Sun GlassFish Enterprise Server v3 Domain File Format Reference

About the domain.xml File

The domain.xml file contains most of the Sun GlassFish Enterprise Server configuration. The domain.xml file is located in the domain configuration directory, which is typically domain-dir/config.

There is no DTD file or schema that determines the format of the domain.xml file. The server's configuration is dictated by the Java interfaces with appropriate annotations and domain.xml serves as a seed for that configuration. At any point in time, the overall structure of an XML element present in domain.xml is clearer when one sees the Java interface in the package com.sun.enterprise.config.serverbeans. Thus these Java interfaces take the place of the DTD file in previous releases.

This file is further described in the following sections:


Note –

Settings in the Enterprise Server deployment descriptors override corresponding settings in the domain.xml file unless otherwise stated. For more information about the Enterprise Server deployment descriptors, see the Sun GlassFish Enterprise Server v3 Application Deployment Guide.


Verification

To verify that the structure and content of the domain.xml file are correct, use the asadmin verify-domain-xml command. To use this command on the default domain in the default location, simply type asadmin verify-domain-xml at the command line. Any errors found are printed on the screen. For more information about this command, see verify-domain-xml(1).

Extensibility

If you create new add-on components for the Enterprise Server, you can add any configuration these components require to the domain.xml file. For more information on extending the Enterprise Server by creating add-on components, see the Sun GlassFish Enterprise Server v3 Add-On Component Development Guide.

Backup

A backup of the domain.xml file is created whenever the configuration is changed using the Administration Console or the asadmin command. The backup file is located in the domain configuration directory, typically domain-dir/config, and is named domain.xml.bak. If you make a mistake editing the domain.xml file, you can overwrite it using the backup file.

Default Values

In this manual, the term default is used in its broader sense, and not in the specific way it is used in the XML 1.0 standard. A default value is an initial value or the value used if no value is present in the XML file. A default value can be any of the following:


Note –

Removal of initial values in domain.xml is not recommended because attributes may be left without values or values may revert to internal defaults. Explicitly changing values is recommended.

Only values that differ from internal defaults are included in the domain.xml file.


Variables

Variables and variable references are needed for two reasons:

Variable references appear in the domain.xml file as strings that begin with the characters ${ and end with the character }. For example, the string ${com.sun.enterprise.myVar} is a reference to the variable com.sun.enterprise.myVar .

Variables are defined both outside of and within domain.xml. Predefined variables that exist outside of domain.xml are defined as Java System Properties. Within domain.xml, a variable is defined using the system-property element or the jvm-options element.

The system-property element’s name attribute is the name of a variable; its value attribute is the definition of the variable. For example, the following system-property element defines a port-number variable with the value 6500:

<system-property name="port-number" value="6500"/>

Multiple system-property subelements are permitted within server, config, and domain elements.

A variable defined in the jvm-options element is a Java System Property with the -D flag. For example, the following jvm-options element defines a port-number variable with the value 5500:

<jvm-option>-Dport-number=5500</jvm-option>

Multiple definitions for the same variable are permitted. The Enterprise Server determines the actual value of a variable by searching for its first definition in a strict hierarchy of the elements within domain.xml. The hierarchy is as follows:

server -> config -> jvm-options -> domain -> System

Implicit in this hierarchy is the notion of reference and containment. A variable referenced in a server element is only looked up:

Element Referencing

One element references another when an attribute of the referencing element has the same value as an attribute of the referenced element. For example, the application-ref element references an application that is deployed to its parent server element. The application-ref element’s ref attribute has the same value as the name attribute of an application element.

The referencing application-ref element might look like this:

<application-ref ref="MyServlet"/>

The referenced application element might look like this:

<application name="MyServlet" location="myservletdir"/>

Element Hierarchy

The element hierarchy for the domain.xml file is as follows. To make the hierarchy more readable, elements having property as their last or only subelement are marked with a P, and the property subelements are not shown. Parent/child relationships between elements are shown, but not cardinality. For those details, see the element descriptions.

