Chapter 31. Resource Adapters

JBoss EAP 7 includes an integrated Artemis resource adapter, which uses the pooled-connection-factory element to configure the outbound and inbound connections of the resource adapter.

Outbound Connection

Outbound connections are defined using the pooled-connection-factory element, which is then used in Java EE deployments by EJBs and servlets to send messages to and receive messages from queues or topics. Because connections created from connection factories are created in the scope of the application server, they can use application server features like the following:

This is a major difference with a pooled-connection-factory as these features are not available with a basic connection-factory like InVmConnectionFactory or RemoteConnectionFactory. Also, be aware that with a connection factory defined using pooled-connection-factory, it is not possible to do a lookup using JNDI from an external standalone JMS client.

Inbound Connections

Inbound connections are used only by message-driven beans (MDBs) to receive message from a queue or a topic. MDBs are stateless session beans that listen on a queue or topic. They must implement the public onMessage(Message message) method, which is called when a message is sent to a queue or a topic. The Artemis resource adapter is responsible for receiving the message from the queue or the topic and passing it to the onMessage(Message message) method. For this purpose it configures the inbound connection, which defines the location of the integrated Artemis server and some additional elements.

Each MDB session bean uses a thread from the client thread pool to consume the message from the destination. The default maximum thread pool size is set to eight (8) times the number of CPU cores. For systems with many MDB sessions, such as test suites, this can potentially lead to thread exhaustion and force MDBs to wait for a free thread from the pool. You can configure the maximum client thread pool size using the activemq.artemis.client.global.thread.pool.max.size system property. To set the maximum thread pool size to 128, pass the following argument on command line when starting the server.

-Dactivemq.artemis.client.global.thread.pool.max.size=128

For more information about MDBs, see Message Driven Beans in Developing EJB Applications for JBoss EAP.

JBoss EAP includes a resource adapter to make connections to its integrated ActiveMQ Artemis messaging server. By default the pooled-connection-factory defined in the messaging-activemq subsystem uses the adapter to make the connections. However, you can use the same resource adapter to make connections to an Artemis server running inside a remote instance of JBoss EAP as well.

To connect to an Artemis server running inside a remote instance of JBoss EAP, create a new pooled-connection-factory by following the steps below.

Configuring an MDB to use a pooled-connection-factory

After the pooled-connection-factory is configured to connect to a remote Artemis server, Message-Driven Beans (MDB) wanting to read messages from the remote server must be annotated with the @ResourceAdapter annotation using the name of the pooled-connection-factory resource.

import org.jboss.ejb3.annotation.ResourceAdapter;

@ResourceAdapter("remote-artemis")
@MessageDriven(name = "MyMDB", activationConfig = { ... })
public class MyMDB implements MessageListener {
    public void onMessage(Message message) {
       ...
    }
}

If the MDB needs to send messages to the remote server, it must inject the pooled-connection-factory by looking it up using one of its JNDI entries.

@Inject
@JMSConnectionFactory("java:/jms/remoteCF")
private JMSContext context;

Configuring the JMS destination

An MDB must also specify the destination from which it will consume messages. The standard way to do this is to define a destinationLookup activation config property that corresponds to a JNDI lookup on the local server.

@ResourceAdapter("remote-artemis")
@MessageDriven(name = "MyMDB", activationConfig = {
    @ActivationConfigProperty(propertyName = "destinationLookup", propertyValue = "myQueue"),
    ...
})
public class MyMDB implements MessageListener {
    ...
}

If the local server does not include a JNDI binding for the remote Artemis server, specify the name of the destination, as configured in the remote Artemis server, using the destination activation config property and set the useJNDI activation config property to false. This instructs the Artemis resource adapter to automatically create the JMS destination without requiring a JNDI lookup.

@ResourceAdapter("remote-artemis")
@MessageDriven(name = "MyMDB", activationConfig = {
    @ActivationConfigProperty(propertyName = "useJNDI", propertyValue = "false"),
    @ActivationConfigProperty(propertyName = "destination", propertyValue = "myQueue"),
    ...
})
public class MyMDB implements MessageListener {
    ...
}

In the above example, the activation config properties configure the MDB to consume messages from the JMS Queue named myQueue hosted on the remote Artemis server. In most cases, the MDB does not need to lookup other destinations to process the consumed messages, and it can use the JMSReplyTo destination if it is defined on the message.

If the MDB needs any other JMS destinations defined on the remote server, it must use client-side JNDI. See Connecting to a Server for more information.

You can deploy the resource adapter provided by the Red Hat JBoss A-MQ product and have, for example, Red Hat JBoss A-MQ 6.2.0, become the external JMS provider for JBoss EAP.

See the Red Hat JBoss A-MQ documentation for details on how to deploy and configure an A-MQ resource adapter.

About IBM WebSphere® MQ

IBM WebSphere® MQ is the Messaging Oriented Middleware (MOM) product offering from IBM that allows applications on distributed systems to communicate with each other. This is accomplished through the use of messages and message queues. IBM WebSphere® MQ is responsible for delivering messages to the message queues and for transferring data to other queue managers using message channels. For more information about IBM WebSphere® MQ, see IBM MQ.

Summary

This section covers the steps to deploy and configure the IBM WebSphere® MQ resource adapter in JBoss EAP. JBoss EAP 7 is certified with IBM WebSphere® MQ 7.5.0.4. This deployment and configuration can be accomplished by manually editing configuration files, using the management CLI tool, or using the web-based management console.

Prerequisites

Before you get started, you must verify the version of the IBM WebSphere® MQ resource adapter and understand some of its configuration properties.

Procedure to Deploy the IBM WebSphere® Resource Adapter

JBoss EAP can be configured to work with third-party JMS providers, however not all JMS providers produce a JMS JCA resource adapter for integration with Java application platforms. This procedure covers the steps required to configure the generic JMS resource adapter included in JBoss EAP to connect to a JMS provider. In this procedure, Tibco EMS 6.3 is used as an example JMS provider. Other JMS providers may require different configuration.

Before you can configure a generic resource adapter, you will need to do the following:

In the example XML used in this procedure, these parameters are written as PROVIDER_FACTORY_INITIAL, PROVIDER_URL, and PROVIDER_CONNECTION_FACTORY respectively. Replace these placeholders with the JMS provider values for your environment.

@MessageDriven(name = "HelloWorldQueueMDB", activationConfig = {
  // The generic JMS resource adapter requires the JNDI bindings
  // for the actual remote connection factory and destination
  @ActivationConfigProperty(propertyName = "connectionFactory", propertyValue = "java:global/remoteJMS/XAQCF"),
  @ActivationConfigProperty(propertyName = "destination", propertyValue = "java:global/remoteJMS/Queue1"),
  @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
  @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge") })
  public class HelloWorldQueueMDB implements MessageListener {
  public void onMessage(Message message) {
  // called every time a message is received from the _Queue1_ queue on the JMS provider.
  }
}

@Resource(lookup = "java:/jms/XAQCF")
private ConnectionFactory cf;

@Resource(lookup = "java:global/remoteJMS")
private Context context;
...
Queue queue = (Queue) context.lookup("Queue1")