# Enable the Security context propagation for jrmp
jonas.security.propagation    true

# Enable the rmi Security manager
jonas.security.manager    true

# Enable csiv2 security propagation for rmi/iiop
jonas.csiv2.propagation    true

# Enable the Transaction context propagation
jonas.transaction.propagation    true

#  Set the name of log configuration file to trace.properties
jonas.log.configfile    trace

Properties are self commented.

	Note
	setting jonas.security.manager to false implies a colocated registry and implies to set in carol.properties: carol.jvm.rmi.local.registry=true

Here is the list of default services activated at starting time:

jonas.services    registry,jmx,jtm,db,security,mail,wm,resource,ejb2,ejb3,ws,web,ear,depmonitor

The possible services are:

registry,jmx,security,jtm,db,mail,wm,wc,dbm,resource,cmi,ha,ejb2,ejb3,ws,versioning,web,ear,depmonitor,discovery

Services will be started in the order in which they appear in the list. Therefore, the following constraints should be considered:

registry can be omitted from the list because this service is automatically launched if it is not already activated by another previously started server. This is also true for jmx, since it is automatically launched after the registry.

Configuration parameters for services follow a strict naming convention: a service XX will be configured via a set of properties:

###################### JOnAS JTM Transaction service configuration
#  Set the name of the implementation class of the jtm service
jonas.service.jtm.class    org.ow2.jonas.tm.jotm.JOTMTransactionService

#  Set the Transaction Manager launching mode.
#  If set to 'true', TM is remote: TM must be already launched in an other JVM.
#  If set to 'false', TM is local: TM is going to run into the same JVM
#  than the jonas Server.
jonas.service.jtm.remote    false

#  Set the default transaction timeout, in seconds.
jonas.service.jtm.timeout    60
            

see Section 2.4, “Configuring JOnAS Services” for a complete description of the services configuration.

carol.protocols=jrmp 
carol.jrmp.url=rmi://localhost:1099 
carol.jvm.rmi.local.call=false 
carol.jvm.rmi.local.registry=false 
carol.jrmp.server.port=0 
carol.jrmp.interfaces.bind.single=false 

The JacORB implementation of RMI over the IIOP is used. The configuration file of JacORB is the $JONAS_BASE/conf/jacorb.properties file.

As for the other protocols RMI over IIOP is ready to used in the default distribution. It is only for tuning purpose that the $JONAS_BASE/conf/jacorb.properties file must be customized.

By default the CORBA Naming service is run using the port 2001 (as it is set in the carol.properties file)

So the only thing to do for working in RMI over IIOP is to set the property protocols in carol.properties:

carol.protocols=iiop
# RMI IIOP URL
carol.iiop.url=iiop://localhost:2001
carol.iiop.server.port=0 
carol.iiop.server.sslport=2003 
carol.iiop.PortableRemoteObjectClass=org.objectweb.jonas_lib.naming.JacORBPRODelegate  

carol.protocols=irmi
carol.irmi.url=rmi://localhost:1098 
carol.irmi.server.port=0 
carol.irmi.interfaces.bind.single=false 

	for irmi the default port is 1098
	exported objects will listen on this port for remote method invocations:0 means random port. Caution if the port is set to n the port 'n + 1' will be used by the JMX server.So, for the firewall configuration, you have to open the port numbers 'n' and 'n+1'
	if true use only a single interface when creating the registry (specified in carol.irmi.url property). Default configuration = false(use all interfaces available)

CMI is the component to use for clustering purpose. It is embedded in the component CAROL.

CMI is just composed of wrappers and interceptors and is fully independant of the implementation of protocol. CMI relies on JGroups group-communication protocol for ensuring the replication of the cluster view. CMI provides jndi high availability, the load-balancing and fail-over at the EJB level.

For using CMI with a protocol (in addition to the activation of service cmi), a property must be added in carol.properties:

carol.jrmp.cmi=true 
carol.iiop.cmi=true
carol.irmi.cmi=false 

	Note
	By default, the property is set at true.

JOnAS can be configured to use several protocols simultaneously. To do this, just specify a comma-separated list of protocols in the carol.protocols property of the carol.properties file. For example:

carol.protocols=iiop,jrmp
carol.jrmp.url=rmi://localhost:1099
carol.iiop.url=iiop://localhost:2001

	Caution
	When iiop is used in a multiprotocol configuration, it must appear at the first position in the protocol list.

If Monolog is configured to use the JDK logger it will replace the JDK logger implementation with its own implementation and so all JDK logs are intercepted by Monolog. By default Monolog is configured to use the JDK logger.

There is no special configuration file for Jakarta commons login.If it is used on top of the java logging API it is the same case than the previous section.

JOnAS don't provide the corresponding jar file so, log4j must be packaged (.jar file and log4j.properties) in any application that want to use it. The log4j.properties file must be configured correctly.

If log4j is used by several applications it is possible to centralize the log4j configuration by putting log4j.properties in $JONAS_BASE/conf and log4j jar file in $JONAS_BASE/lib/commons.

In the JOnAS distribution several templates of datasource.properties files are provided one for Oracle, PostgreSQL, Sybase, DB2, MySQL, HSQLDB, InterBase, FirebirdSQL, Mckoi SQL, InstantDB ) respectively in Oracle1.properties, PostgreSQL1.properties etc...

A complete description of the datasource.properies file can be found inSection 2.8, “Configuring JDBC DataSources”

You have to provide initialization parameters in jonas.properties file for:

Example:

jonas.service.discovery.multicast.address=224.224.224.224
jonas.service.discovery.multicast.port=9080
jonas.service.discovery.ttl=1
#  For a master server, configure the client source port with this property
jonas.service.discovery.source.port=9888

#  A multicast greeting message is sent out when discovery service is started.
#  The starting server listens at the port jonas.service.discovery.greeting.port
#  (default 9899) for a response for jonas.service.discovery.greeting.timeout miliseconds
#  (default 1000 ms). If a pre-existing server has the same server name as this one,
#  this server's discovery service will be terminated.
jonas.service.discovery.greeting.port=9899
jonas.service.discovery.greeting.timeout=1000

JGropups configuration being more complex, a specific configuration file have to be used. The name of this file is given by the jonas.service.discovery.jgroups.conf property. Two other properties have to be initialized:

Example:

jonas.service.discovery.jgroups.conf=jgroups-discovery.xml
jonas.service.discovery.group.name=JGroupsDiscovery
jonas.service.discovery.group.reconnection.timeout=5000

You can find in JOnAS distribution, under JONAS_ROOT/conf, a jgroups-discovery.xml file. This file containes a JGroups stack configuration for the UDP protocol.

In order to be detected by a master server, a cluster daemon has to be properly configured. This is achieved by using a discovery entry in the clusterd.xml configuration file. The configuration properies are:

Example:

  <discovery>
    <group-name>JGroupsDiscovery</group-name>
    <stack-file>jgroups-discovery.xml</stack-file>
    <start-up>true</start-up>
  </discovery>

A template MailSession1.properties file is supplied in $JONAS_BASE/conf. It contains two mandatory properties :

#Factory Name/Type
mail.factory.name mailSession_1
mail.factory.type javax.mail.Session

The JNDI name of the mail factory object is mailSession_1. This template must be updated with values appropriate to your installation. See the section "Configuring a mail factory" below for the list of available properties.

A template MimePartDS1.properties is supplied in $JONAS_BASE/conf. It contains two mandatory properties :

#Factory Name/Type
mail.factory.name mailMimePartDS_1
mail.factory.type javax.mail.internet.MimePartDataSource

The JNDI name of the mail factory object is mailMimePartDS_1. This template must be updated with values appropriate to your installation. See the section "Configuring a mail factory" below for the list of available properties.

Here are the possible properties

This service has been designed for dynamic redeployment of applications, without any application downtime and without users' sessions being lost:

The versioning service achieves this by adding virtual contexts to all services that provide support for versioning. To use the versioning service:

When the versioning service is enabled, application resources (web pages, EJBs, etc.) are accessed the following way:

This can be schematized as follows:

The current limitations of the versioning service are:

As this service allows seamless and interruptionless upgrade and test of all applications, it is strongly recommended for all applications to refer version identifiers in their manifest files. Remember that ANT, Maven as well as most IDEs can set any MANIFEST attribute automatically.

We will now detail the way versioning works by creating two versions of the Java EE 5 Sample Application in the JOnAS examples folder: version 1.0.0 and version 1.0.1. Since the application is an EAR, we only need to refer the version identifier in the EAR file.

When the first version of the EAR is deployed:

Therefore, when a user accesses the /javaee5-earsample URI, the content seen is the same as the one on /javaee5-earsample-version1.0.0.

We now deploy the second version of the application, version 1.0.1, via the JOnAS Web Admin panel. When the second version is deployed, it is bound to the virtual URI as Reserved (this is the default policy and can be modified via JMX at any time). This means that the only way of accessing the 1.0.1 version of the application is to type as URI /javaee5-earsample-version1.0.1. All visitors of /javaee5-earsample will still access the version 1.0.0.

To change the access policies of each version of the virtual URI (the only URI end users are expected to access), go to the list of Web Containers in the JOnAS Web Admin panel. If you set the version 1.0.0 as Disabled and the version 1.0.1 as Default:

When the first version of the EAR is deployed:

Therefore, when a user looks up for the myStateless bean, the reference received is the same as the one received when javaee5_earsample_version1.0.0/myStateless is looked up.

The behaviours of the Web and EJB services when the version 1.0.1 is deployed are similar, except for one very important point: when multiple applications are packaged together, the only versions of the applications they've been tested against are the versions inside the same EAR. Therefore, blindly accessing the Default version of the EJBs could have unexpected results. This is why the concept of versioned EJB clients has been created:

This can be schematized as follows:

As with the versioned Web Applications, to change the access policies of each version of the virtual JNDI container (which knows the JNDI names end users are expected to access), go to the list of EJB Containers in the JOnAS Web Admin panel. If you set the version 1.0.0 as Disabled and the version 1.0.1 as Default:

The File WSDLHandler type is used in simple WebServices usage scenario, when the application doesn't requires a full blown web services registry (like UDDI or ebXML). It will simply save the WSDL documents (and their dependencies) in a configurable directory.

# FileWSDLHandler class
jonas.service.wsdl.class    org.ow2.jonas.ws.base.handler.FileWSDLHandler

# Directory where WSDLs will be copied
# If not set JONAS_BASE/wsdls will be used
# jonas.service.publish.file.directory    /tmp                  

# Encoding of the file (In respect with the platform JOnAS is running on)
# If not set default to UTF-8
jonas.service.publish.file.encoding     UTF-8                   

The JAXR WSDLHandler is a WSDL Handler responsible of publishing the application WSDL in an enterprise level registry or repository, allowing external clients to get the technical and administrative information about the deployed service.^[8]

# RegistryWSDLHandler class
jonas.service.wsdl.class    org.ow2.jonas.ws.base.handler.RegistryWSDLHandler

# User name and Password to access Registry
jonas.service.publish.uddi.username                 jonas                                             
jonas.service.publish.uddi.password                 jonas                                             