domain P
.    system-applications
.    .    application P
.    .   .    engine P
.    .   .    module
.    .   .    .    engine P
.    .   .    .   .    web-module-config
.    .   .    .   .    .    env-entry
.    .   .    .   .    .    .    env-entry-name
.    .   .    .   .    .    .    env-entry-type
.    .   .    .   .    .    .    env-entry-value
.    .   .    .   .    .    context-param
.    .   .    .   .    .    .    param-name
.    .   .    .   .    .    .    param-value
.    applications
.    .    application P
.    .   .    engine P
.    .   .    module
.    .   .    .    engine P
.    .   .    .   .    web-module-config
.    .   .    .   .    .    env-entry
.    .   .    .   .    .    .    env-entry-name
.    .   .    .   .    .    .    env-entry-type
.    .   .    .   .    .    .    env-entry-value
.    .   .    .   .    .    context-param
.    .   .    .   .    .    .    param-name
.    .   .    .   .    .    .    param-value
.    .    lifecycle-module P
.    .    j2ee-application P
.    .    web-module P
.    .   .    web-service-endpoint
.    .   .    .    registry-location 
.    .   .    .    transformation-rule 
.    .    ejb-module P
.    .   .    web-service-endpoint 
.    .   .    .    registry-location 
.    .   .    .    transformation-rule 
.    .    connector-module P
.    .    appclient-module P
.    .    extension-module P
.    resources
.    .    custom-resource P
.    .    external-jndi-resource P
.    .    jdbc-resource P
.    .    mail-resource P
.    .    admin-object-resource P
.    .    connector-resource P
.    .    resource-adapter-config P
.    .    jdbc-connection-pool P
.    .    connector-connection-pool P
.    .   .    security-map
.    .   .    .    principal
.    .   .    .    user-group
.    .   .    .    backend-principal
.    .    work-security-map
.    .   .    principal-map
.    .   .    group-map
.    configs
.    .    config P
.    .   .    http-service P
.    .   .    .    access-log
.    .   .    .    virtual-server P
.    .   .    .   .    http-access-log
.    .   .    network-config
.    .   .    .    transports
.    .   .    .   .    selection-key-handler
.    .   .    .   .    transport
.    .   .    .    protocols
.    .   .    .   .    protocol
.    .   .    .   .    .    http
.    .   .    .   .    .    .    file-cache
.    .   .    .   .    .    port-unification
.    .   .    .   .    .    .    protocol-finder
.    .   .    .   .    .    protocol-chain-instance-handler
.    .   .    .   .    .    .    protocol-chain
.    .   .    .   .    .    protocol-filter
.    .   .    .   .    .    ssl
.    .   .    .    network-listeners
.    .   .    .   .    network-listener
.    .   .    iiop-service
.    .   .    .    orb P
.    .   .    .    ssl-client-config 
.    .   .    .   .    ssl  
.    .   .    .    iiop-listener P
.    .   .    .   .    ssl  
.    .   .    admin-service P
.    .   .    .    jmx-connector P
.    .   .    .   .    ssl  
.    .   .    .    das-config P
.    .   .    connector-service
.    .   .    web-container P
.    .   .    .    session-config
.    .   .    .   .    session-manager
.    .   .    .   .    .    manager-properties P
.    .   .    .   .    .    store-properties P
.    .   .    .   .    session-properties P
.    .   .    ejb-container P
.    .   .    .    ejb-timer-service P
.    .   .    mdb-container P
.    .   .    jms-service P
.    .   .    .    jms-host P
.    .   .    log-service P
.    .   .    .    module-log-levels P
.    .   .    security-service P
.    .   .    .    auth-realm P
.    .   .    .    jacc-provider P
.    .   .    .    audit-module P
.    .   .    .    message-security-config
.    .   .    .   .    provider-config P
.    .   .    .   .    .    request-policy
.    .   .    .   .    .    response-policy
.    .   .    transaction-service P
.    .   .    monitoring-service P
.    .   .    .    module-monitoring-levels P
.    .   .    java-config P
.    .   .    .    profiler P
.    .   .    .   .    jvm-options
.    .   .    .    jvm-options
.    .   .    thread-pools
.    .   .    .    thread-pool P
.    .   .    system-property
.    .   .    jruby-container
.    .   .    .    jruby-runtime-pool
.    servers
.    .    server P
.    .   .    application-ref
.    .   .    resource-ref
.    .   .    system-property
.    system-property