HTTP farming consists in distributing the processing load across N JOnAS instances. The same application is deployed all over the cluster and a request may be processed by any instance.

A load-balancer is setup in front of the JOnAS instances. The intermediate device handles the site url in order to mask the JOnAS instances multiplicity to the users. The load-balancer supports the HTTP session affinity in order to route a client towards the server hosting its session.

A load-balancer may be a software or a hardware device or a mix of two. The application server instances may be collocated on a same machine or may be distributed across several machines.

The intermediate device may be duplicated for avoiding a SPOF.

Hereinafter the figure illustrates a HTTP farm composed of a L4 switch, 2 Apache servers and N JOnAS instances.

The Apache server is configured with the mod_jk plugin for ensuring the load-balancing between the JOnAS instances and the session affinity through the AJP protocol. Furthermore mod_jk supports the failover when a server crashes. The Apache server may be used for caching the static pages, performing compression or encryption and, thus, can reduce the application servers load.

	Note
	From Apache 2.2, mod_proxy_balancer is alternative to the mod_jk plugin. It supports AJP protocol but also HTTP and FTP.

The number of JOnAS instances must be determined according to the expected performance. The Apache server being a SPOF, it should be duplicated and a network device distributes the load at the TCP level between them. Of course the network device should be replicated as well (primary/backup mode).

HTTP farming is very common and widespread. It fits well with the more frequent requirements in terms of scalability and availability. Furthermore, this architecture pattern can be used for implementing a cluster of web service providing that the web service is standard and is stateless.

When the application server tier gets a bottleneck, this architecture enables to improve the performance by adding some JOnAS instances.

The application server may be unstable, in particular under heavy load. This architecture enables to improve the availability by reducing the impact of failures. However the failures are not transparent to the users who are connected to the in-fault server since they lose theirs sessions. To be note that after a crash, the load is distributed between the survivors servers what may impact the performance.

HTTP clustering is used when service continuity of web application is expected and when failures must be transparent for the users. It consists in replicating the HTTP sessions on P JOnAS instances among N.

The session context is replicated across a replication domain. Domain members are met through a multicast based protocol. The session replication takes place through point to point protocol (TCP based) and the replication mode can be synchronous (the user response is sent after the replication) or asynchronous (the user response is immediate and the replication is delayed).

Hereinafter the figure illustrates cluster with 4 JOnAS instances behind an Apache server. Requests are load-balanced across the 4 instances . The jk connector handles the session affinity and ensures that all the requests related to one session are routed towards the same instance. 2 replication domain are defined and each session is replicated on 2 JOnAS instances hosting by 2 different nodes for ensuring not to lose a session when a crash node occurs.

The Apache server can be duplicated for avoiding a SPOF.

Such a configuration lies both in the Apache/jk elements (related to the load-balancing) and in the JOnAS instances (related to the session replication).

	Note
	From Apache 2.2, mod_proxy_balancer is alternative to the mod_jk plugin. It supports AJP protocol but also HTTP and FTP.

HTTP clustering must be used only when the HTTP session loss is not acceptable. A server failure is visible only for the connected users who have an on-going request processed by the failed instance. The fault will be transient, the request will be sent towards another server which hosts a backup of the session.

The HTTP session replication impacts the performance and causes an overhead on the system resources consumption (memory. network, cpu). Moreover, the replication in a synchronous mode induces an extra latency.

For reducing the performance impact, it is recommended to use a dedicated network interface for the HTTP session replication (separated from the AJP requests) and to limitate the replication across 2 JOnAS instances (replication domain).

EJB farming aims at providing:

EJB2 and EJB3 farming are supported by JOnAS.

The EJB tier duplication is not visible for the client.

EJB farming relies on the CMI component which enables clustering on top of different RMI protocols such as jrmp, iiop or irmi.

When a client program intends to access an EJB, it invokes a JNDI registry lookup for getting an EJB home or EJB remote proxy. In an EJB farm, the CMI registry is replicated in order to provide a cluster view to the client. The cluster view represents a a list of JOnAS nodes hosting the EJB with additional clustering meta-datas. The replication and the group membership rely on the JGroups's group communication protocol. The cluster view is updated dynamically through a control channel and a dedicated control thread in the client JVM. The CMI client proxy ensures the load-balancing and the fail-over of the EJB invocations.

In the clustering meta-datas, the cluster logic defines both the load-balancing and fail-over algorithms. The cluster logic can be customized. A set of default policies are provided with CMI: round-robin, first available, random, etc... For each one, a strategy can be added, for example, local preference (for dealing with the collocated mode) or weighted round-robin (for adding a weighting).

Hereinafter the figure illustrates a EJB farm in a 2 tier architecture with both web client and java client.

The Apache server is configured with the mod_jk plugin for ensuring the load-balancing between the JOnAS instances and the session affinity. Two JOnAS instances (1-2) host the presentation layer and are configured with a servlet container. Two JOnAS instances (3-4) host the business layer and are configured with an ejb container. The CMI registry is replicated across the cluster members in order to share informations about EJBs deployment and topology. Both servlet and java clients do access to EJB and do benefit from load-balancing and availability. In the case of a SFSB (stateful session bean), the EJB is created only in one instance and the state is lost if the JOnAS instance crashes, state replication is addressed in Section 2.2.8, “EJB cluster”.

The JOnAS instances number must be determined according to the expected performance.

This architecture pattern is used either when the ejb tier is separated from the web tier and/or when ejb client are fat java programs.

EJB distribution aims at deploy a JavaEE application which is distributed on many JOnAS instances.

EJB distribution also relies on the CMI component.

Without CMI, EJB needs to be modified to allow invocations on the remote EJBs, for example by setting the Context.PROVIDER_URL of the remote registries or by using the specific features of the IIOP protocol. With CMI, EJB can continue to access to the remote EJBs as if they were locally deployed.

This architecture pattern is used on the EJB tier.

EJB clustering is used when service continuity of ejb application is required and when any failure must be transparent for the users. It relies on the stateful EJB replication and manages the transaction in order to:

The EJB replication relies on

An EJB is replicated only if it is specified as replicated in the component meta-datas (annotation and/or deployment descriptor).

A stateful ejb is created on a JOnAS instance selected according to a load-balancing algorithm (default is round-robin). After the creation all the business methods invocations are routed to this JOnAS instance unless a failure occurs.

Hereinafter the figure illustrates a EJB cluster.

Each JOnAS instance of the EJB tier is configured with the HA service in charge of the session replication. CMI client API supports fail-over for both EJB2 and EJB3.

