Jerome,
Thanks for taking the time to start the process of a "Getting
Started" guide. I think it will help a lot for those approaching V3--
I know reading it has helped me understand the big picture better.
Specific comments, nearly all intended to result in modifications to
the document--
0) Consider splitting off some of the more specific material into
other docs (build stuff, admin commands, jdbc).
1) "For instance, you may depend on the com.sun.enterprise:config-api
(name of the module constructed from a group id and an artifact id)
to get the configuration out of the domain.xml"
What's a "group id" and "artifact id"? These are not defined prior
to reading this. (perfect examples of where a hyperlink would add
value).
2) Is there a module template (complete set of stuff from which a
module could be created by changing classnames)?
3) How do I go about compiling a module in terms of setting my
classpath for compilation?
4) What's a "generalist introduction"? An introduction by a
generalist? :)
5) Should a module be created to do something like start the
MBeanServer? (I don't think so, since the MBeanServer can be created
even before main()).
6) You must explain terms like "distribution artifact"! The meaning
of such terms cannot be assumed.
7) A lot more hyperlinks are needed throughout; not everyone knows
everything and certainly very, very few people will be familiar with
everything mentioned in the document.
8) Grammar/spelling: "necessitate three steps", "out of integration",
"depende", "complete lists of dependencies", "basically free", "with
a module like its HK2 manifest entries", "The bootstrap module which
is not a real module since", "difficult, but moreover, does not
necessarily mean", "called contract", "handfull",
9) Smart quotes “hello” vs "hello", except in code examples.
10) "As you can see, distributions are constructed out of integration
of binary files procured from a maven repository,".
No I can't really see from the description; I can only see if I
already understood all the complicated steps described. Don't waste
space with verbage like "as you can see"-- instead take space and
*explain* in more detail. Or at least strike "As you can see", which
might be completely false for the reader!
11) "Each module can be integrated in various distributions" =>
Clarification is needed that version and distribution are orthogonal
terms.
How does one compile a module that depends on module(s) that are part
of a particular distribution if it cannot depend on such?
12) Why is it "src/main/java"? Why not just "src"? (Since 99% of the
time it's always java). Why is "main" in there?
13) Why are "resources" in "src/resources"? Isn't "src" *source
code*, not data?
14) Don't say "constructed from a group id and an artifact id" when
you mean "constructed from a maven pom.xml <groupId> and
<artifactId>". Use consistent terminology, not paraphrased terms;
it's confusing!
15) Is it "hk2" or "HK2"? What do "H" and "K" and "2" stand for?
Explain terms the first time they are used (minimum), or hyperlink
into a glossary.
16) Section numbers and titles are indented nearly half way into the
page.
17) Need link for how to "publish the module binaries to a maven
repository": how to do it, what the expected artifacts are, etc.
18) Use the same font as for code snippets for code-like terms such
as "pom.xml", class names like "ModuleStartup",
"com.sun.enterprise:v3-core", etc.
19) PDF has broken 2.6.2 listing awkwardly, wrapping lines around.
20) "Each distribution will have a dashboard wiki page" => So do
those pages not yet exist?
21) "Each distribution will have a contributors dashboard" => When is
this planned to be done and who coordinates it?
22) "GlassFish is now an HK2 executable..." => What does that mean?
23) "glassfish-{Version}.jar" => Is that just a major version number
eg "V3"?
24) "When embedded, GlassFish V3 startup sequence is..." => Embedded
in what for example? Slightly more clarity is needed eg "When
embedded in another JVM (such as the NetBeans IDE), ...". Can this
actually be done today? Aren't classloading requirements tricky
somehow with lots of modules?
25) "If all the modules forming a GlassFish distribution were
referencing each other, the entire set of modules would be loaded at
startup basically erasing all the modularization advantage" => And
what are those advantage(s)? Startup speed? JVM footprint?
26) "POJO" => "POJO (Plain Old Java Objects). Don't assume everyone
(especially speakers in another language) will grasp every acronym.
In this case, use of an acronym is a step backwards.
27) The use of "services" and "Services" in the same paragraph is
confusing. Are these the same thing? Or a specific and a generic idea?
28) "one to many" => "one-to-many"
29) Very confusing paragraph: "Even if v3-core module does not import
directly...". Rephrase.
30) "can also bring up other modules" => What does "bring up" mean,
exactly?
31) "on the grizzly module" => is "grizzly" a proper noun ("Grizzly")
or an adjective here?
32) More explanation of @Contract is needed. Does it designate a
service (Service?) ?
33) "A new type of service or contract..." => Which one? Is it a
Service or a Contract? A concept or a class? "New" in what sense?
Confusing. Reading 3.2.3 (which follows) helps. You need to say
*how a Service is actually defined*! From what I gather, a Service
must implement one or more interfaces which has been annotated with
@Contract. True?
34) "implementing a contract" => Meaning "implementing an interface
annoted with @Contract"?
35) Where is interface "PostConstruct" defined? What is it's
relevance to 3.2.3?
36) Don't show an example first and foremost, then say it's
"discouraged"! Show the best practice *first*, and don't show the
discouraged practice at all!
37) The explanation of @Configured, @Attribute, @Element is almost a
foregone conclusion: take the time to explain *exactly* what these
things do! Don't assume implicit knowledge!
38) Section 3.3 needs some subheadings; it's very dense and hard to
follow as-is. Seems to jump around topics a great deal. Too hard to
read.
39) Sections 4, 5, 6 seem like they belong in documents of their own.
Please use HTML so others can updated/edit/improve and link to
internal targets in the document.
Lloyd
---
Lloyd L Chambers
lloyd.chambers_at_sun.com
Sun Microsystems, Inc
On Oct 12, 2007, at 3:00 PM, Jerome Dochez wrote:
> Hi All
>
> I have written a short document that gives an overall idea on how
> V3 is or will be architectured and gives some tips and information
> on how to work with modules and maven 2.
>
> This document will continue to evolve substantially so feedback is
> greatly appreciated.
>
> Find it in the main V3 wiki page.
>
> http://wiki.glassfish.java.net/Wiki.jsp?page=PlanForGlassFishV3
>
> Jerome
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: dev-help_at_glassfish.dev.java.net
>
---
Lloyd L Chambers
lloyd.chambers_at_sun.com
Sun Microsystems, Inc