June.Parks_at_Sun.COM wrote:
> I don't see why there can't be a DTD or equivalent that covers all the
> possibilities available for the most inclusive distribution at the
> time of the release. Those who lack some modules won't be interested
> in what they've elected not to have anyway. Add-on modules that add
> to domain.xml should provide documentation of the additions. Why
> can't this be done?
>
> If GlassFish Engineering insists that a definitive DTD is not
> possible, then I don't see any point in publishing a book on the
> domain.xml file.
The main point I intended to make earlier is that we cannot use a single
definition (DTD or XSD) for runtime validation in every GlassFish
installation, due to users' ability to refine their installation by
adding or removing modules. Your point that users could disregard parts
of the documentation for the all-inclusive domain.xml is certainly valid.
The existing text description of the config information, reachable from
the wiki page, is indeed a description of the most inclusive set of XML
elements that would be available in a default installation of GlassFish
as it is distributed today. I'm sorry if I didn't make that clear earlier.
> There's no way I can get reliable information, therefore I can't write
> the book with any certainty of its accuracy. I've tried to make do
> with scraps of information, but it looks like what I need to do an
> adequate job is not forthcoming.
The tool I hacked together over the weekend provides precisely this sort
of overall and complete picture based on the actual Java source. It
should be very reliable. There are a few problems I noticed which I
noted on the wiki page. As I offered in our other mail conversation,
I'll send you a revised copy of the text description that reflects the
fixes to those problems. My call to action to the module leads at the
start of this thread was for them (us!) to review the @Configured Java
interfaces to make sure the source accurately reflects what we want.
That means there could be more corrections coming.
>
> If Engineering is developing some kind of configuration extraction
> process with @Documentation annotations, or whatever form
> user-readable comments take, great, I'm willing to help edit those
> comments. As for documenting domain.xml in book form, as I have done
> for several releases now, I don't think I can continue under these
> circumstances.
I hope you're convinced otherwise after reading this. Granted, given
what it has to work with today the tool cannot give you a
fully-commented DTD or XSD as we had in v2. Adding the @Documentation
annos to the Java interfaces (and making related enhancements to the
tool) could go a long way toward fixing that but clearly that's not
there yet.
- Tim
>
> June
>
> On 06/23/09 12:24, Tim Quinn wrote:
>> Vince Kraemer wrote:
>>> Tim Quinn wrote:
>>>> From time to time there have been requests for DTDs or XSDs for the
>>>> v3 domain.xml. But because the content of domain.xml is variable,
>>>> depending on what modules are installed, this is not really feasible.
>>>
>>> Since xml means eXtensible Markup Language, if have to wonder why
>>> you say this..
>>>
>>> It seems like we should be able to use schemas to create a complex,
>>> dynamic document that can be more validated than, "Is this document
>>> well-formed?"
>>>
>>> What is the impediment that makes it not really feasible?
>> My point - poorly-stated, perhaps - is that we cannot publish a
>> single authoritative and complete DTD or XSD on, say, a Glassfish web
>> site, that will apply to all GlassFish installations, nor can we ship
>> such a thing for installation with GlassFish itself. Different
>> GlassFish installations will (eventually) include different
>> combinations of modules depending on what types of apps those users
>> want to support, and even that set can change over time for a single
>> installation.
>> The acceptable contents of the domain.xml file can therefore be
>> different for different installations of GlassFish. Hence a single,
>> installed or centrally-published DTD or XSD does not suffice.
>> That's all I meant.
>> As for validation, in practice the GlassFish configuration subsystem
>> does "validate" the domain.xml when it loads the configuration into
>> memory during start-up. The elements in the XML file correspond
>> directly to Java interfaces marked with the @Configured annotation.
>> Each interface's methods, annotated with @Attribute or @Element,
>> define the corresponding element's attributes and subelements that
>> will be permitted in the XML. The config subsystem will complain
>> when it finds an XML element, subelement, or attribute that the
>> interface definitions do not declare. It's not validation against an
>> XSD, but it is validation in a different sense.
>> - Tim
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe_at_glassfish.dev.java.net
>> For additional commands, e-mail: dev-help_at_glassfish.dev.java.net
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: dev-help_at_glassfish.dev.java.net
>