This architecture pattern is recommended when the application contains some stateful EJB and doesn't tolerate any session loss and any interruption of service. However the user must be aware that this kind of setting does impact highly the performance as the session is replicated between the JOnAS server at each method call.

JMS Farming aims at:

JMS farming consists in distributing the messages load across N JOnAS instances. The same application is deployed all over the cluster and a message may be processed by any instances.

JMS farming relies on the distribution capabilities of the JORAM product. Load-balancing can take place both at the server side or at the client side. When a server crashes, pending messages are lost unless a specific mechanism is set up at the disk level (such mechanisms are addressed in Section 2.2.10, “JMS cluster”).

At the server side, messages can be redirected towards other JOnAS instances when the load reaches a threshold.

Hereinafter the figure illustrates a JMS farming with a distribution control at the server side.

At the client side, messages can be distributed across a set of JOnAS instances according to a load-balancing algorithm (default is random).

Hereinafter the figure illustrates a JMS farming with a distribution control at the client side.

JMS farming fits well with the need of scalability and availability of the EDA (Event Driven Architecture) applications. When the application provides a JMS based asynchronous interface, the JORAM's clustering capabilities do enable to equilibrate the load either from the client side or from the server side. JMS farming is recommended when the message loss is acceptable and constitutes a good compromise in terms of performance and flexibility.

JMS cluster is used when the messages loss is not acceptable and when the interruption of service is not permitted.

Two solutions are available for ensuring the messaging high availability with JOnAS:

This architecture pattern is recommended when the application doesn't tolerate any message loss and any interruption of service. Two mechanisms are available: the first one relies on operating system HA features and the JORAM's persistent mode whereas the second one relies on the native JORAM capabilities and a replication of the JMS requests. In case of the underlying OS provides HA features, the first solution is simpler in term of configuration and provides better performance. Otherwise JORAM HA solution can be considered and the user must pay attention to the performance impact.

A dedicated JOnAS is assigned with the master role which enables the domain management feature. The jonasAdmin console is deployed in this instance and is no more necessary in the others ones.

The domain management functions are exposed through a set of MBeans that are used by the jonasAdmin console.

The master instance interacts with the managed JOnAS instances and the cluster daemons through JMX. The master node periodically polls the managed instances for providing states and statistics.

Several master instances can be defined for high availability, only one must be enabled at one point.

The cluster daemon is in charge of controlling the JOnAS instances (start/stop) that are collocated on the same machine. It is an optional component in the domain management infrastructure and can be added on an existing configuration.

It is accessible through a JMX Remote interface and provides the start/stop operations. By default, it relies on the native JOnAS command for driving the JOnAS instances. The user may put its own commands for setting a particular environment before starting/stopping a JOnAS node.

The managed JOnAS instances must respect some conventions for domain management:

Both domain name and instance name are specified in the starting command: jonas start -n instance_name -Ddomain.name=domain_name.

The discovery service aims at detecting when a new JOnAS instance appears or when a JOnAS instance leaves the domain. It enables the master instance to retrieve the managed instances without any prior informations about them.

Two implementations of the discovery service are available (the choice is done by configuration):

The first one relies on IP multicast whereas the second one uses point to point communication.

If the managed instances cannot be discovered automatically due to the network configuration or the administration policies, the domain topology can be described statically in the domain.xml file.

