Introduction to the GlassFish Domain and Domain Model
By Shreedhar Ganapathy on Oct 10, 2006
Much of the contents in this blog apply to GlassFish V2(with clustering support).
The GlassFish Project's application server comes with a very nice browser-based Administration console and a rich command line interface. Behind these easy-to-use interfaces lies the JMX compliant administration infrastructure that instruments management of these configurational entities and makes it possible to configure, operate and perform lifecycle operations on the server. At the heart of it all is the domain configuration model that provides the basis for the domain.xml configuration repository wherein lies the values applied to a given domain's configuration.
The concept of a domain in GlassFish can be related to an administrative area. Under a domain, one can have standalone instances (and with GlassFish v2, cluster(s) of instances). The administrator, thus, configures and manages all the operational aspects of the instances/clusters under a given domain through the Domain Administration Server (DAS). A domain can span multiple machines. Instances belonging to a domain can be located on multiple machines. Each machine's instances are started/stopped by a lightweight java process called the node-agent. The node-agent performs operations requested by the DAS such as starting or stopping one or more instances it is managing on a specific machine. Additionally, the node agent synchronizes configuration state between the DAS and the instances it manages.
A domain can have standalone instances and/or cluster(s) of instances. Java EE (J2EE) applications can be deployed to the domain, a specific instance, or a specific cluster. An already deployed application can be referenced by an instance or cluster by creating references to the application deployed on the domain. When as application is deployed to a specific instance, the application is placed in the domain level and an application-ref is created under the specific instance. Similarly, resources such as jdbc resources and related connection pools can be deployed/created at the domain level, a specific instance or a specific cluster. A resource that already exists can be used by other instances by creating a resource reference to the resource on the domain. When a resource is deployed to a particular instance, then the resource is created at the domain level and a resource-ref is created in the instance referencing the resource in the domain.
All of the above functionality is based on the foundations provided by our domain model. The domain model is specified in the domain dtd. The dtd specifies configuration artifacts and their related attributes and sub-elements, through a pseudo hierarchical and largely referential structure. At the top level is the domain element under which all configurational elements lie.
Below, these subelements are explained for more information.
The domain can comprise of a set of 'applications', 'resources', 'configs', 'servers', 'clusters', 'loadbalancers', 'lb-configs' and 'node-agents'. These are subelements of the top level root element 'domain'. In addition, special token value elements called 'system-property' and name-value pair elements called 'property' can be defined in the domain and at all sub levels for customization and extension.
The element 'configs' comprises of a set of 'config' subelements each of which is a set of configurational elements such as 'http-service', 'iiop-service', 'jms-service', etc.
A 'config' can be shared by one or more 'servers' through references('config-ref'). In other words, a particular configuration can be referenced by one or more instances but customized for specifics like port, etc through 'system-property' definitions under that particular instance.
The element 'node-agents' comprises of one or more 'node-agent' entities which are lightweight java processes living on specific machines that are part of the administrative domain as explained in the earlier paragraphs. The 'node-agent' manages the lifecycle of the instances that are installed on the machine it manages. The node agent plays an important role in synchronizing the configuration state from the domain administration server with the instances it manages.
The element 'servers' comprises of one or more sub-elements of type 'server' referring to an individual instance.
Each 'server' instance references a 'config' through the attribute 'config-ref'. By default, creating an instance results in a '<instance-name>-config' being created with auto selected ports representing that particular instance's configuration. This config could be shared as explained above by referencing in another instance.
The subelement 'applications' comprises a set of application types that are deployed to the particular domain or instance or cluster.
An application can be any of several recognized types, namely, j2ee-application, web-module, ejb-module, connector-module, appclient-module, lifecycle-module and mbean.
When an application is deployed in GlassFish, it is placed in the domain and made available to instances through 'application-ref'. In other words, instances ('server' elements) reference an application through the subelement 'application-ref'.
The subelement 'resources' comprises a set of resource types that go to support the application deployed. Several recognized types of resources are defined in the domain dtd most common of which are 'jdbc-resource', 'connector-resource', jdbc-connection-pool', 'connector-connection-pool', 'persistence-manager-factory-resource', 'resource-adapter-config', etc.
Resources are referenced by the instances through resource-refs. In other words, a particular 'server' would reference resources applicable to it by the subelement 'resource-ref'.
In a later blog, I will explain the loadbalancers and lb-configs elements.