13. Clustering

The clustering mechanism uses JMS to provide distribution and fail-over on multiple JBI containers.

Features

transparent remoting
rollback and redelivery when a JBI exchange fail
load balancing among JBI containers able to handle a given exchange
pause new exchanges processing when the number of concurrently processed messages reach a given threshold

Installation

The JBI cluster engine is not installed by default in ServiceMix NMR. The main reason is that it requires a JMS broker to be available and none is included inside the distribution.

Using ActiveMQ

If you plan to use ActiveMQ (which is recommended), you can use the following configuration to create the cluster engine:

    <bean id="clusterEngine" class="org.apache.servicemix.jbi.cluster.engine.ClusterEngine">
        <property name="pool">
            <bean class="org.apache.servicemix.jbi.cluster.requestor.ActiveMQJmsRequestorPool">
                <property name="connectionFactory" ref="connectionFactory" />
                <property name="destinationName" value="${destinationName}" />
            </bean>
        </property>
        <property name="name" value="${clusterName}" />
    </bean>

    <osgi:list id="clusterRegistrations"
               interface="org.apache.servicemix.jbi.cluster.engine.ClusterRegistration"
               cardinality="0..N">
       <osgi:listener ref="clusterEngine" bind-method="register" unbind-method="unregister" />
    </osgi:list>

    <osgi:reference id="connectionFactory" interface="javax.jms.ConnectionFactory" />

    <osgi:service ref="clusterEngine">
        <osgi:interfaces>
            <value>org.apache.servicemix.nmr.api.Endpoint</value>
            <value>org.apache.servicemix.nmr.api.event.Listener</value>
            <value>org.apache.servicemix.nmr.api.event.EndpointListener</value>
            <value>org.apache.servicemix.nmr.api.event.ExchangeListener</value>
        </osgi:interfaces>
        <osgi:service-properties>
            <entry key="NAME" value="${clusterName}" />
        </osgi:service-properties>
    </osgi:service>

    <osgix:cm-properties id="clusterProps" persistent-id="org.apache.servicemix.jbi.cluster.config">
        <prop key="clusterName">${servicemix.name}</prop>
        <prop key="destinationName">org.apache.servicemix.jbi.cluster</prop>
    </osgix:cm-properties>

    <ctx:property-placeholder properties-ref="clusterProps" />

This configuration is the default one for ActiveMQ and is provided inside an OSGi bundle. It will use a JMS ConnectionFactory retrieved from OSGi.

If you want to use this default configuration, a simple way to create and configure the cluster engine is to drop a feature descriptor in the deploy folder of your ServiceMix NMR / Kernel:

<features>
    <repository>mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/${servicemix.nmr.version}/xml/features</repository>
    <repository>mvn:org.apache.servicemix.features/apache-servicemix/${servicemix.features.version}/xml/features</repository>
    <feature name="cluster-example-smx2">
        <config name="org.apache.servicemix.jbi.cluster.config">
            clusterName=smx2
        </config>
        <feature>activemq</feature>
        <feature>jbi-cluster</feature>
    </feature>
</features>

This will install the activemq and jbi-cluster feature. Note that the cluster engine will not be started until a JMS ConnectionFactory is available from the OSGi registry, which can be done easily by creating an ActiveMQ broker using the following command:

smx@root:/> activemq/create-broker

The default configuration for the created broker will include a JMS ConnectionFactory definition and register it in the OSGi registry.

Using another JMS Broker

The cluster engine, though optimized for using ActiveMQ, can be used with any JMS compliant broker. In order to do so, you need to modify the above configuration to not use the ActiveMQ optimized requestor pool:

    <bean id="clusterEngine" class="org.apache.servicemix.jbi.cluster.engine.ClusterEngine">
        <property name="pool">
            <bean class="org.apache.servicemix.jbi.cluster.requestor.GenericJmsRequestorPool">
                <property name="connectionFactory" ref="connectionFactory" />
                <property name="destinationName" value="${destinationName}" />
            </bean>
        </property>
        <property name="name" value="${clusterName}" />
    </bean>

You also need to create a JMS ConnectionFactory pointing to your JMS broker and register it in OSGi, or put its definition directly in the JBI cluster engine Spring configuration file.

Configuration

When using an OSGi packaged JBI Service Assemby, you can include the clustered endpoints definitions in the spring configuration file directly.

<http:consumer-endpoint id="myHttpConsumer" service="test:myService" endpoint="myEndpoint" />

<bean class="org.apache.servicemix.jbi.cluster.engine.OsgiSimpleClusterRegistration">
  <property name="endpoint" ref="myHttpConsumer" />
</bean>

When using a JBI packaged Service Assembly, you need to create a spring application to register the endpoint as a clustered endpoint:

<bean class="org.apache.servicemix.jbi.cluster.engine.OsgiSimpleClusterRegistration">
  <property name="serviceName" value="test:myService" />
  <property name="endpointName" value="myEndpoint" />
</bean>

#top