JOnAS provides different administration interfaces:

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.balance_workers=worker1,worker2
worker.myloadbalancer.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 JkWorkersFile
# (put workers.properties next to httpd.conf)
/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 /sampleCluster2 myloadbalancer
JkMount /sampleCluster2/* myloadbalancer
JkMount /sampleCluster3 myloadbalancer
JkMount /sampleCluster3/* myloadbalancer
# A mount point to the status worker
JkMount /jkmanager jkstatus
JkMount /jkmanager/* jkstatus

# Copy mount points into all virtual hosts
JkMountCopy All

# 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 cluster member needs an AJP/1.3 connector listening on the port defined in the workers.properties file. Moreover, the worker name (here in the example, worker1/worker2) must be used as value for the Engine's jvmRoute attribute.

Here is a chunk of tomcat6-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" protocol="HTTP/1.1" connectionTimeout="20000"
        redirectPort="9043" />
    <!-- AJP 1.3 Connector on port 9010 for worker.worker1.port in workers.properties file -->
    <Connector port="9010" 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>
      

	Note
	mod_proxy-balancer is available in Apache 2.2 and later.

See the Apache documentation here .

Contrary to mod_jk, mod_proxy_balancer supports HTTP and AJP protocols. Thus the cluster member can specify either an AJP/1.3 connector or a HTTP connector. In both case, the connector port number must be the same than the port number defined in the Apache's configuration file. Moreover, the BalancerMember route parameter must be used as value for the Engine's jvmRoute attribute.

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

Web cluster members are JOnAS instances having the web container 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 tomcat6-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 a configuration of the Cluster element for an all-to-all session replication with the DeltaManager. This works great for small cluster. For larger cluster, BackupManager enables to replicate the session data to one backup node, and only to nodes that have the application deployed. See the documentation for more informations.

      <!-- Define a Cluster element -->
      <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
                 channelSendOptions="8" clustername="mycluster" >
          <Manager className="org.apache.catalina.ha.session.DeltaManager"
                   expireSessionsOnShutdown="false"
                   notifyListenersOnReplication="true"/>
          <Channel className="org.apache.catalina.tribes.group.GroupChannel">
            <Membership className="org.apache.catalina.tribes.membership.McastService"
                        address="228.0.0.4"
                        port="45564"
                        frequency="500"
                        dropTime="3000"/>
            <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
                      address="auto"
                      port="4000"
                      autoBind="100"
                      selectorTimeout="5000"
                      maxThreads="6"/>
            <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
              <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/>
            </Sender>
            <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
            <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/>
          </Channel>
          <Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
                 filter=""/>
          <Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/>
          <ClusterListener className="org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener"/>
          <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>
        </Cluster>
      

	Note
	the clusterName attribute is mandatory for administration purpose (and not set by default in tomcat6-server.xml file).

CMI is an OW2 project providing a framework to define and configure clusters of RMI objects. CMI is embedded both in JOnAS and EasyBeans projects.

The main features are :

	Note
	CMI described in this section is CMI v2 available in JOnAS 5 (not in JOnAS 4).

3.2.1.1.1. Load-balancing algorithm

3.2.1.1.1.1. An example of execution

The following figure shows how to define a weighted round-robin in term of policy and strategy.

An use of the weighted round-robin

3.2.1.1.1.2. General case

The chain strategy -> policy

HA service provides High Availability for the EJB. A first implementation based on the Horizontal replication is delivered for EJB2.1. Other solutions are under development: Terracotta based and pair replication.

3.2.1.2.1. High Availability with Horizontal Replication

Stateful session beans (EJB2.1) can be replicated since JOnAS 4.7 in order to provide high availability in the case of failures in clustered environments. A new service called High Availability (HA) has been included in JOnAS to provide replication mechanisms. JOnAS HA also requires the cluster method invocation (CMI) protocol.

From JOnAS 4.8, a new replication algorithm based on a horizontal replication approach is available. The algorithm improves the algorithm implemented for JOnAS 4.7 with the following enhancements:

• Replication of SFSBs with references to EBs: The algorithm can replicate SFSBs that reference EB by means of both, local or remote interfaces.

• Transaction awareness: The algorithm is transaction aware, meaning that the state is not replicated if the transaction aborts.

• Exactly-once semantics: Each transaction is committed exactly once at the DB if the client does not fail. If the client fails, each transaction is committed at most once at the DB

3.2.1.2.1.1. EJB replication Description

3.2.1.2.1.1.1. Update-everywhere mode

JOnAS implements an update-everywhere replication protocol according to the database replication terminology (See the J. Gray et al.'s paper ''The dangers of replication and a solution'' in proceedings of the ACM SIGMOD 96's conference, Canada). In this protocol, a client can connect to any server. When the client calls the create() method on the SFSB's Home interface, the server the client connects to is selected following a round-robin scheme. All the requests from the client to the SFSB will be processed by this server until the client calls the remove() method on the remote interface. The rest of the servers will act as backups for that client. Before sending the response to the client, the SFSB's state is sent to the backups.

If the server fails, another server among the backups will be selected to serve the client requests, first restoring the current state of the SFSBs from the state information stored in the HA local service. From this point on, this server will receive the new client requests.

The supported replication scenarios are shown in the following figure:

3.2.1.2.1.1.2. Transaction aware fail-over

The horizontal approach aims to guarantee that the transactions are kept consistent when a fail-over occurs. They are either aborted or restored for ensuring the exactly-once semantics. During a fail-over, the new primary uses a special table in the database for storing the transaction identifier and enabling to find out if the transaction was committed or not.

• If the transaction is aborted due to the primary failure, then the new primary will not find the transaction identifier in the special table. The request will be replayed.

• If the transaction is committed, then the new primary will find the transaction identifier, which means that the transaction was committed. The request won't be replayed; the replicated result is returned.

Beyond the SFSB replication, the algorithm enables the building of applications (stateful or stateless) with a high level of reliability and integrity.

The setting of an EJB farm is achieved by

3.2.2.1.1. cmi service configuration

The configuration of the cmi service is available through the file $JONAS_BASE/conf/cmi-config.xml.

The CMI service can be configured in two modes:

• server mode with a cluster view manager created locally, i.e. with a local instance of a replicated CMI registry.

• client mode without a local cluster view manager, in this case a list of providers urls (i.e. a list of cluster view manager urls) is given for accessing to the remote CMI registries.

The server mode is simpler to configure, the client mode requires to define statically a list of providers urls. The server mode starts a Group Communication Protocol instance (e.g. JGroups) and thus increases the resources consumption compare to the client mode.

	Note
	The CMI configuration file may contain two parts: a server element which corresponds to the server mode configuration and a client element for the client mode configuration. If the two are present, only the server element is loaded which means that the server mode is configured.

3.2.2.1.1.1. Server mode configuration

The server element contains the following elements:

Example 3.5. Configuring the cmi service in the server mode

  
<cmi xmlns="http://org.ow2.cmi.controller.common"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:jgroups="http://org.ow2.cmi.controller.server.impl.jgroups">
    <server>
        <jndi> 
            <protocol name="jrmp" noCmi="false" />
        </jndi>
        <viewManager  
            class="org.ow2.cmi.controller.server.impl.jgroups.JGroupsClusterViewManager"> 
            <jgroups:config 
                    delayToRefresh="60000" 
                    loadFactor="100" 
                    confFileName="jgroups-cmi.xml" 
                    recoTimeout="30000" 
                    groupName="G1"> 
                <components> 
                 <event />
                </components>
            </jgroups:config>
        </viewManager>
    </server>
</cmi>

	jndi element - optional. Enable to specify that a protocol must not be clustered with CMI (administration uses, ...). Here, the clustering of jrmp protocol can be disabled by setting true to the noCmi attribute.
	viewManager element - mandatory. Defines the view manager configuration (registry replication, refresh time, ...).
	class attribute - mandatory. Specifies the protocol implementation to use for replicating the view (CMI registry). Here the JGroups implementation is set.
	jgroups:config element - mandatory. Define the JGroups related parameters.
	delayToRefresh attribute - optional. Refresh period of the client view (in ms). For example, it expresses the maximum delay for taking into account a load-balancing parameter update.
	loadFactor attribute - optional. Specifies the initial load-factor of the current node used in the weigthed round robin policy.
	confFileName attribute - mandatory. Specifies the JGroups's stack configuration filename (found in the $JONAS_BASE/conf directory).
	recoTimeout attribute - optional. Specifies the reconnection timeout after a shunning or an error in the group communication protocol (in ms). If the timer expires, an exception is thrown.
	groupName attribute - mandatory. Specifies the JGroups channel name used by the CMI cluster view replication mechanism.
	components element - mandatory. Enable the events component into CMI. This element must not be modified.

	Note
	Refer to the clustering guide for issues related to JGroups.

3.2.2.1.1.2. Client mode configuration

The client element contains the following elements:

Example 3.6. Configuring the cmi service in the client mode

  
<cmi xmlns="http://org.ow2.cmi.controller.common"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <client noCmi="false"> 
    	<jndi> 
        	<protocol name="jrmp">
            	<providerUrls> 
                	<providerUrl>rmi://localhost:1099</providerUrl>
                	<providerUrl>rmi://localhost:2001</providerUrl>
            	</providerUrls>
        	</protocol>
    	</jndi>
    </client>
</cmi>

	noCmi attribute - optional. Enable to specify that CMI must be disabled.
	jndi element - mandatory. Specify a list of providers URLs for a given protocol. It is not necessary to set the whole list of cluster members, a subset is enough. However for ensuring high availability, at least two providers URLs must be mentionned.

3.2.2.1.2. Registry distribution (server mode)

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

• $JONAS_BASE/conf/cmi-config.xml for specifying the JGroups configuration file name and the JGroups group name.

• $JONAS_BASE/conf/jgroups-cmi.xml file for the settings of the jgroups protocol stack. By default, the JGroups configuration uses the UDP protocol and the multicast IP for broadcasting the registry updates. A TCP-based stack can be used in a network environment that does not allow the use of multicast IP or when a cluster is distributed over a WAN.

For example, the jgroups-cmi.xml file may contain the following stack configuration:

Example 3.7. JGroups's configuration stack

<config>
    <UDP mcast_addr="224.0.0.35"
         mcast_port="35467"
         tos="8"
         ucast_recv_buf_size="20000000"
         ucast_send_buf_size="640000"
         mcast_recv_buf_size="25000000"
         mcast_send_buf_size="640000"
         loopback="false"
         discard_incompatible_packets="true"
         max_bundle_size="64000"
         max_bundle_timeout="30"
         use_incoming_packet_handler="true"
         ip_ttl="2"
         enable_bundling="true"
         enable_diagnostics="true"
         thread_naming_pattern="cl"

         use_concurrent_stack="true"

         thread_pool.enabled="true"
         thread_pool.min_threads="1"
         thread_pool.max_threads="25"
         thread_pool.keep_alive_time="5000"
         thread_pool.queue_enabled="false"
         thread_pool.queue_max_size="100"
         thread_pool.rejection_policy="Run"

         oob_thread_pool.enabled="true"
         oob_thread_pool.min_threads="1"
         oob_thread_pool.max_threads="8"
         oob_thread_pool.keep_alive_time="5000"
         oob_thread_pool.queue_enabled="false"
         oob_thread_pool.queue_max_size="100"
         oob_thread_pool.rejection_policy="Run"/>

    <PING timeout="2000"
            num_initial_members="3"/>
    <MERGE2 max_interval="30000"
            min_interval="10000"/>
    <FD_SOCK/>
    <FD timeout="2000" max_tries="3" shun="true"/>
    <VERIFY_SUSPECT timeout="1500"  />
    <BARRIER />
    <pbcast.NAKACK max_xmit_size="60000"
                   use_mcast_xmit="false" gc_lag="0"
                   retransmit_timeout="300,600,1200,2400,4800"
                   discard_delivered_msgs="true"/>
    <UNICAST timeout="300,600,1200,2400,3600"/>
    <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
                   max_bytes="400000"/>
    <VIEW_SYNC avg_send_interval="60000"   />
    <pbcast.GMS print_local_addr="true" join_timeout="3000"
                join_retry_timeout="2000" shun="true" />
    <SEQUENCER/>
    <FC max_credits="20000000"
                    min_threshold="0.10"/>
    <!--pbcast.STREAMING_STATE_TRANSFER use_reading_thread="true"/-->
    <pbcast.STATE_TRANSFER  />
    <!-- pbcast.FLUSH  /-->
</config>
      

	Note
	You can find more information about JGroups and about the stack configuration here.

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:

• JGroups group name

• JGroups multicast address

• JGroups multicast port

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.

package org.ow2.cmi.lb.policy;

import java.lang.reflect.Method;
import java.util.Collection;

import org.ow2.cmi.lb.LoadBalanceable;
import org.ow2.cmi.lb.NoLoadBalanceableException;
import org.ow2.cmi.lb.decision.DecisionManager;
import org.ow2.cmi.lb.strategy.IStrategy;

/**
* Interface of the policies for load-balancing.
* @param <T> The type of object that was load-balanced
* @author The new CMI team
*/
public interface IPolicy<T extends LoadBalanceable> {

