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. If the maximum pool size is not defined, it is determined to be eight (8) times the number of CPU core processors. 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 increase the maximum pool size of client thread pool using the management CLI. The following command sets the maximum client thread pool size to 128.

/subsystem=messaging-activemq:write-attribute(name=global-client-thread-pool-max-size,value=128)

For information about how to configure the client thread pool size, see Client Thread Management. 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.

WFLYCTL0412: Required services that are not installed:" => ["jboss.naming.context.java.jboss.DefaultJMSConnectionFactory"]

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 configure the integrated Artemis resource adapter to connect to a remote installation of Red Hat AMQ 7, which then becomes the JMS provider for your JBoss EAP 7.2 applications. This allows JBoss EAP to be a client for the remote Red Hat AMQ 7 server.

If you require support for other messaging protocols, such as AMQP or STOMP, you must configure Red Hat AMQ 7 as your messaging broker. That is because JBoss EAP 7.2 is packaged with Apache ActiveMQ Artemis 1.5.x, which removed the support for these protocols. Red Hat AMQ 7 provides support for AMQP, STOMP, and other messaging protocols. This means that clients that are using AMQP or STOMP protocols can use Red Hat AMQ 7 as the messaging broker, and the Artemis resource adapter integrated in the JBoss EAP server can then be used to process messages for the deployed applications.

Limitations of the Integrated Resource Adapter

Dynamic Creation of Queues and Topics

Be aware that the Artemis resource adapter that is integrated in JBoss EAP 7.2 does not support dynamic creation of queues and topics in the Red Hat AMQ 7 broker. You must configure all queue and topic destinations directly on the remote Red Hat AMQ 7 server.

Creation of Connection Factories

Although Red Hat AMQ 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. When the external-context is used to create the connection factory, it creates simple JMS connection factory as defined in the JMS specification. The newly created connection factory is equivalent to the RemoteConnectionFactory, which is defined by default in messaging-activemq subsystem. This connection factory is independent of the other components in the application server, meaning it is not aware of, nor is it able to use, other components like the transaction manager or the security manager. For this reason, only the pooled-connection-factory can be used to create connection factories in JBoss EAP 7. The external-context can only be used to register JMS destinations, which are already configured on the remote AMQ 7 broker, into the JNDI tree of the JBoss EAP 7 server so that local deployments can look them up or inject them.

Connection factories created by configuring the external-context or the connection-factory elements cannot be used to connect to the remote AMQ 7 broker as they do not use the Artemis resource adapter. Only connection factories created by configuring the pooled-connection-factory element are supported for use when connecting to the remote AMQ7 broker.

Configure JBoss EAP to Use a Remote Red Hat AMQ Server

You can use the management CLI to configure JBoss EAP to use a remote installation of Red Hat AMQ 7 as the messaging provider by following the steps below:

JBoss EAP is now configured to use the remote installation of Red Hat AMQ 7 as the messaging provider.

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.3.0, become the external JMS provider for JBoss EAP.

See Install the ActiveMQ Resource Adapter in Integrating with JBoss Enterprise Application Platform, which is in the Red Hat JBoss A-MQ documentation suite, for details on how to deploy and configure a Red Hat JBoss A-MQ resource adapter.

About IBM MQ

IBM 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 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 MQ, see IBM MQ on the IBM products website.

Summary

IBM MQ can be configured as an external JMS provider for JBoss EAP 7.2. This section covers the steps to deploy and configure the IBM MQ resource adapter in JBoss EAP. This deployment and configuration can be accomplished by using the management CLI tool or the web-based management console.

JBoss EAP 7.2 has been tested with the following configurations.

See JBoss EAP supported configurations for the most current information about the supported configurations of IBM MQ.

Prerequisites

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

Procedure

@ActivationConfigProperty(propertyName = "destination", propertyValue = "QUEUE")

@JMSConnectionFactoryDefinition(
    name = "java:/jms/WMQConnectionFactory",
    interfaceName = "javax.jms.ConnectionFactory",
    resourceAdapter = "wmq.jmsra",
    properties = {
        "channel=<channel>",
        "hostName=<hostname_wmq_broker>",
        "transportType=<transport_type>",
        "queueManager=<queue_manager>"
    }
)

@Inject
@JMSConnectionFactory("jms/CF")
@JMSPasswordCredential(userName="myusername", password="mypassword")
@JMSSessionMode(JMSContext.DUPS_OK_ACKNOWLEDGE)
transient JMSContext context3;

WARN  [org.jboss.jca.core.connectionmanager.pool.strategy.PoolByCri] (EJB default - 7) IJ000604: Throwable while attempting to get a new connection: null: com.ibm.mq.connector.DetailedResourceException: MQJCA1011: Failed to allocate a JMS connection., error code: MQJCA1011 An internal error caused an attempt to allocate a connection to fail. See the linked exception for details of the failure.

QueueConnection qc = queueConnectionFactory.createQueueConnection("invalidUserName", "invalidPassword");

SVR-ERROR: Expected JMSException, received com.ibm.mq.connector.outbound.MQQueueProxy cannot be cast to com.ibm.mq.jms.MQDestination

ERROR [io.undertow.request] (default task-1) UT005023: Exception handling request to /jmsServlet-1.0-SNAPSHOT/: com.ibm.msg.client.jms.DetailedJMSRuntimeException: MQJCA0002: An exception occurred in the IBM MQ layer. See the linked exception for details.
A call to IBM MQ classes for Java(tm) caused an exception to be thrown.

SVR-ERROR: com.ibm.msg.client.jms.DetailedJMSException: JMSWMQ2007: Failed to send a message to destination 'MDB_NAME TOPIC_NAME'

com.ibm.mq.MQException: JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED') reason '2072' ('MQRC_SYNCPOINT_NOT_AVAILABLE')

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 8 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")

Using the @Resource annotation, Enterprise Java Beans (EJBs) can directly inject Java Message Service (JMS) resources or connection factories. You can specify the following parameters using the @Resource annotations:

To inject a resource, you must specify the Java Naming and Directory Interface (JNDI) name of the resource in one of these parameters.