This document introduces basic clustering setup for Entity Beans, Stateful Session Beans and Stateless Session Beans. More advanced documentation will soon be available.

Clustering should be considered in alpha state. Feedback is highly welcome.

Clustering is built on top of the JavaGroups framework and requires JDK 1.3.x.

In order to create a cluster of JBoss nodes, you simply need to launch several JBoss (with clustering activated, see below) instances on different hosts. JBoss instances will automatically detect their neighbors and form a cluster.

Clustering features are available in the pre 3.0 sources. First get the latest sources from CVS or download one of the sources daily snapshot. You then need to build JBoss server (run jboss-all/build/build.bat or jboss-all/build/build.sh). For more information read this the section called “Downloading the Documentation Example Source”.

The resulting JBoss server can be found in jboss-all/build/output/jboss-3.0.0alpha.

To activate global clustering support, you need to copy the file jboss-all/cluster/etc/cluster-service.xml in the /deploy directory of your newly built JBoss server. Clustering is now activated in your JBoss server.

To make a Stateless Session Bean (SLSB) active in a cluster, you need to modify its deployment settings in jboss.xml:

<jboss>
	<enterprise-beans>
		<session>
			<ejb-name>nextgen.StatelessSession</ejb-name>
			<jndi-name>nextget.StatelessSession</jndi-name>
			<clustered>True</clustered>
		</session>
	</enterprise-beans>
</jboss>
			

Thus, you simply need to add the <clustered> tag to your existing jboss.xml configuration file.

To make a Stateful Session Bean (SFSB) active in a cluster, you need to modify its deployment settings in jboss.xml:

<jboss>
	<enterprise-beans>
		<session>
			<ejb-name>nextgen.StatefulSession</ejb-name>
			<jndi-name>nextget.StatefulSession</jndi-name>
			<clustered>True</clustered>
		</session>
	</enterprise-beans>
</jboss>
			

Thus, like for SLSB, you simply need to add the <clustered> tag to your existing jboss.xml configuration file. By default, bean state is replicated in-memory in sub-groups of two nodes.

To make an Entity Bean (EB) active in a cluster, you need to modify its deployment settings in jboss.xml:

<jboss>
	<enterprise-beans>
		<entity>
			<ejb-name>nextgen.EnterpriseEntity</ejb-name>
			<jndi-name>nextget.EnterpriseEntity</jndi-name>
			<clustered>True</clustered>
		</entity>
	</enterprise-beans>
</jboss>
			

Thus, like for SLSB and SFSB, you simply need to add the <clustered> tag to your existing jboss.xml configuration file. By default, bean state is replicated in-memory in sub-groups of two nodes.

As Entity Beans clustering in JBoss is based on pessimistic locking at the database level, your database must support SQL instruction like "SELECT ... FOR UPDATE". Check in your database documentation if it supports such a feature.

Note: Entity Beans clustering has currently only been tested with Oracle.

By default, client code use the standard JBoss JNDI provider: JNP.

Nevertheless, a Highly Available (HA) JNDI server can also be used. To use it, you must have a list of cluster nodes in the provider URL list separated by commas (HA-JNDI default port is 1100):

java.naming.provider.url=server1:1100,server2:1100,server3:1100

Note that automatic discovery of HA-JNDI host is not yet available but is a planned feature.