    /**
     * Chooses a load-balanceable among the list of load-balanceables.
     * @param loadBalanceables a list of load-balanceables
     * @throws NoLoadBalanceableException if no server is available
     * @return the chosen load-balanceable
     */
    T choose(Collection<T> loadBalanceables) throws NoLoadBalanceableException;

    /**
     * Return a strategy to modify the behavior of this policy.
     * @return a strategy to modify the behavior of this policy
     */
    IStrategy<T> getStrategy();

    /**
     * Sets a strategy to modify the behavior of this policy.
     * @param strategy a strategy of load-balancing
     */
    void setStrategy(IStrategy<T> strategy);

    /********************** Begin of callback definitions **********************/

    /**
     * Returns a decision when an exception is thrown during an access to a registry
     * for a given load-balanceable.
     * @param loadBalanceable the load-balanceable that have caused the exception
     * @param thr the exception that is thrown
     * @return the decision when an exception is thrown during an access to a registry
     * for a given load-balanceable
     */
    DecisionManager<Void> onLookupException(T loadBalanceable, Throwable thr);

    /**
     * Returns a decision when an exception is thrown during an invocation for a given
     * load-balanceable.
     * @param method the method that was invoked
     * @param parameters the parameters of the method
     * @param loadBalanceable the load-balanceable that have caused the exception
     * @param thr the exception that is thrown
     * @return the decision when an exception is thrown during an invocation for a given
     * load-balanceable
     */
    DecisionManager<Void> onInvokeException(Method method, Object[] parameters, T loadBalanceable, Throwable thr);

    /**
     * Return a decision when a server is chosen and its delegate retrieved.
     * @param <ReturnType> the type of delegate
     * @param method the method that was invoked
     * @param parameters the parameters of the method
     * @param chosenValue the delegate of chosen server
     * @return the decision when the server is chosen and its delegate retrieved
     */
    <ReturnType> DecisionManager<ReturnType> onChoose(Method method, Object[] parameters, ReturnType chosenValue);

    /**
     * Returns a decision when the invocation of a remote method ends.
     * @param <ReturnType> the type of the returned value
     * @param method the method that was invoked
     * @param parameters the parameters of the method
     * @param loadBalanceable the load-balanceable used for the invocation
     * @param retVal the returned value
     * @return the decision when the invocation of a remote method ends
     */
    <ReturnType> DecisionManager<ReturnType> onReturn(Method method, Object[] parameters, T loadBalanceable, ReturnType retVal);

}
        			

package org.ow2.cmi.lb.policy;

import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.Random;

import net.jcip.annotations.ThreadSafe;

import org.ow2.cmi.lb.LoadBalanceable;
import org.ow2.cmi.lb.NoLoadBalanceableException;
import org.ow2.cmi.lb.strategy.IStrategy;
import org.ow2.cmi.lb.strategy.NoStrategy;
import org.ow2.util.log.Log;
import org.ow2.util.log.LogFactory;
/**
 * The default load-balancing policy (Round Robin) that always chooses the next available load-balanceable.
 * @param <T> The type of objects that are load-balanced
 * @author The new CMI team
 */