# Organization name, small desc (optionnal) and primary contact name.
jonas.service.publish.uddi.organization.name        OW2                                               
jonas.service.publish.uddi.organization.desc        OW2 Consortium (http://www.objectweb.org)         
jonas.service.publish.uddi.organization.person_name JOnAS                                             

# URLs where Registry can be contacted (Publish an Query APIs)
javax.xml.registry.lifeCycleManagerURL  http://localhost:9000/juddi/publish                           
javax.xml.registry.queryManagerURL      http://localhost:9000/juddi/inquiry                           

The memoryrealm must be named and defines users, groups and roles in the section <jonas-memoryrealm>

<jonas-memoryrealm>
 <memoryrealm name="memrlm_1"> 
   <roles>
     <role name="jonas-admin" description="JonasAdmin role" /> 
     <role name="tomcat" description="Used in examples" />
   </roles>
   <groups>
   <group name="jonas" 
      roles="jonas-admin,tomcat,jaas,ws-security" description="All authorization" /> 
   </groups>
   <users>
     <user name="tomcat" password="tomcat" roles="tomcat,jonas-admin,manager" /> 
     <user name="jetty" password="jetty" roles="jetty" />
     <!-- Example of a crypt password : password for jadmin is : jonas -->
     <user name="jadmin" password="{MD5}nF3dVBB3NPfRgzWlJFwoaw==" roles="jonas-admin" /> 
     <user name="jps_admin" password="admin" roles="administrator" />
     <user name="supplier" password="supplier" roles="administrator" />
     <!-- Another crypt example in another format : password is jonas -->
     <!-- JonasAdmin uses name="jonas" password="jonas" -->
     <user name="jonas" password="SHA:NaLG+uYfgHeqth+qQBlyKr8FCTw=" groups="jonas" /> 
     <user name="principal1" password="password1" roles="role1" />
     <user name="principal2" password="password2" roles="role2" />
    </users>
 </memoryrealm>
</jonas-memoryrealm>

Users, groups, and roles information are stored in a database; the configuration for accessing the corresponding database is described in the section <jonas-dsrealm>

The configuration requires the name of a datasource, the tables used, and the names of the columns.

<jonas-dsrealm>
   <dsrealm name="dsrlm_1" 
            dsName="jdbc_1" 
      userTable="realm_users" userTableUsernameCol="user_name" userTablePasswordCol="user_pass" 
      roleTable="realm_roles" roleTableUsernameCol="user_name" roleTableRolenameCol="role_name"> 
   </dsrealm>
</jonas-dsrealm>

to use this database a Datasource configuration with the right JNDI name for the dbm service must be set in the jonas.properties file.

Users, groups, and roles information are stored in an LDAP directory. This is described in the section <jonas-ldaprealm>

There are some optional parameters. If they are not specified, some of the parameters are set to a default value. For example if the providerUrl element is not set, the default value is ldap://localhost:389. The jonas-realm_1_0.dtd DTD file show the default values.

JOnAS provides in $JONAS_BASE/conf/jaas.config a JAAS Login Configuration File already configured with some login configuration.

There are two requirements: the entry dedicated to Tomcat must be named tomcat, and the entry for Jetty, jetty. Note that everything in this file is case-sensitive.

The predifined entries are:

The default configuration for the web container Tomcat is the following:

tomcat {
    org.objectweb.jonas.security.auth.spi.JResourceLoginModule required
    resourceName="memrlm_1"
    ;
};

this indicates that the JResourceLoginModule Login Module must be used on the memory realm named memrlm_1.

The default configuration for the web container Jetty is the same than the previous:

jetty {
    org.objectweb.jonas.security.auth.spi.JResourceLoginModule required
    resourceName="memrlm_1"
    ;
};

the configuration for the container clients examples :

jaasclient {
    // Login Module to use for the example jaasclient.

    org.objectweb.jonas.security.auth.spi.JResourceLoginModule required
    resourceName="memrlm_1"

    org.objectweb.jonas.security.auth.spi.ClientLoginModule  required
    globalCtx="true"
    ;
};

Here two Login Modules are used, one for checking the identity in the memoty realm, the second for propagating a security context with the client request.

To change the location and name of the jaas.config file, edit the $JONAS_BASE/bin/jonas.sh script and modify the following line:

-Djava.security.auth.login.config=$JONAS_BASE/conf/jaas.config

JOnAS provides some predefined LoginModules:

The jonas-ra.xml contains JOnAS specific information describing deployment information, logging, pooling, jdbc connections, and RAR config property values:

At JDBC RA deployment time, if pool-init is not null pool-init JDBC connection are created.

When a user requests a jdbc connection, the JDBC RA first checks to see if a connection is already open for its transaction. If not, it tries to get a free connection from the free list. If there are no more connections available, it creates a new jdbc connection (if pool-max is not reached).

If it cannot create new connections, the user must wait (if pool-max-waiters is not reached) until a connection is released. After a limited time (pool-max-waittime), the getConnection returns an exception.

When the user calls close() on its connection, it is put back in the free list.

Many statistics are computed (every pool-sampling-period seconds) and can be viewed by JonasAdmin. This is useful for tuning these parameters and for seeing the server load at any time

When a connection has been open for a time too long (pool-max-age), the pool will try to release it from the freelist. However, the JDBC RA always tries to keep open at least the number of connections specified in pool-min.

When the user has forgotten to close a jdbc connection, the system can automatically close it, after pool-max-opentime minutes. Note that if the user tries to use this connection later, thinking it is still open, it will return an exception (socket closed).

When a connection is reused from the freelist, it is possible to verify that it is still valid. This is configured in jdbc-check-level . For levels >1 it tries a dummy statement on the connection before returning it to the caller. This statement is configured in jdbc-test-statement.

	Note
	this previous description is not only true for JDBC RAs but also for all types of resource adapters, except jdbc-check-level and jdbc-test-statement which are specifics for JDBC.

An RAR for Oracle named as jdbc_1 in JNDI and using the Oracle thin Driver JDBC driver, should be described in a file (called for example Oracle1_DM.rar), with the following properties configured in the jonas-ra.xml file:

<?xml version = "1.0" encoding = "UTF-8"?>
<jonas-connector xmlns="http://www.objectweb.org/jonas/ns"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.objectweb.org/jonas/ns
 http://www.objectweb.org/jonas/ns/jonas-connector_4_2.xsd" >
  <jndi-name>jdbc_1</jndi-name>
  <rarlink>JOnASJDBC_DM</rarlink>
  <jonas-config-property>
    <jonas-config-property-name>user</jonas-config-property-name>
    <jonas-config-property-value>scott</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>password</jonas-config-property-name>
    <jonas-config-property-value>tiger</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>loginTimeout</jonas-config-property-name>
    <jonas-config-property-value></jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>URL</jonas-config-property-name>
    <jonas-config-property-value>jdbc:oracle:thin:@malte:1521:ORA1</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>dsClass</jonas-config-property-name>
    <jonas-config-property-value>oracle.jdbc.driver.OracleDriver</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>mapperName</jonas-config-property-name>
    <jonas-config-property-value>rdb.oracle</jonas-config-property-value>
  </jonas-config-property>
</jonas-connector>

In this example, "malte" is the hostname of the server running the database Oracle, 1521 is the SQL*Net V2 port number on this server, and ORA1 is the ORACLE_SID. This example makes use of the Oracle "Thin" JDBC driver. For an application server running on the same host as the Oracle DBMS, you can use the Oracle OCI JDBC driver.

To create a PostgreSQL RAR configured as jdbc_3 in JNDI, it should be described in a file (called for examplePostgreSQL3_DM.rar), with the following properties configured in the jonas-ra.xml file:

<?xml version = "1.0" encoding = "UTF-8"?>
<jonas-connector xmlns="http://www.objectweb.org/jonas/ns"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.objectweb.org/jonas/ns
 http://www.objectweb.org/jonas/ns/jonas-connector_4_2.xsd" >
  <jndi-name>jdbc_3</jndi-name>
  <rarlink>JOnASJDBC_DM</rarlink>
<jonas-config-property>
    <jonas-config-property-name>user</jonas-config-property-name>
    <jonas-config-property-value>jonas</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>password</jonas-config-property-name>
    <jonas-config-property-value>jonas</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>loginTimeout</jonas-config-property-name>
    <jonas-config-property-value></jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>URL</jonas-config-property-name>
    <jonas-config-property-value>jdbc:postgresql:/malte:5432/db_jonas</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>dsClass</jonas-config-property-name>
    <jonas-config-property-value>org.postgresql.Driver</jonas-config-property-value>
  </jonas-config-property>
  <jonas-config-property>
    <jonas-config-property-name>mapperName</jonas-config-property-name>
    <jonas-config-property-value>rdb.postgres</jonas-config-property-value>
  </jonas-config-property>
</jonas-connector>

An RAR for Oracle configured as jdbc_4 in JNDI and using the Oracle XADataSource interface of the JDBC driver thin in order to use a JDBC2-XA-compliant driver.It may be described in a file (called for example Oracle1_XA.rar), with the following properties configured in the jonas-ra.xml file:

<?xml version = "1.0" encoding = "UTF-8"?>
<jonas-connector xmlns="http://www.objectweb.org/jonas/ns"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.objectweb.org/jonas/ns
 http://www.objectweb.org/jonas/ns/jonas-connector_4_2.xsd" >
  <jndi-name>jdbc_4</jndi-name>
  <rarlink>JOnASJDBC_XA</rarlink>
   <jonas-config-property>
      <jonas-config-property-name>user</jonas-config-property-name>
      <jonas-config-property-value>jonas</jonas-config-property-value>
   </jonas-config-property>
   <jonas-config-property>
      <jonas-config-property-name>password</jonas-config-property-name>
      <jonas-config-property-value>jonas</jonas-config-property-value>
   </jonas-config-property>
   <jonas-config-property>
      <jonas-config-property-name>databaseName</jonas-config-property-name>
      <jonas-config-property-value>dbjonas</jonas-config-property-value>
    </jonas-config-property>
    <jonas-config-property>
      <jonas-config-property-name>portNumber</jonas-config-property-name>
      <jonas-config-property-value>1521</jonas-config-property-value>
    </jonas-config-property>
    <jonas-config-property>
      <jonas-config-property-name>serverName</jonas-config-property-name>
      <jonas-config-property-value>wallis</jonas-config-property-value>
    </jonas-config-property>
    <jonas-config-property>
      <jonas-config-property-name>dbSpecificMethods</jonas-config-property-name>
      <jonas-config-property-value>:#setDriverType=thin##String</jonas-config-property-value>
    </jonas-config-property>
    <jonas-config-property>
      <jonas-config-property-name>dsClass</jonas-config-property-name>
      <jonas-config-property-value>oracle.jdbc.xa.client.OracleXADataSource</jonas-config-property-value>
    </jonas-config-property>
</jonas-connector>

The a3server.xml ($JONAS_BASE/conf/a3server.xml) file describes the JORAM platform, i.e., the network domain, the used transport protocol, and the reachable JORAM servers. It is used by a JORAM server at start time. By default, only one collocated JORAM server is defined (s0) based on the tcp/ip protocol. A distributed configuration example is provided in the how-to document and other examples are available in JORAM's user guide.

<config>
  <property name="Transaction" value="fr.dyade.aaa.util.NullTransaction"/> 
   <server id="0" name="S0" hostname="localhost"> 
    <service class="org.objectweb.joram.mom.proxies.ConnectionManager"
             args="root root"/>
    <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService"
             args="16010"/> 

   </server>
</config>

The above configuration describes a JORAM platform made up of one unique JORAM server (id 0, name s0), running on localhost, listening on port 16010. Those values are taken into account by the JORAM server when starting. However, they should match the values set in the deployment descriptor of the RA, otherwise the adapter either will not connect to the JORAM server, or it will build improper connection factories.

The joram_raconfig command allows to modify these parameters in all the configuration files.

If used in non-collocated mode, joram can be started with the JmsServer command which loads the $JONAS_BASE/conf/a3server.xml configuration file.

The ra.xml file is the standard deployment descriptor for the JORAM adapter and the jonas-ra.xml file is the JOnAS-specific deployment descriptor for the JORAM adapter. These files set the central configuration of the adapter, define and set managed connection factories for outbound communication, and define a listener for inbound communication. jonas-ra.xml contains specific parameters such as pool parameters or jndi names, but also may redefine the parameters of some ra.xml files and override their values. Globally, a good way to proceed is to keep the original ra.xml file with the default values and to customize the configuration only in the jonas-ra.xml file.

Changing the configuration of the RA requires extracting and editing the deployment descriptor and updating the archive file. There are several possible ways to do this:

The following properties are related to the central configuration of the adapter; they are set via some <jonas-config-property> elements:

The <jonas-connection-definition> elements wrap properties related to the managed connection factories:

There are three managed connection factories:

Here are the properties that can be configured for each managed connection factory:

The <jonas-activationspec> element wraps a property related to inbound messaging:

The Pooling Tags are the same than those for other RAs:

joramAdmin.xml file describes the configuration related to the application. It describes the administration objects in the JORAM server such as the JMS objects, the users, or the non-managed factories. In other words, it defines the JORAM objects to be (optionally) created when deploying the adapter.

In earlier version the joram-admin.cfg was used for this same purpose but it is now deprecated.

The default file provided with JOnAS creates a queue bound with the name sampleQueue, a topic bound with the name sampleTopic, sets the anonymous user, and creates and binds non-managed connection factories named JCF, JQCF and JTCF

Note

All administration tasks are performed by the server connected but may affect remote JORAM servers to which the adapter is connected through the ServerId attribute. If a queue, a topic or a user already exists on the JORAM server (for example, because the server is in persistent mode and has re-started after a crash, or because the adapter has been deployed, undeployed and is re-deployed giving access to a remote JORAM server), it will be retrieved instead of being re-created.

The format of this file is XML. Here are some examples:

A pool of ManagedConnection is defined for each factory (connection definition) specified in the jonas-ra.xml file. See the pool parameters in the Section 2.7.1.2, “Resource Adapter configuration: ra.xml, jonas-ra.xml”.

The JORAM RA manages a pool of session/thread for each connection and, by default, the maximum number of parallel sessions is set to 10.

When linked with an message-driven bean, this maximum number of entries in the pool corresponds to the maximum number of messages that can be processed in parallel per message-driven bean. A session is released to the pool just after the message processing (onMessage()). When the maximum is reached, the inquiries for a session creation are blocked until a session becomes available in the pool.

The maxNumberOfWorks property can be set in the message-driven bean standard deployment descriptor. For example, the code below can be added to limit the number of parallel sessions to 100 (default value is 10).

     <activation-config-property>
     <activation-config-property-name>maxNumberOfWorks</activation-config-property-name>
     <activation-config-property-value>100</activation-config-property-value>
     </activation-config-property>

As this parameter set the max number of messages that can be treated simultaneously, the max-cache-size must be set accordingly in the specific deployment descriptor.

Each Datasource is implemented as a connection manager and manages a pool of JDBC connections.

The pool can be configured via some additional properties described in the following table.

All these settings have default values and are not required. All these attributes can be reconfigured when JOnAS is running, with the console JonasAdmin.

When a user requests a jdbc connection, the dbm connection manager first checks to see if a connection is already open for its transaction. If not, it tries to get a free connection from the free list. If there are no more connections available, the dbm connection manager creates a new jdbc connection (if jdbc.maxconpool is not reached).

If it cannot create new connections, the user must wait (if jdbc.maxwaiters is not reached) until a connection is released. After a limited time (jdbc.maxwaittime), the getConnection returns an exception.

When the user calls close() on its connection, it is put back in the free list.

Many statistics are computed (every jdbc.samplingperiod seconds) and can be viewed by JonasAdmin. This is useful for tuning these parameters and for seeing the server load at any time.

When a connection has been open for too long a time (jdbc.connmaxage), the pool will try to release it from the freelist. However, the dbm connection manager always tries to keep open at least the number of connections specified in jdbc.minconpool.

When the user has forgotten to close a jdbc connection, the system can automatically close it, after jdbc.maxopentime minutes. Note that if the user tries to use this connection later, thinking it is still open, it will return an exception (socket closed).

When a connection is reused from the freelist, it is possible to verify that it is still valid. This is configured in jdbc.connchecklevel. The maximum level is to try a dummy statement on the connection before returning it to the caller. This statement is configured in jdbc.connteststmt

Here is the template for an Oracle dataSource.properties file that can be found in $JONAS_ROOT/conf:

###################### Oracle DataSource configuration example
#


#####
#  DataSource configuration
#
datasource.name  jdbc_1
datasource.url  jdbc:oracle:thin:@<your-hostname>:1521:<your-db>
datasource.classname oracle.jdbc.driver.OracleDriver
datasource.username <your-username>
datasource.password <user-password>
datasource.mapper rdb.oracle


#####
#  ConnectionManager configuration
#

#  JDBC connection checking level.
#     0 = no special checking
#     1 = check physical connection is still open before reusing it
#     2 = try every connection before reusing it
jdbc.connchecklevel 0

#  Max age for jdbc connections
#  nb of minutes a connection can be kept in the pool
jdbc.connmaxage 1440

# Maximum time (in mn) a connection can be left busy.
# If the caller has not issued a close() during this time, the connection
# will be closed automatically.
jdbc.maxopentime 60

#  Test statement
jdbc.connteststmt select * from dual

# JDBC Connection Pool size.
# Limiting the max pool size avoids errors from database.
jdbc.minconpool 10
jdbc.maxconpool 30

# Sampling period for JDBC monitoring :
# nb of seconds between 2 measures.
jdbc.samplingperiod 30

# Maximum time (in seconds) to wait for a connection in case of shortage.
# This may occur only when maxconpool is reached.
jdbc.maxwaittime 5

# Maximum of concurrent waiters for a JDBC Connection
# This may occur only when maxconpool is reached.
jdbc.maxwaiters 100
       

As with other Apache modules, mod_jk should be first installed on the modules directory of the Apache Web Server and the httpd.conf file has to be updated. Moreover, mod_jk requires workers.properties file that describes the host(s) and port(s) used by the workers.

#-----------------------
# List the workers name
#-----------------------
worker.list=myloadbalancer,jkstatus

#-----------------------
# worker1
#-----------------------
worker.worker1.port=9010
worker.worker1.host=localhost
worker.worker1.type=ajp13 # Load balance factor
worker.worker1.lbfactor=1 # Define preferred
failover node for worker1
#worker.worker1.redirect=worker2 # Disable worker1 for all requests except failover
#worker.worker1.disabled=True
#-----------------------
# worker2
#-----------------------
worker.worker2.port=9011
worker.worker2.host=localhost
worker.worker2.type=ajp13 # Load balance factor
worker.worker2.lbfactor=1 # Define preferred failover node for worker2
#worker.worker2.redirect=worker2 # Disable worker2 for all requests except failover
#worker.worker2.disabled=True
#-----------------------
# Load Balancer worker
#-----------------------
worker.myloadbalancer.type=lb
worker.myloadbalancer.balanced_workers=worker1,worker2
worker.mylloadbalancer.sticky_session=false
#-----------------------
# jkstatus worker
#-----------------------
worker.jkstatus.type=status
        

# Load mod_jk module
# Update this path to match your modules location
LoadModule jk_module
modules/mod_jk.so # Location of the workers.properties file
# Update this path to match your conf directory location (put workers.properties next to httpd.conf) JkWorkersFile
/etc/httpd/conf/workers.properties # Location of the log file JkLogFile /var/log/mod_jk.log
# Log level : debug, info, error or emerg
JkLogLevel info
# Select the timestamp log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
# Shared Memory Filename ( Only for Unix platform ) required by loadbalancer
JkShmFile /var/log/jk.shm
# Assign specific URL to the workers
JkMount /clusteredExample myloadbalancer
JkMount /clusteredExample/* myloadbalancer
# A mount point to the status worker
JkMount /jkmanager jkstatus
JkMount /jkmanager/* jkstatus
# Enable the Jk manager access only from localhost
<Location /jkmanager/>
   JkMount jkstatus
   Order deny,allow
   Deny from all
   Allow from 127.0.0.1
</Location>
        

Each member needs an AJP13 connector listening on the port defined in the workers.properties file. Moreover, the worker name (here worker1/worker2) must be used as value for the Engine's jvmRoute attribute.

Here is a chunk of server.xml configurations file for the member worker1:

<Server>
  <!-- Define the Tomcat Stand-Alone Service -->
  <Service name="Tomcat-JOnAS">
    <!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 9000 -->
    <Connector port="9000" maxHttpHeaderSize="8192" maxThreads="150"
        minSpareThreads="25" maxSpareThreads="75"
        enableLookups="false" redirectPort="9043"
        acceptCount="100" connectionTimeout="20000"
        disableUploadTimeout="true"/>
    <!-- AJP 1.3 Connector on port 9010 for worker.worker1.port in workers.properties file -->
    <Connector port="9010" enableLookups="false" redirectPort="9043" protocol="AJP/1.3"/>

    <!-- An Engine represents the entry point You should set jvmRoute to support load-balancing via AJP ie : -->
    <Engine name="jonas" defaultHost="localhost" jvmRoute="worker1">
    </Engine>
  </Service>
<Server>
      

Additionally to HTTP requests load balancing provided by TomcatCluster members, transparent failover for Web applications can be reached by using HTTP session replication provided by the Tomcat clustering solution.

TomcatCluster members are JOnAS instances having the web service activated, using the Tomcat implementation, and having a specific configuration which allows them to be members of a Tomcat cluster.

The concerned configuration file is the server.xml file. Every member of the cluster must have a Cluster element defined in the default virtual host definition. The cluster name is defined by the clusterName attribute, which should be the same for all the cluster members. Another common element for the cluster members is the Membership definition.

The example below defines the configuration for a server which is a TomcatCluster member and a JkCluster member in the same time.

<Server>
  <!-- Define the Tomcat Stand-Alone Service -->
  <Service name="Tomcat-JOnAS">
    <!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 9000 -->
    <Connector port="9000" maxHttpHeaderSize="8192" maxThreads="150"
        minSpareThreads="25" maxSpareThreads="75"
        enableLookups="false" redirectPort="9043"
        acceptCount="100" connectionTimeout="20000"
        disableUploadTimeout="true"/>
    <!-- AJP 1.3 Connector on port 9010 (value of worker.worker1.port in workers.properties file) -->
    <Connector port="9010" enableLookups="false" redirectPort="9043" protocol="AJP/1.3"/>

    <!-- Define the Engine -->
    <Engine name="jonas" defaultHost="localhost" jvmRoute="worker1">
    </Engine>

    <!-- Define the default virtual host -->
    <Host name="localhost" debug="0" appBase="webapps"
        unpackWARs="false" autoDeploy="false"
        deployOnStartup="false" deployXML="false">
      <!-- Define a Cluster element -->
      <Cluster className="org.apache.catalina.cluster.tcp.SimpleTcpCluster"
        clusterName="myTomcatCluster"
        managerClassName="org.apache.catalina.cluster.session.DeltaManager"
        expireSessionsOnShutdown="false" useDirtyFlag="true"
        notifyListenersOnReplication="true">
        <Membership
          className="org.apache.catalina.cluster.mcast.McastService"
          mcastAddr="228.0.0.4" mcastPort="45564"
          mcastFrequency="500" mcastDropTime="3000"/>
        <Receiver
          className="org.apache.catalina.cluster.tcp.ReplicationListener"
          tcpListenAddress="auto" tcpListenPort="4003"
          tcpSelectorTimeout="100" tcpThreadCount="6"/>
        <Sender
          className="org.apache.catalina.cluster.tcp.ReplicationTransmitter"
          replicationMode="pooled" ackTimeout="15000"/>
        <Valve
          className="org.apache.catalina.cluster.tcp.ReplicationValve"
          filter=".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.htm;.*\.html;.*\.css;.*\.txt;"/>
      </Cluster>
    </Host>
  </Service>
<Server>
      

	Note
	the clusterName attribute is mandatory (and not set by default in server.xml file).

Lets consider the two JOnAS servers which play the role of worker1 and worker2 in the myloadbalancer JkCluster . Suppose that these servers, named node1 and node2 are configured as members of the myTomcatCluster TomcatCluster . The master detects automatically the Tomcat cluster membership and creates a TomcatCluster named myTomcatCluster . It adds node1 and node2 to the cluster's member list.

Here is myTomcatCluster cluster with node1 and node2 members running

TODO: add CMI documentation

TbC

TODO: add HA documentation

TbC

CMI relies on JGroups group-communication protocol for ensuring the global registry replication. The parameters are gathered in the:

All the members of a cluster share the same JGroups configuration.

If several cluster partitions are required over a single LAN, several JGroups configurations must be configured with different values for the following parameters:

When a new node appears in the cluster, its registry content is synchronized automatically.

When a node disappears, JGroups notifies the other's member of the node leaving and the registry entries related to this node are removed.

On the client side, the high availability of the registry is provided by the capability to set several JOnAS instances in the registry url. At the lookup time, the client chooses (round-robin algorithm) one of the available servers to get the home stub. If the server fails, the request is sent to another server. The CMI url registry is specified in the $JONAS_BASE/conf/carol.properties file using the following syntax:

carol.cmi.url=cmi://server1:port1[,server2:port2...]       

The CMI cluster stub handles a cluster map on the client side. The CMI cluster stub is created:

In these two cases, the call gets a stubs list from the global registry and the CMI cluster stub updates the local cluster map. Afterwards, the local cluster map can be updated dynamically during the invocation of the business methods calls (through the HA interceptors) when a new view is detected in the cluster.

If a communication error with a server occurs during a remote call invocation, the server is removed from the cluster map.

CMI classes are generated by GenIC when compiling with the protocol CMI. They are built from the velocity templates located in $JONAS_ROOT/templates/genic directory. By default the templates used are:

The templates inherit the org.objectweb.carol.cmi.Distributor class and contain the following methods:

The user has the ability to customize the load-balancing and fail-over logic for each EJB by specifying the velocity template to use in the JOnAS- specific descriptor on deployment of the ejb-jar file. The XML elements are:

<cluster-home-distributor>MyHomeDistributor.vm</cluster-home-distributor>      

<cluster-remote-distributor>MyRemoteDistributor.vm</cluster-remote-distributor>      

If not set, the default velocity templates are used.

If set with the value 'disabled', the CMI classes are not generated and the EJB will not be distributed.

If set with a file name, this file must be located in the $JONAS_ROOT/templates/genic directory.

The 'cluster-home-distributor' element is valid for the SSB, SFSB and EB.

The 'cluster-remote-distributor' element is valid for the SSB.

The High Availability (HA) service is required in JOnAS in order to replicate SFSBs. The HA service must be included in the list of available services in JOnAS. This is done in the jonas.properties file placed in $JONAS_BASE/conf.

...
jonas.services registry,jmx,jtm,db,dbm,security,resource,ejb,ws,web,ear,ha
...      

The HA service must also be configured in the jonas.properties file:

...
jonas.service.ha.class org.objectweb.jonas.ha.HaServiceImpl
jonas.service.ha.gcl jgroups
...
      

The HA service uses JGroups as a group communication layer (GCL). JGroups behavior is specified by means of a stack of properties configured through an XML file (See JGroups documentation for more information: http://www.jgroups.org). The default configuration of the HA service uses the $JONAS_BASE/conf/jgroups-ha.xml file and the sfsb-rep group name. The HA service can be told to use a particular stack configuration or a particular group name by modifying the following lines in jonas.properties:

...
jonas.service.ha.jgroups.conf jgroups-ha.xml
jonas.service.ha.jgroups.groupname jonas-rep
...      

Finally, the CMI protocol must be specified in the carol.properties file in $JONAS_BASE/conf:

...
carol.protocols=cmi...
...      

The new horizontal replication algorithm uses a database table to keep track of current running transactions. This table is accessed from the new elected node during fail-over to detect whether or not the current transaction committed at the former local node, ensuring exactly-once semantics. The table contains only one column: the transaction identifier (txid).

In JOnAS 4.8 this table must be created manually with the following SQL command:

create TABLE ha_transactions (txid varchar(60));      

This table should be located preferably in the database used by the replicated application, but it is not mandatory. If the table is not created in the database used by the replicated application, it is necessary to configure a new datasource for the database that contains this transaction table. This datasource must be configured to use the serializable transaction isolation level.

The database that holds the transaction table is accessed by the replication service with the JNDI name configured in jonas.properties.

...
jonas.service.ha.datasource tx_table_ds
...      

Due to the fact that the replication algorithm stores information associated with clients' transactions and that the server is not notified when a client dies, the HA service might have been storing unnecessary replication information over time. In order to automatically clean this unnecessary replication information, the HA service includes a garbage collection mechanism. It is possible to configure the number of seconds the system waits to execute this mechanism by changing the following property in the jonas.properties file:

...
jonas.service.ha.timeout 600
...      

The JOnAS administration console offers several items of information about the HA service's replication algorithm and allows the configuring of several parameters related to its behaviour. The related information and parameters include:

The JMS API provides a separate domain for each messaging approach, point-to-point or publish/subscribe. The point-to-point domain is built around the concept of queues, senders and receivers. The publish/subscribe domain is built around the concept of topic, publisher and subscriber. Additionally it provides a unified domain with common interfaces that enable the use of queue and topic. This domain defines the concept of producers and consumers. The classic sample uses a very simple configuration (centralized) made of one server hosting a queue and a topic. The server is administratively configured for accepting connection requests from the anonymous user.

JMS clustering aims to offer a solution for both the scalability and the high availability for the JMS accesses. This document gives an overview of the JORAM capabilities for clustering a JMS application in the J2EE context. The load-balancing and fail-over mechanisms are described and a user guide describing how to build such a configuration is provided. Further information is available in the JORAM documentation here .

The following information will be presented:

Getting started :

Two instances of JOnAS are configured ("J1" and "J2"). Each JOnAS instance has a dedicated collocated JORAM server: server "S1" for JOnAS "J1", "S2" for "J2". Those two servers are aware of each other.

Set a JORAM distributed configuration:

See here for more information about a JORAM distributed configuration.

A non hierarchical topic might also be distributed among many servers. Such a topic, to be considered as a single logical topic, is made of topic representatives, one per server. Such an architecture allows a publisher to publish messages on a representative of the topic. In the example, the publisher works with the representative on server 1. If a subscriber subscribed to any other representative (on server 2 in the example), it will get the messages produced by the publisher.

Load balancing of topics is very useful because it allows distributed topic subscriptions across the cluster.

The following scenario and general settings are proposed:

#!/bin/ksh

export JONAS_BASE=$PWD/jb1
cp $JONAS_ROOT/examples/output/ejbjars/newsamplemdb.jar $JONAS_BASE/ejbjars/
jonas admin -a newsamplemdb.jar -n node1

export JONAS_BASE=$PWD/jb2
cp $JONAS_ROOT/examples/output/ejbjars/newsamplemdb.jar $JONAS_BASE/ejbjars/
jonas admin -a newsamplemdb.jar -n node2
        

jclient newsamplemdb.MdbClient         

ClientContainer.info : Starting client...
JMS client: tcf = TCF:localhost-16010
JMS client: topic = topic#1.1.1026
JMS client: tc = Cnx:#0.0.1026:5
MDBsample is Ok
        

Message received: Message6
MdbBean onMessage
Message received: Message7
MdbBean onMessage
Message received: Message8
        

Globally, the load balancing in the context of queues may be meaningless in comparison of load balancing topic. It would be a bit like load balancing a stateful session bean instance (which just requires failover). But the JORAM distributed architecture enables :

Here is a diagram of what is going to happen for the Queue and the message:

A load balancing message queue may be needed for a high rate of messages. A clustered queue is a cluster of queues exchanging messages depending on their load. The example has a cluster of two queues. A heavy producer accesses its local queue and sends messages. It quickly becomes loaded and decides to forward messages to the other queue of its cluster which is not under heavy load.

For this case some parameters must be set:

For further information, see the JORAM documentation here .

The scenario for Queue is similar to the topic one. A client sent messages to a queue in S1. MDB gets messages from each local cluster queue representative. After having sent a burst of messages to the server S1, the load distribution should occur and message should be moved to S2.

The Queue definition in $JONAS_BASE/conf/joramAdmin.xml file is as following :

Run the sample

The procedure is similar to the topic example described above, just use the newsamplemdb2 example rather than newsample one.

An HA server is actually a group of servers, one of which is the master server that coordinates the other slave servers. An external server that communicates with the HA server is actually connected to the master server.

Each replicated JORAM server executes the same code as a standard server except for the communication with the clients.

In the example, the collocated clients use a client module (newsamplemdb). If the server replica is the master, then the connection is active enabling the client to use the HA JORAM server. If the replica is a slave, then the connection opening is blocked until the replica becomes the master.

Several files must be changed to create a JORAM HA configuration:

<?xml version="1.0"?/>
<config>
  <domain name="D1"/>

  <property name="Transaction" value="fr.dyade.aaa.util.NullTransaction"/>

  <cluster id="0" name="s0">

    <property name="Engine" value="fr.dyade.aaa.agent.HAEngine" />
    <property name="nbClusterExpected" value="1" />
        

<?xml version="1.0"?>
<config<
  <domain name="D1"/>

  <property name="Transaction" value="fr.dyade.aaa.util.NullTransaction"/>

  <cluster id="0" name="s0">

    <property name="Engine" value="fr.dyade.aaa.agent.HAEngine" />
    <property name="nbClusterExpected" value="1" />

    <server id="0" hostname="localhost">
      <network domain="D1" port="16300"/>
      <service class="org.objectweb.joram.mom.proxies.ConnectionManager" args="root root"/>
      <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" args="16010"/>
      <service class="org.objectweb.joram.client.jms.ha.local.HALocalConnection"/>
    </server>

    <server id="1" hostname="localhost">
      <network domain="D1" port="16301"/>
      <service class="org.objectweb.joram.mom.proxies.ConnectionManager" args="root root"/>
      <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" args="16020"/>
      <service class="org.objectweb.joram.client.jms.ha.local.HALocalConnection"/>
    </server>

  </cluster>

</config>
        

<?xml version="1.0"?>

<JoramAdmin>

<AdminModule>
  <collocatedConnect name="root" password="root"/>
</AdminModule>

<ConnectionFactory className="org.objectweb.joram.client.jms.ha.tcp.HATcpConnectionFactory">
  <hatcp url="hajoram://localhost:16010,localhost:16020" reliableClass="org.objectweb.joram.client.jms.tcp.ReliableTcpClient"/>
  <jndi name="JCF"/>
</ConnectionFactory>

<ConnectionFactory className="org.objectweb.joram.client.jms.ha.tcp.QueueHATcpConnectionFactory">
  <hatcp url="hajoram://localhost:16010,localhost:16020" reliableClass="org.objectweb.joram.client.jms.tcp.ReliableTcpClient"/>
  <jndi name="JQCF"/>
</ConnectionFactory>

<ConnectionFactory className="org.objectweb.joram.client.jms.ha.tcp.TopicHATcpConnectionFactory">
  <hatcp url="hajoram://localhost:16010,localhost:16020" reliableClass="org.objectweb.joram.client.jms.tcp.ReliableTcpClient"/>
  <jndi name="JTCF"/>
</ConnectionFactory>
        

      <config-property>
         <config-property-name>ClusterId</config-property-name>
         <config-property-type>java.lang.Short</config-property-type>
         <config-property-value>0</config-property-value>
      </config-property>
        

First launch the two JOnAS bases. Create a runHa.sh file in which the following code will be added:

export JONAS_BASE=$PWD/jb1
export CATALINA_BASE=$JONAS_BASE
rm -f $JONAS_BASE/logs/*
jonas start -win -n node1 -Ddomain.name=HA
      

Then do the same for the second JOnAS base. After that launch the script.

One of the two JOnAS bases (the one which is the slowest) will be in a waiting state when reading the joramAdmin.xml

JoramAdapter.start :   - Collocated JORAM server has successfully started.
JoramAdapter.start :   - Reading the provided admin file: joramAdmin.xml
      

whereas the other one is launched successfully.

Then launch (through a script or not) the newsamplemdb example:

jclient -cp /JONAS_BASE/jb1/ejbjars/newsamplemdb.jar:/JONAS_ROOT/examples/classes  -carolFile clientConfig/carol.properties newsamplemdb.MdbClient
      

Messages are sent on the JOnAS base which was launched before. Launch it again and kill the current JOnAS. The second JOnAS will automatically wake up and take care of the other messages.

This is a proposal for building an MDB clustering based application.

This is like contested Queues. i.e., there is more than one receiver on different machines receiving from the queue. This load balances the work done by the queue receiver, not the queue itself.

The HA mechanism can be mixed with the load balancing policy based on clustered destinations. The load is balanced between several HA servers. Each element of a clustered destination is deployed on a separate HA server.

Here is the supposed configuration (supposed because it has not been verifed).

The configuration must now be tested, as follows:

Names can be defined in a static way, through the domain.xml configuration file, or dynamically, by starting new elements in the domain. For example, when starting a JOnAS instance, the administrator can specify the server name using the -n option and the domain name by setting the domain.name environment property. The uniqueness of the starting server's name is enforced by the discovery service.

The first step is to choose a name for the domain and to choose a server to represent the common administration point. This server must be configured as a master by setting to true the jonas.master property. Also, to allow dynamic domain management, add the discovery service in the JOnAS services list (jonas.services property).

The domain name is not a configuration property for the master (neither for any server in the domain), but it has to be specified when starting the master.

Before starting the master, the administrator can define the domain's initial topology by editing the domain.xml configuration file.

This step is optional. It consists in defining the domain elements using the domain.xml configuration file located in the master's configuration directory. If the administrator has no specific configuration needs, it should at least check the name element, and set its value to the chosen name. That file can also be used to define a default user name and password to use when connecting to servers and cluster daemons. Moreover, the administrator can choose to remove the domain.xml file.

The elements that can be defined in domain.xml are:

Start the master in the domain:

jonas start -n masterName -Ddomain.name=domainName

Note that the domain name is specified by setting a domain.name environment property.

Once started, the administrator can manage and monitor the following elements in the domain through JonasAdmin, or another JMX based administration application, running on the master: