Domain Management in JOnAS

The content of this guide is the following:

1. Target Audience and Rationale
2. Domain Management Goals
3. Mechanisms used by Domain Management
4. How to start Servers in a Domain
5. How to define domain configuration using domain.xml file

Target Audience and Rationale

This guide is intended for JOnAS administrators responsible for the configuration and administration of JOnAS servers running within a management domain.

Domain Management Goals

A JOnAS management domain is composed of a set of JOnAS servers that are running under the same management authority and are identified by a domain name.

The servers in a domain can be administered by a management application running on one server (or several) in the domain; this is the role of administrator or master. The managed servers play the role of slaves.

Typically, when deploying the JonasAdmin application on a slave, the administrator can manage only the server on which the application is running. When deploying JonasAdmin on a master server, the administrator can manage all the servers in the domain: the administrator can see all the servers started in the domain, apply management operations (currently applications or modules deployment) to one or more servers in the domain, and finally, switch management from the master to any other server in the domain.

Starting with JOnAS 4.7, domain management is enhanced with cluster management facilities. A cluster is a group of servers having common properties within a domain. A cluster may be the target of a domain level management operation - currently applications and modules deployment only. Moreover, clusters may be nested. Domain topology (servers and clusters composing the domain) can be defined using a new domain.xml configuration file.

Mechanisms used by Domain Management

Basically, domain management in JOnAS relies on JSR 160 specification. When a JOnAS server is started, it creates at least one JSR 160 connector server as explained in JSR 160 support in JOnAS.

A connector server makes it possible for a JMX remote API client to access and manage the MBeans exposed through the MBean server running in a remote JVM. In order to establish a connection, the remote client needs to know the address of the connector server. JSR 160 does not provide any specific API that would make it possible for a client to find the address of a connector server. The standard suggests using existing discovery and lookup infrastructures; for instance, JNDI API with a LDAP back end.

A new service added to JOnAS, the Discovery Service, allows JOnAS servers running over a LAN within the same management domain to communicate to each other the connector-server addresses they create at start-up. All the servers in the domain having the discovery service in the services list, will publish their connector-server address at start-up. The goal is to allow master servers to discover which servers are running in their domain, and to establish connections allowing them to remotely manage the slave servers by a management application deployed on a master server.

Starting with JOnAS 4.7, a server can be added to a domain via a management operation, thus allowing servers which cannot use the multicast-based discovery service to join a management domain.

The current discovery service implementation is based on MBeans (called discovery MBeans) which use:

• IP Multicast protocol to communicate their connector-server addresses and state transitions to each other.
• JMX notifications to update domain management information within a master server.

J2EEDomain MBean

The J2EEDomain MBean has the following JMX ObjectName:

		domainName:j2eeType=J2EEDomain,name=domainName
	

A J2EEDomain MBean contains several management attributes and operations related to servers management in a domain:

• If the J2EEDomain is registered in a master server's MBean server, the servers attribute keeps the list of the servers running in the domain. Otherwise, it contains only one element corresponding to itself. The elements in the servers list are Strings representing J2EEServer ObjectNames associated to the running servers. By iterating over the servers list, a management application can determine the name of the servers in the domain.
• The getConnectorServerURLs operation returns the connector server addresses for a server in the list.

  In order to administer a given server in the domain, any management application has to create a MBeanServerConnection object using one of the connector-server addresses corresponding to that server (see the j2eemanagement sample).

Starting with JOnAS 4.7, the J2EEDomain MBean was enriched in order to support adding/removing a server to/from the domain, creating a cluster in the domain, listing the clusters in a domain.

Note that clusters are implemented as "sub-domains", they have associated J2EEDomain type MBeans. For example, if a cluster named clust is created in the domain named domainName, it has an associated MBean with the following JMX ObjectName:

		domainName:j2eeType=J2EEDomain,name=domainName,clusterName=clust,parentClusterName=domainName
	

Another new feature is servers state management. When adding a server to a domain (or cluster), it may be in STARTED state if a remote JMX connection can be established, or STOPPED state if not.

The following is a list of some of the new management attributes and operations exposed by a J2EEDomain MBean:

• addServer(String serverName, String[] connectorServerURLs)
• getServerState(serverName)
• createCluster(String clusterName)
• clusters attribute gives the String representation of the J2EEDomain ObjectNames associated to the clusters created in this domain (or in this cluster if the current J2EEDomain MBean is associated to a cluster).

Domain management information in JMX service

The JMX service, as the J2EEDomain MBean, implements mechanisms that update information about the servers running in the current domain, and creates ready-to-use MBeanServerConnection connection objects. The JonasAdmin application, for example, uses these connection objects via the JonasManagementRepr helper class.

How to start manageable servers in a Domain

The servers must adhere to these rules:

• The servers must be started on hosts connected by a LAN.
• The servers must be configured with the discovery service activated (see Configuring Discovery Service).
• There must be at least one master server in the domain. The role of a server, slave or master, is determined by the discovery service configuration.
• The servers must have different names, but the same domain name.

Also note the following:

• Servers may be started in any order.
• Servers may join or leave the domain at any time. Domain management information is updated on the master server(s).
• A slave server may become master by invoking the startDiscoveryMaster management operation exposed by the discovery service. This operation can be invoked using the JonasAdmin management console deployed on a master.

Example

Consider a scenario in which there are three JOnAS servers named jonas, j1 and j2. Assume that they have discovery service configured with at least one of the servers playing the role of master.

• Start the server named jonas in domain jonas (by default, the domain name is given by the server's name)

		jonas start
	

• Start the server named j1 in domain jonas

		jonas start -n j1 -Ddomain.name=jonas
	

• Start the server named j2 in domain jonas

		jonas start -n j2 -Ddomain.name=jonas
	

How to define domain configuration using domain.xml file

A default domain configuration is provided in $JONAS_ROOT/conf/domain.xml. This configuration corresponds to a domain named jonas managed by a master server also named jonas. The location tag defines a JMX remote connector server URL for this server.