@ThreadSafe
public final class RoundRobin<T extends LoadBalanceable> extends AbstractPolicy<T> {

    /**
     * Logger.
     */
    private static final Log LOGGER = LogFactory.getLog(RoundRobin.class);

    /**
     * Initial value of the pointer.
     */
    private static final int INITIAL_VALUE = -1;

    /**
     * The pointer to store the last ref.
     */
    private int pointer;

    /**
     * Random numbers.
     */
    private final Random rand = new Random();

    /**
     * Build the Round Robin policy.
     * Give to the pointer an initial value.
     */
    public RoundRobin() {
        pointer = INITIAL_VALUE;
    }

    /**
     * Chooses the next load-balanceable among the list of load-balanceables.
     * @param loadBalanceables the list of load-balanceables
     * @throws NoLoadBalanceableException if no server available
     * @return the chosen load-balanceable
     */
    @Override
    public synchronized T choose(final Collection<T> loadBalanceables) throws NoLoadBalanceableException{

        if (loadBalanceables == null || loadBalanceables.isEmpty()) {
            LOGGER.error("The given list is null or empty: " + loadBalanceables);
            throw new NoLoadBalanceableException("The given list is null or empty: " + loadBalanceables);
        }
        List<T> cmiRefsWithStrategy;

        IStrategy<T> strategy = getStrategy();

        if(strategy != null) {
            cmiRefsWithStrategy = strategy.choose(loadBalanceables);
            // If no server corresponds at this strategy, we don't use it
            if(cmiRefsWithStrategy.isEmpty()) {
                cmiRefsWithStrategy = new ArrayList<T>(loadBalanceables);
            }
        } else {
            cmiRefsWithStrategy = new ArrayList<T>(loadBalanceables);
        }

        int size = cmiRefsWithStrategy.size();
		if(pointer == INITIAL_VALUE){
            // The initial pointer depends on the strategy
            if(strategy != null && !(strategy instanceof NoStrategy)) {
                // Use the first element chosen by the strategy
                pointer = 0;
            } else {
                // No strategy, choose randomly the first element
                pointer = rand.nextInt(size);
            }
        } else {
            // Perhaps some servers are disappeared, in this case the pointer can out of bounds
            if(pointer >= size) {
                pointer = INITIAL_VALUE;
            }
            // Choose the next target
            pointer = (pointer + 1) % size;
        }
        return cmiRefsWithStrategy.get(pointer);
    }

    @Override
    public String toString() {
        return "RoundRobin[pointer: "
        + pointer + " - strategy: " + getStrategy() + "]";
    }

}			        

package org.ow2.cmi.lb.strategy;

import java.util.Collection;
import java.util.List;

import org.ow2.cmi.lb.LoadBalanceable;

/**
 * Interface of the load-balancing strategies.
 * A strategy allows to modify a list of load-balanceables before applying a policy to elect only one load-balanceable.
 * @param <T> The type of object that was load-balanced
 * @author The new CMI team
 */
public interface IStrategy<T extends LoadBalanceable> {

    /**
     * Returns a new list of load-balanceables by modifying the given list.
     * @param loadBalanceables a list of load-balanceables
     * @return a new list of load-balanceables by modifying the given list
     */
    List<T> choose(Collection<T> loadBalanceables);

}
        			

package org.ow2.cmi.lb.strategy;

import java.net.InetAddress;
import java.net.NetworkInterface;
import java.net.SocketException;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;

import net.jcip.annotations.Immutable;

import org.ow2.cmi.controller.client.ClientClusterViewManager;
import org.ow2.cmi.controller.common.ClusterViewManager;
import org.ow2.cmi.controller.server.ServerClusterViewManager;
import org.ow2.cmi.lb.LoadBalanceable;
import org.ow2.cmi.reference.ServerRef;
import org.ow2.util.log.Log;
import org.ow2.util.log.LogFactory;

/**
 * Defines a strategy that enable the local preference.
 * @param <T> The type of objects that are load-balanced
 * @author The new CMI team
 */
@Immutable
public final class LocalPreference<T extends LoadBalanceable> implements IStrategy<T> {

    /**
     * Logger.
     */
    private static final Log LOGGER = LogFactory.getLog(LocalPreference.class);

    /**
     * The manager of the cluster view.
     */
    private final ClusterViewManager clusterViewManager;

    /**
     * Constructs a strategy for load-factor.
     * @param clusterViewManager the manager of the cluster view
     */
    public LocalPreference(final ClusterViewManager clusterViewManager) {
        this.clusterViewManager = clusterViewManager;
    }

    /**
     * Returns a list of CMIReference that references the local servers.
     * @param cmiRefs a list of CMIReference
     * @return a list of CMIReference that references the local servers
     */
    public List<T> choose(final Collection<T> cmiRefs) {

        List<T> localServers = new ArrayList<T>();

        for(T cmiRef : cmiRefs) {

            // Gets the reference of server that have deployed the object
            ServerRef serverRef = cmiRef.getServerRef();

            //  Gets its address
            InetAddress inetAddress = serverRef.getInetAddress();

            try {
                // Checks if the addresses match
                if(isLocal(inetAddress)) {
                    // Local address: adds reference in the first position
                    localServers.add(cmiRef);
                }
            } catch (SocketException e) {
                LOGGER.error("Cannot know if is local or not", e);
                throw new RuntimeException("Cannot know if is local or not", e);
            }
        }
        return localServers;
    }

    /**
     * Tests if an address is local.
     * @param inetAddress an address
     * @return true if the given address is local
     * @throws SocketException if an I/O error occurs
     */
    private boolean isLocal(final InetAddress inetAddress) throws SocketException {

        if(clusterViewManager instanceof ClientClusterViewManager) {
            if(NetworkInterface.getByInetAddress(inetAddress)!=null) {
                return true;
            }
        } else if(clusterViewManager instanceof ServerClusterViewManager) {
            if(inetAddress.equals(((ServerClusterViewManager) clusterViewManager).getInetAddress())) {
                return true;
            }
        }
        return false;
    }

    @Override
    public String toString() {
        return "LocalPreference";
    }

}
			        

<cluster-config>
...
    <properties>
        <simple-property name="prop1" value="val1" />
        <simple-property name="prop2" value="38" />
        <array-property name="prop3">
            <value>true</value>
        </array-property>
        <array-property name="prop4">
            <value>java.util.LinkedList</value>
            <value>java.util.ArrayList</value>
        </array-property>
        <array-property name="prop5">
            <value>http://carol.ow2.org</value>
        </array-property>
    </properties>
</cluster-config>

           						

