GlassFish Wiki : DomainXMLv3Structure

Structure of domain.xml in v3

Structure of domain.xml in v3

ConfigAnalyzer Tool

Download
Run
Output

v3 domain.xml (as of 22 July 2009)
Inconsistencies/Errors in the @Configured Interfaces
Bugs in the Tool itself

There have been several requests for a DTD or other definition for the v3 domain.xml. There cannot really be a static DTD or XSD because the format of the domain.xml file can change as new, unanticipated types of containers are added to a GlassFish installation. The proper structure of domain.xml is therefore dynamic and can only be computed by examining the @Configured interfaces in the GlassFish code base.

ConfigAnalyzer Tool

Still, there is no denying the value in having a static description of the format, even if it is only a snapshot of a given moment in time. To try to meet that need, I've created a very simple tool that analyzes all the @Configured interfaces in JARs you point it to and displays the structure from a given @Configured type and below. I have not (so far) formatted the output as a DTD or XSD but the output information should be at least equivalent to DTD and XSD content.

For example, if you ask the tool to display from

com/sun/enterprise/config/serverbeans/Domain

you will see (in theory) the entire structure of domain.xml.

Download

You can download the ConfigAnalyzer tool from here. Be sure to download the ASM library and save it as lib/ASM.jar relative to where you save the tool itself.

Run

Use

 
        java -jar xxx/ConfigAnalyzer.jar internal-name-of-interface-to-analyze comma-or-space-separated-list-of-JARs-to-analyze 
       

where

xxx

is the path where you downloaded the JAR and

internal-name-of-interface-to-analyze

is the fully-qualified interface name (using slashes, not dots) you want to analyze. You need to specify the list of JARs you want the tool to scan looking for @Configured interfaces. You can specify individual JARs. You can also specify directories, in which case the tool will include all JARs in the directory.

For example, this command will display the format of the entire domain.xml file:

 
        java  -jar xxx/ConfigAnalyzer.jar com/sun/enterprise/config/serverbeans/Domain ${installDir}/glassfishv3/glassfish/modules/ 
       

Output

The tool prints each interface that corresponds to an XML element at the left margin, followed by a list of attributes (if any) and their characteristics (required, default value, etc.). Then comes the list of subelements (if any). The tool derives the name of each subelement from the @Configured interface type returned by the corresponding

get

method defined on the containing interface.

The tool loosely uses regex-style notation for

optional
required-once (no added notation),
required-at-least-once , or
optional-repeating .

For elements defined using

 
        @Element("*")
List<OtherType> getOtherTypes();

the tool displays, for that subelement, a choice of all @Configured interfaces which extend

OtherType

. On that same line the tool also flags the use of the wildcard processing and displays the @Configured interface type which the subelement interfaces extend. Here is partial output from the earlier command anchored at com/sun/enterprise/config/serverbeans/Domain that illustrates this output:

 
        domain
  Attributes:
    application-root
    log-root
    locale
    version

  Subelements:
    applications ?
    system-applications ?
    resources ?
    configs 
    servers 
    clusters ?
    node-agents ?
    lb-configs ?
    load-balancers ?
    system-property *
    property *

applications
  Subelements:
    ( module | ejb-module | appclient-module | connector-module | mbean | server | cluster | lifecycle-module | j-2-ee-application | web-module | config | application | container | extension-module ) * [wildcard type = org/glassfish/api/admin/config/Named returned by getModules]

system-applications
  Subelements:
    ( module | ejb-module | appclient-module | connector-module | mbean | server | cluster | lifecycle-module | j-2-ee-application | web-module | config | application | container | extension-module ) * [wildcard type = org/glassfish/api/admin/config/Named returned by getModules]

resources
  Subelements:
    ( external-jndi-resource | jdbc-connection-pool | custom-resource | mail-resource | admin-object-resource | resource-adapter-config | persistence-manager-factory-resource | connector-resource | work-security-map | jdbc-resource | connector-connection-pool ) * [wildcard type = com/sun/enterprise/config/serverbeans/Resource returned by getResources] 
       

v3 domain.xml (as of 22 July 2009)

Here is the entire analysis of the v3 domain.xml elements, using the above command, as of this writing.

There seem to be some inconsistencies in the way some of the @Configured interfaces are defined. What I've seen so far are @Configured interfaces that do not extend the correct parent interface, or methods defined on @Configured interfaces that seem to return an overly-general type. I've started a table below recording them based on my quick looks so far. There might be more; if you find any please add them to the table.

As for actually changing the definitions, we probably need to be careful because of how important these interfaces are to the server's operation. Code reviews involving Jerome and/or the admin team are probably in order.

Inconsistencies/Errors in the @Configured Interfaces

@Configured interface/method	Issue	Status
Applications#getModules	returns List<Named> ; should return List<Module> instead? currently returns types that are not really modules (cluster, server, container) but are Named
SystemApplications#getModules	returns List<Named> ; should return List<Module> instead?
ServerRef	should also extend Ref; it does not so it is excluded from lb-config subelements; what is currently cluster-ref * should be (cluster-ref \| server-ref) *

Bugs in the Tool itself

Problem	Status