Article

How to integrate a remote Red Hat AMQ 7 cluster on Red Hat JBoss EAP 7

December 6, 2018
Roman Martin Gil
Roman Martin Gil
Principal Middleware Architect
EAP 7 - Ready, Set, Code EAP 7 - Ready, Set, Code

It is very common in an integration landscape to have different components connected using a messaging system such as Red Hat AMQ 7 (RHAMQ 7). In this landscape, usually, there are JEE application servers, such as Red Hat JBoss Enterprise Application Platform 7 (JBoss EAP 7), to deploy and run applications connected to the messaging system.

This article describes in detail how to integrate a remote RHAMQ 7 cluster on a JBoss EAP 7 server, and it covers in detail the different configurations and components and some tips to improve your message-driven beans (MDBs) applications.

Overview

The messaging broker embedded in JBoss EAP 7 is ActiveMQ Artemis, a community project created from the union of HornetQ and Apache ActiveMQ projects, and it is the base of the RHAMQ 7. The result of this union is a high-performance messaging system for both platforms with the best features of both projects and with some smart new features.

JBoss EAP 7 features an embedded Apache ActiveMQ Artemis server as its JMS broker to provide Java EE messaging capabilities and it is configured in the messaging-activemq subsystem. This subsystem defines the operations and functions for this embedded broker.

However, it is very common to deploy RHAMQ 7 as an external clustered messaging platform to be used from different types of applications. JBoss EAP 7 connects to any messaging provider using a Java Connector Architecture (JCA) Resource Adapter. JBoss EAP 7 includes an integrated Artemis resource adapter.

The integrated Artemis resource adapter could be configured to connect to a remote installation of RHAMQ 7, which then becomes the JMS provider for your JBoss EAP 7 applications. This allows JBoss EAP 7 to be a client for the remote RHAMQ 7 server.

The Artemis resource adapter integrated with JBoss EAP 7 has the following limitations:

  • Dynamic creation of queues and topics: It does not support dynamic creation of queues and topics in the RHAMQ 7 broker. You must configure all queue and topic destinations directly on the remote RHAMQ 7 broker.
  • Creation of connection factories: RHAMQ 7 allows connection factories to be configured using both the pooled-connection-factory and the external-context; there is a difference in the way each connection factory is created. Only the pooled-connection-factory can be used to create connection factories in JBoss EAP 7. The external-context can be used only to register JMS destinations, which are already configured on the remote RHAMQ 7 broker, into the JNDI tree of the JBoss EAP 7 server so that local deployments can look them up or inject them. Only connection factories created by configuring the pooled-connection-factory element are supported for use when connecting to the remote RHAMQ 7 broker.

The communication between JBoss EAP 7 and RHAMQ 7 requires you to set up:

  • RHAMQ 7 brokers
  • JBoss EAP 7 servers

This article supposes an RHAMQ 7 HA cluster is deployed with at least three master brokers. It is not within the scope of this article to describe how to deploy a high availability (HA) RHAMQ 7 cluster; however, if you want to learn more, the Automating AMQ 7 High Availability Deployment article could help you.

RHAMQ 7 configuration

The Artemis resource adapter that is included with JBoss EAP 7.1 uses the ActiveMQ Artemis JMS Client 1.5.5. This client requires anycastPrefix and multicastPrefix prefixing on the address. It also expects the queue name to be the same as the address name. 

<acceptors>
     <acceptor name="netty-acceptor">tcp://localhost:61616?anycastPrefix=jms.queue.;multicastPrefix=jms.topic.</acceptor>
</acceptors>

JBoss EAP 7 configuration

JBoss EAP 7 includes a default configuration for the messaging-activemq subsystem with the full or full-ha configuration. The default configuration does not include how to connect to a remote server. So to set it up, use the following steps:

  • Define the remote socket bindings to connect to each RHAMQ 7 broker deployed in its cluster:
/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=messaging-remote-broker01:add(host=BROKER01,port=61616)
/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=messaging-remote-broker02:add(host=BROKER02,port=61616)
/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=messaging-remote-broker03:add(host=BROKER03,port=61616)
  • Define new remote connectors in the messaging-activemq subsystem:
/subsystem=messaging-activemq/server=default/remote-connector=messaging-remote-broker01-connector:add(socket-binding=messaging-remote-broker01)
/subsystem=messaging-activemq/server=default/remote-connector=messaging-remote-broker02-connector:add(socket-binding=messaging-remote-broker02)
/subsystem=messaging-activemq/server=default/remote-connector=messaging-remote-broker03-connector:add(socket-binding=messaging-remote-broker03)
  • Define a new pooled connection factory called activemq-rar.rar. Note that we are using a list of connectors and we activate the HA property:
/subsystem=messaging-activemq/server=default/pooled-connection-factory=activemq-rar.rar:add(entries=["java:/RemoteJmsXA", "java:jboss/RemoteJmsXA"],connectors=["messaging-remote-broker01-connector", "messaging-remote-broker02-connector", "messaging-remote-broker03-connector"],ha=true)
  • Define some extra properties, for example, user, password, and rebalance-connections between each connector (so it will avoid connecting only to one member of the cluster):
/subsystem=messaging-activemq/server=default/pooled-connection-factory=activemq-rar.rar:write-attribute(name=user,value=user)
/subsystem=messaging-activemq/server=default/pooled-connection-factory=activemq-rar.rar:write-attribute(name=password,value=s3cr3t)
/subsystem=messaging-activemq/server=default/pooled-connection-factory=activemq-rar.rar:write-attribute(name=rebalance-connections,value=true)
  • Define a new external context to declare the Queues and Topics in the RHAMQ 7 cluster. This step will define a local JNDI entry to connect to the remote resources:
/subsystem=naming/binding=java\:global\/remoteContext:add(binding-type=external-context, class=javax.naming.InitialContext, module=org.apache.activemq.artemis, environment=[java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory, queue.SampleQueue=SampleQueue, topic.SampleTopic=SampleTopic])
/subsystem=naming/binding=java\:\/queue\/SampleQueue:add(lookup=java:global/remoteContext/SampleQueue,binding-type=lookup)
/subsystem=naming/binding=java\:\/topic\/SampleTopic:add(lookup=java:global/remoteContext/SampleTopic,binding-type=lookup)
  • As an optional step, you could modify the default resource adapter defined in the EJB 3 subsystem from the default one (activemq-ra) to the newly defined one (activemq-rar.rar). With this change, all your MDB instances will be connected to the broker using it:
<mdb>
    <resource-adapter-ref resource-adapter-name="${ejb.resource-adapter-name:activemq-rar.rar}"/>
    <bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>
</mdb>
  • The new pooled connection factory has statistics disabled; do the following to activate them if you want to monitor how it is working at runtime:
/subsystem=messaging-activemq/server=default/pooled-connection-factory=activemq-rar.rar:write-attribute(name=statistics-enabled,value=true)
  • Do the following to see the statistics:
/subsystem=messaging-activemq/server=default/pooled-connection-factory=activemq-rar.rar:read-resource(include-runtime=true)

Tips to improve your MDB applications

Some literature describes the use of MDBs as an anti-pattern for consuming messages in the latest application designs; however, MDBs are often used in Java EE applications. The use of MDBs can be improved in a JBoss EAP 7 environment and—with a high-performance broker such as RHAMQ 7—you could get high levels of throughput by following some tips.

MDBs are a special kind of stateless session beans. They implement a method called onMessage that it is triggered when a JMS destination on which an MDB is listening receives a message. That is, MDBs are triggered by the receipt of messages from a JMS provider (resource adapter), unlike stateless session beans where methods are usually called by EJB clients. MDBs process messages asynchronously.

However, the number of MDBs instantiated could be defined by the following:

  • Resource adapter definition
  • Bean instance pool definition
  • Pool definition of the resource adapter
  • Resource adapter–specific properties

The combination of these features will help you to define how many instances of MDBs will be managed by JBoss EAP 7 and thus improve the throughput of your messaging system.

Resource adapter definition

In some cases, we need to define some different pooled connection factories. In such a case, we could define in the MDB which resource adapter to use by using the @org.jboss.ejb3.annotation.ResourceAdapter annotation: 

@ResourceAdapter("activemq-rar.rar")
@MessageDriven(
    name = "SampleMDB",
    mappedName = "queue/SampleQueue",
    activationConfig = {
        @ActivationConfigProperty(propertyName = "destination", propertyValue = "SampleQueue"),
        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
        @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge")
    }
)
public class SampleMDB implements MessageListener {

This annotation is provided by the Maven jboss-ejb3-ext-api artifact that can be added to your Maven project, as follows: 

<!-- EJB3 Extension -->
<dependency>
    <groupId>org.jboss.ejb3</groupId>
    <artifactId>jboss-ejb3-ext-api</artifactId>
    <version>2.2.0.Final-redhat-1</version>
    <scope>provided</scope>
</dependency>

Bean instance pool definition

JBoss EAP 7 can cache EJB instances in a bean instance pool to save initialization time. MDB instances are located in the default pool definition called mdb-strict-max-pool. If you have a large number of MDB definitions or you want to split them into different pools, you could create different bean instance pools, as follows: 

/subsystem=ejb3/strict-max-bean-instance-pool=mdb-sample-pool:add(max-pool-size=100,timeout=10,timeout-unit=MILLISECONDS)

Pool definition of the resource adapter

You can set a specific instance pool that a particular bean will use by using the @org.jboss.ejb3.annotation.Pool annotation:  

@Pool("mdb-sample-pool") 
@MessageDriven(
    name = "SampleMDB",
    mappedName = "queue/SampleQueue",
    activationConfig = {
        @ActivationConfigProperty(propertyName = "destination", propertyValue = "SampleQueue"),
        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
        @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge")
    }
)
public class SampleMDB implements MessageListener {

Resource adapter–specific properties

By default, in JBoss EAP 7, each MDB can have up to 16 sessions, where each session processes a message. You can change this value by using a resource adapter–specific property to align with the application requirements.

maxSession is the property to define a different number of sessions managed by the MDB. When increasing the size of the maxSession attribute on a MDB, it is important to make sure that the value is not greater than the value of max-pool-size in the MDB pool size. If it is, there will be idle sessions since there will not be enough MDBs to service them. It is recommended that both values be equal.

The MDB definition should be similar to this: 

@Pool("mdb-sample-pool") 
@MessageDriven(
    name = "SampleMDB",
    mappedName = "queue/SampleQueue",
    activationConfig = {
        @ActivationConfigProperty(propertyName = "destination", propertyValue = "SampleQueue"),
        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
        @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge"),
        @ActivationConfigProperty(propertyName = "maxSession", propertyValue = "100")
    }
)
public class SampleMDB implements MessageListener {

Monitoring your MDBs

To confirm the status of your MDBs, this CLI command will help you: 

/deployment=SampleMDB.jar/subsystem=ejb3/message-driven-bean=SampleMDB:read-resource(include-runtime=true)

Summary

This article provided a detailed description of JBoss EAP 7 integration with an RHAMQ 7 cluster broker and subsytem configuration, and it provided some extra tips about how to improve your MDB applications.

If you are looking for more details, please refer to the following links:

Last updated: September 3, 2019