<jonas-ejb-jar 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-ejb-jar_5_1.xsd">

    <jonas-session>
        <ejb-name>MyEjb1SLR</ejb-name>
        <jndi-name>MyEjb1Home</jndi-name>
        <min-pool-size>3</min-pool-size>
        <cluster-config>
        	<name>jonas-cluster</name>
        	<policy>org.ow2.cmi.lb.policy.RoundRobin</policy>
        	<strategy>org.ow2.cmi.lb.strategy.LocalPreference</strategy>
        	<pool>
           		<max-size>10</max-size>
            	<max-waiters>15</max-waiters>
            	<timeout>2000</timeout>
           </pool>
       </cluster-config>
    </jonas-session>
</jonas-ejb-jar>
            

@Cluster(name="test_cluster", pool=@Pool(max=2))
									

@Policy(RoundRobin.class)
									

@Strategy(LocalPreference.class)
									

@Properties(
  simpleProperties={
    @SimpleProperty(
      name="prop1",
      value="val1"),
    @SimpleProperty(
      name="prop2",
      value="38")},
  arrayProperties={
    @ArrayProperty(
      name="prop3"
      values="true"),
    @ArrayProperty(
      name="prop4",
      values={"java.util.LinkedList",
              "java.util.ArrayList"}),
    @ArrayProperty(
      name="prop5",
      values={"http://www.ow2.org"})})
									

package org.ow2.easybeans.examples.cluster;

import javax.ejb.Remote;
import javax.ejb.Stateless;

import org.ow2.cmi.annotation.Cluster;
import org.ow2.cmi.annotation.Policy;
import org.ow2.cmi.lb.policy.RoundRobin;
import org.ow2.easybeans.api.bean.EasyBeansBean;

@Stateless
@Remote(ClusterRemote.class)
@Cluster(name="test_cluster")
@Policy(RoundRobin.class)
public class ClusterBeanAN implements ClusterRemote {

    private String ezbServerDescription = null;

    public String getEZBServerDescription(final String msg) {

        if(this.ezbServerDescription == null) {
            this.ezbServerDescription =
                ((EasyBeansBean) this).getEasyBeansFactory().getContainer().getConfiguration().getEZBServer().getDescription();
        }
        System.out.println(msg);
        return this.ezbServerDescription + "\n";
    }
}
            

<cluster:cluster>
...
    <properties>
        <simple-property name="prop1" value="val1" />
        <simple-property name="prop2" value="38" />
        <array-property name="prop3">
            <value>true</value>
        </array-property>
        <array-property name="prop4">
            <value>java.util.LinkedList</value>
            <value>java.util.ArrayList</value>
        </array-property>
        <array-property name="prop5">
            <value>http://carol.ow2.org</value>
        </array-property>
    </properties>
</cluster:cluster>
								

<easybeans xmlns="http://org.ow2.easybeans.deployment.ejb"
	xmlns:cluster="http://org.ow2.cmi.info.mapping">
	<ejb>
 		<session>

			<ejb-name>clusterXMLBean</ejb-name>
			<cluster:cluster name="easybeans-cmi">
				<cluster:policy>org.ow2.cmi.lb.policy.FirstAvailable</cluster:policy>
				<cluster:strategy>org.ow2.cmi.lb.strategy.LocalPreference</cluster:strategy>
        	    <pool>
           		    <max-size>10</max-size>
            	    <max-waiters>15</max-waiters>
            	    <timeout>2000</timeout>
                </pool>
			</cluster:cluster>
		</session>
	</ejb>
</easybeans>
            

EJB clustering can be transparent for the client so that a client which is connected to a standalone server can be switched to a clustering mode without any configuration changes.

However either for disabling CMI and for ensuring the JNDI availability, a CMI configuration can be required.

java -jar myclient.jar -cp<...> -Dcmi.conf.url=/tmp/cmi-config.xml
           						

jclient -jar myclient.jar -Dcmi.disabled=true
           							

<cmi xmlns="http://org.ow2.cmi.controller.common"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <client noCmi="true" />
</cmi>
           							

3.2.2.2.3. Cluster view manager fail-over

CAROL is a the JOnAS's protocol abstract layer and the carol.properties indicates the default protocol and the registry URL. The client retrieves the cluster view from the server side. By default it gets in touch with the server identified by the CAROL configuration. For ensuring high availability of the service, a list of cluster view manager URLs can be provided to the client through the CMI configuration file. Refer to Section 3.2.2.1.1, “cmi service configuration” for a precise information about the setting. Example:

Example 3.13. CMI configuration at the client side

<cmi xmlns="http://org.ow2.cmi.controller.common"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <client noCmi="false">
    	<jndi>
        	<protocol name="jrmp">
            	<providerUrls>
                	<providerUrl>rmi://localhost:1099</providerUrl>
                	<providerUrl>rmi://localhost:2001</providerUrl>
            	</providerUrls>
        	</protocol>
    	</jndi>
    </client>
</cmi>
           							

A first available policy with local preference is applied for selecting a provider URL. If the primary gets unavailable, a secondary is selected randomly at fail-over.

	Note
	In the case of a web tier which acts as a CMI client (CMI service with client mode), a list of provider URLs must be specified in the $JONAS_BASE/conf/cmi-config.xml file.

As for the farming, the cluster mode can be transparent for the client configuration apart for the expected high availability of the CMI internals service. In particular the CMI cluster view manager client part must be configure with a list of provider urls in order to be able to take-over when a server node failure occurs. Refer to Section 3.2.2.2, “At the client side” for a precise information about the setting.

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 provided with JOnAS ($JONAS_ROOT/examples/javaee5-earsample) uses a very simple configuration (centralized) made of one server hosting a queue and/or 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 chapter gives an overview of the JORAM capabilities for clustering a JMS application in the Java EE 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:

Install and configure two JOnAS instances (see here ). The newjc tool may be used for generating the initial configuration of the JMS cluster. The tool may be run with the default inputs except for the architecture (bothWebEjb) and number of nodes (2). Refer to Section 5.1, “newjc command” for further information about the newjc tool.

The MDB application is based on an example from the EasyBeans project. You can download the full source code of the application in the EasyBeans project under the example/messagedrivenbean directory. A user guide for compiling the example is given here

By default, The messagedrivenbean is bound to a JMS Queue and later in the documentation we will see how to change it for using a Topic instead. The implementation is :

package org.ow2.easybeans.examples.messagedrivenbean;

import javax.ejb.ActivationConfigProperty;
import javax.ejb.MessageDriven;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageListener;
import javax.jms.TextMessage;

@MessageDriven(activationConfig = {
        @ActivationConfigProperty(propertyName = "destination", propertyValue = "SampleQueue"),
        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue")
        }
)
public class MessageDrivenBean implements MessageListener {

    public void onMessage(final Message message) {
        String txt = "Receiving a message named '" + message + "'.";
        if (message instanceof TextMessage) {
            try {
                txt += " with the content '" + ((TextMessage) message).getText();
            } catch (JMSException e) {
                e.printStackTrace();
            }
        }
        System.out.println(txt);
    }

}
          

Here the client application is extracted from the EasyBeans project as well. The client code sends a few messages towards the JMS object. The code is:

package org.ow2.easybeans.examples.messagedrivenbean;

import java.util.Hashtable;

import javax.jms.Queue;
import javax.jms.QueueConnection;
import javax.jms.QueueConnectionFactory;
import javax.jms.QueueSender;
import javax.jms.QueueSession;
import javax.jms.Session;
import javax.jms.TextMessage;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

public final class ClientMessageDriven {

    private static final String QUEUE_CONNECTION_FACTORY = "JQCF";
    private static final String SAMPLE_QUEUE = "SampleQueue";
    private static final int NUMBER_MESSAGES = 5;
    private static final String
            DEFAULT_INITIAL_CONTEXT_FACTORY = "org.objectweb.carol.jndi.spi.MultiOrbInitialContextFactory";

    private ClientMessageDriven() {

    }

    public static void main(final String[] args) throws Exception {

        Context initialContext = getInitialContext();

        QueueConnectionFactory queueConnectionFactory = (QueueConnectionFactory) initialContext
                .lookup(QUEUE_CONNECTION_FACTORY);

        // Lookup the Queue through its JNDI name
        Queue queue = (Queue) initialContext.lookup(SAMPLE_QUEUE);

        // Create connection
        QueueConnection queueConnection = queueConnectionFactory.createQueueConnection();

        // Create session
        QueueSession queueSession = queueConnection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);

        // Create sender
        QueueSender queueSender = queueSession.createSender(queue);

        // Send messages
        TextMessage message = null;
        for (int i = 0; i < NUMBER_MESSAGES; i++) {
            message = queueSession.createTextMessage();
            String text = "Message_" + i;
            message.setText(text);
            queueSender.send(message);
            System.out.println("Message [" + message.getJMSMessageID() + ", text:" + text + "] sent");

        }

        // Close JMS objects
        queueSender.close();
        queueSession.close();
        queueConnection.close();

    }

    private static Context getInitialContext() throws NamingException {

        Hashtable<String, Object> env = new Hashtable<String, Object>();
        env.put(Context.INITIAL_CONTEXT_FACTORY, DEFAULT_INITIAL_CONTEXT_FACTORY);
        return new InitialContext(env);
    }
}
          

In this case, the client application must be adapted for publishing a message to a topic. Only the touched lines are shown:

...
import javax.jms.Topic;
import javax.jms.TopicConnection;
import javax.jms.TopicConnectionFactory;
import javax.jms.TopicPublisher;
import javax.jms.TopicSession;

...
    private static final String TOPIC_CONNECTION_FACTORY = "JTCF";
    private static final String SAMPLE_TOPIC = "sampleTopic";
...

        // Get factory
        TopicConnectionFactory topicConnectionFactory = (TopicConnectionFactory) initialContext
                .lookup(TOPIC_CONNECTION_FACTORY);

        // Lookup the Topic through its JNDI name
        Topic topic = (Topic) initialContext.lookup(SAMPLE_TOPIC);

        // Create connection
        TopicConnection topicConnection = topicConnectionFactory.createTopicConnection();

        // Create session
        TopicSession topicSession = topicConnection.createTopicSession(false, Session.AUTO_ACKNOWLEDGE);

        // Create publisher
        TopicPublisher topicPublisher = topicSession.createPublisher(topic);

        // Send messages
        TextMessage message = null;
        for (int i = 0; i < NUMBER_MESSAGES; i++) {
            message = topicSession.createTextMessage();
            String text = "Message_" + i;
            message.setText(text);
            topicPublisher.publish(message);
            System.out.println("Message [" + message.getJMSMessageID() + ", text:" + text + "] sent");

        }

        // Close JMS objects
        topicPublisher.close();
        topicSession.close();
        topicConnection.close();

    }
...
          

When using jclient container, the client will connect to the server which is pointed by $JONAS_BASE/conf/carol.properties. You can specify another one with the -carolFile option.

jclient ./clients/client-mdb.jar -carolFile ./carol.properties
          

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". These 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 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 cluster definition with the topics must be added in $JONAS_BASE/conf/joramAdmin.xml file. The connection factories and the anonymous user must be defined with the local server id and the local server port number according to the a3servers.xml content. Here only the cluster related elements are shown:

	Note
	The mdbTopic jndi name is bound in the local JOnAS registry with the local cluster element, i.e. mdbTopic1 for server id 1 and mdbTopic2 for server id 2.

Note

The joramAdmin.xml file has to be loaded when all cluster members are started since some remote cluster elements are defined. An alternative consists in splitting the configuration into two different files joramAdmin-local.xml and joramAdmin-cluster.xml, the first one containing only the local elements and the second one, both local and remote elements. At the JOnAS starting, a script could copy the right file to joramAdmin.xml according to the others members presence (joramAdmin-local.xml if it's the first member which starts and joramAdmin-cluster.xml if all the cluster members are started).

The @MessageDriven annotation is updated in the source code for binding the MDB with the clustered topic. That could be done through the optional deployment descriptor as well.

@MessageDriven(activationConfig = {
        @ActivationConfigProperty(propertyName ="destination", propertyValue ="mdbTopic"),
        @ActivationConfigProperty(propertyName ="destinationType", propertyValue ="javax.jms.Topic")
        }
)
        

The client code for sending a message to a Topic is used and the topic name is set to:

    private static final String SAMPLE_TOPIC = "mdbTopic";
        

Deploy the MDB application in each JOnAS instance and run the sample. The messages do appear on the two different JOnAS servers consoles that shows the messages broadcasting between the topic elements.

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 :

Note

The joramAdmin.xml file has to be loaded when all cluster members are started since some remote cluster elements are defined. An alternative consists in splitting the configuration into two different files joramAdmin-local.xml and joramAdmin-cluster.xml, the first one containing only the local elements and the second one, both local and remote elements. At the JOnAS starting, a script could copy the right file to joramAdmin.xml according to the others members presence (joramAdmin-local.xml if it's the first member which starts and joramAdmin-cluster.xml if all the cluster members are started).

The @MessageDriven annotation is set with the mdbQueue queue. That could be done through the optional deployment descriptor as well.

@MessageDriven(activationConfig = {
        @ActivationConfigProperty(propertyName ="destination", propertyValue ="mdbQueue"),
        @ActivationConfigProperty(propertyName ="destinationType", propertyValue ="javax.jms.Queue")
        }
)
        

The client code for the Queue is used and the queue name is set to:

    private static final String SAMPLE_Queue = "mdbQueue";
        

The loop number can be increased in order to generate some pending messages in the first server:

    private static final int NUMBER_MESSAGES = 1000;
        

Deploy the MDB application in each JOnAS instance and run the sample. The messages do appear on the two different JOnAS servers consoles that shows the load-balacing at the server side.

In JORAM terminology, 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 (element of the JORAM HA cluster, master or slave) 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 (MDB). 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="1" name="s1">

    <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="1" name="s1">

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

    <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="16010"/>
      <service class="org.objectweb.joram.client.jms.ha.local.HALocalConnection"/>
    </server>

    <server id="2" hostname="localhost">
      <network domain="D1" port="16302"/>
      <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>1</config-property-value>
      </config-property>
        

Deploy the MDB application in each JOnAS instance and start them.

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 the client:

Messages are sent on the JOnAS instance 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.

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.

Not available yet.

The configuration may 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) in jonas.properties file.

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 (that may be encoded) 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:

       
<?xml version="1.0" encoding="UTF-8"?>
<domain 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-domain_4_9.xsd">
  <name>sampleCluster2Domain</name>
  <description>A domain for sampleCluster2 servers management</description>

	<cluster-daemon>
		<name>cd</name>
		<description></description>
		<location>
		   <url>service:jmx:rmi://localhost/jndi/rmi://localhost:1806/jrmpconnector_cd</url>
		</location>
	</cluster-daemon>
	<cluster>
	   <name>mycluster</name>
	  <description>A cluster for sampleCluster2</description>
		<server>
		   <name>node1</name>
		   <location>
			<url>service:jmx:rmi://localhost/jndi/rmi://localhost:2002/jrmpconnector_node1</url>
		   </location>
		   <cluster-daemon>cd</cluster-daemon>
		</server>
		<server>
		   <name>node2</name>
		   <location>
			<url>service:jmx:rmi://localhost/jndi/rmi://localhost:2022/jrmpconnector_node2</url>
		   </location>
		   <cluster-daemon>cd</cluster-daemon>
		</server>
		<server>
		   <name>node3</name>
		   <location>
			<url>service:jmx:rmi://localhost/jndi/rmi://localhost:2032/jrmpconnector_node3</url>
		   </location>
		   <cluster-daemon>cd</cluster-daemon>
		</server>
		<server>
		   <name>node4</name>
		   <location>
			<url>service:jmx:rmi://localhost/jndi/rmi://localhost:2043/jrmpconnector_node4</url>
		   </location>
		   <cluster-daemon>cd</cluster-daemon>
		</server>
	</cluster>

</domain>       
       

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 (such as jconsole), running on the master:

Policies and strategies can be updated dynamically from jonasAdmin console.

From the clustered object information page, you can select another policy :

or strategy :

Refer to the Section 3.2.2.1.3.1, “Overview” section for more information.

Load-factor can be updated dynamically by clicking on a server in the CMI tab page :

The server information page contains a load-factor which can be modified dynamically:

To start and halt the cluster, use the jcl4sc (jcl4sc.bat) command generated by newjc in the root of the JOnAS bases.

jcl4sc -c start allows to start the cluster, included the cluster daemon, the db node, the master node and the jbx nodes.

jcl4sc halt allows to halt the cluster.

You may type jcl4sc -help to get the usage of the command.

The sampleCluster2 application is automatically deployed on the cluster if you have previously build it, before using the jcl4sc command.

The application is available at http://<hostname>:<apache-port>/sampleCluster2.

Example: http://localhost:80/sampleCluster2

To start and halt the cluster, use the jcl4sc (jcl4sc.bat) command generated by newjc in the root of the JOnAS bases.

jcl4sc -c start allows to start the cluster, included the cluster daemon, the db node, the master node and the jbx nodes.

jcl4sc halt allows to halt the cluster.

You may type jcl4sc -help to get the usage of the command.

The sampleCluster3 application is automatically deployed on the cluster if you have previously build it, before using the jcl4sc command.

The application is available at http://<hostname>:<apache-port>/sampleCluster3.

Example: http://localhost:80/sampleCluster3

No, CMIv2 relies on Carol V3.x and is not compliant with JOnAS 4. By the way CMIv2 requires JDK5 and higher.

No, new CMI (v2) is completely transparent for the client and doesn't require a pre-compilation step which is different from CMI v1 in JOnAS 4.

EJB application doesn't require any change provided that the application design is clustering safe. Typically static field must not be used. If no clustering annotation are set into the POJO, the specific deployment descriptor can be added for describing the load-balancing logic.

To select the right network interface, set your IP with the attribute bind_addr of the element UDP into the JGroups configuration files:

<config>
    <UDP bind_addr="192.168.0.1"
    ...
    />
...
</config>

JGroups 2.2 doesn't support IPv6. It must be disabled in the JVM by setting the java.net.preferIPv4Stack to true. JGroups 2.2 is used both in the cmi and discovery services in JOnAS 4. JOnAS 5 embeds JGroups 2.6 that supports quite well IPv6.

In JOnAS 4, when IPv6 is not disabled, the following exceptions may appear:

...
TP.down : failed sending message with java.io.IOException: Invalid argument
...
org.jgroups.ChannelException: failed to start protocol stack
        

Parameter setting example with linux/unix system:

export JAVA_OPTS="$JAVA_OPTS -Djava.net.preferIPv4Stack=true"
      

JGroups 2.2 doesn't support JDK6. The problem is due to the JDK and is documented by Sun here. JGroups is used both in the cmi, ha and discovery services in JOnAS 4.

In a configuration JOnAS 4/JDK6, the following exceptions may appear:

...
org.jgroups.ChannelException: failed loading class
...
        

The workaround consists in setting the sun.lang.ClassLoader.allowArraySyntax jvm property to true. Example of such setting in a linux system:

export JAVA_OPTS="$JAVA_OPTS -Dsun.lang.ClassLoader.allowArraySyntax=true"
      

Yes, JOnAS provides a cluster daemon which acts as a JOnAS instances bootstrap. The cluster daemon exposes a JMX remote interface enabling the remote control.