Configuring Messaging

Messaging systems allow you to loosely couple heterogeneous systems together with added reliability. Unlike systems based on a Remote Procedure Call (RPC) pattern, messaging systems primarily use an asynchronous message passing pattern with no tight relationship between requests and responses. Most messaging systems are flexible enough to also support a request-response mode if needed, but this is not a primary feature of messaging systems.

Messaging systems decouple a message’s sender of messages from it consumer(s). In fact, the senders and consumers of messages are completely independent and know nothing of each other, which allows you to create flexible, loosely coupled systems. Large enterprises often use a messaging system to implement a message bus which loosely couples heterogeneous systems together. Message buses can form the core of an Enterprise Service Bus (ESB). Using a message bus to decouple disparate systems allows the system to grow and adapt more easily. It also allows more flexibility to add new systems or retire old ones since they don’t have brittle dependencies on each other.

Messaging systems can also incorporate concepts such as delivery guarantees to ensure reliable messaging, transactions to aggregate the sending or consuming of multiple message as a single unit of work, and durability to allow messages to survive server failure or restart.

There are two kinds of messaging styles that most messaging systems support: the point-to-point pattern and the publish-subscribe pattern.

The Java Messaging Service 2.0 (JMS) is defined in JSR 343 and is a part of the Java EE 7 specification. JMS is a Java API that provides both point-to-point and publish-subscriber messaging styles. JMS also incorporates the use of transactions. JMS does not define a standard wire format so while vendors of JMS providers may all use the standard APIs, they may use different internal wire protocols to communicate between their clients and servers.

JMS destinations, along with JMS connection factories, are JMS administrative objects. Destinations are used by JMS clients for both producing and consuming messages. The destination allows the JMS client to specify the target when it produces messages and the source of messages when consuming messages. When using a publish-subscribe pattern, destinations are referred to as topics. When using a point-to-point pattern, destinations are referred to as queues.

Applications may use many different JMS destinations which are configured on the server side and usually accessed via JNDI.

Apache ActiveMQ Artemis is an open source project for an asynchronous messaging system. It is high performance, embeddable, clustered and supports multiple protocols. JBoss EAP 7 uses Apache ActiveMQ Artemis as its JMS broker and is configured using the messaging-activemq subsystem. This fully replaces the HornetQ broker but retains protocol compatibility with JBoss EAP 6.

The core ActiveMQ Artemis is JMS-agnostic and provides a non-JMS API, which is referred to as the core API. ActiveMQ Artemis also provides a JMS client API which uses a facade layer to implement the JMS semantics on top of the core API. Essentially, JMS interactions are translated into core API operations on the client side using the JMS client API. From there, all operations are sent using the core client API and Apache ActiveMQ Artemis wire format. The server itself only uses the core API. For more details on the core API and its concepts, refer to the ActiveMQ Artemis documentation.

Let’s quickly discuss how JMS destinations are mapped to Apache ActiveMQ Artemis addresses.

Apache ActiveMQ Artemis core is JMS-agnostic. It does not have any concept of a JMS topic. A JMS topic is implemented in core as an address (the topic name) with zero or more queues bound to it. Each queue bound to that address represents a topic subscription. Likewise, a JMS queue is implemented as an address (the JMS queue name) with one single queue bound to it which represents the JMS queue.

By convention, all JMS queues map to core queues where the core queue name has the string "jms.queue." prepended to it. E.g. the JMS queue with the name "orders.europe" would map to the core queue with the name "jms.queue.orders.europe". The address at which the core queue is bound is also given by the core queue name.

For JMS topics the address at which the queues that represent the subscriptions are bound is given by prepending the string "jms.topic." to the name of the JMS topic. E.g. the JMS topic with name "news.europe" would map to the core address "jms.topic.news.europe"

In other words if you send a JMS message to a JMS queue with name "orders.europe" it will get routed on the server to any core queues bound to the address "jms.queue.orders.europe". If you send a JMS message to a JMS topic with name "news.europe" it will get routed on the server to any core queues bound to the address "jms.topic.news.europe".

If you want to configure settings for a JMS Queue with the name "orders.europe", you need to configure the corresponding core queue "jms.queue.orders.europe":

<!-- expired messages in JMS Queue "orders.europe" will be sent to the JMS Queue "expiry.europe" -->
<address-setting match="jms.queue.orders.europe">
   <expiry-address>jms.queue.expiry.europe</expiry-address>
   ...
</address-setting>

The helloworld-mdb quickstart uses a simple message-driven bean to demonstrate basic Java EE 7 messaging features. Having the quickstart up and running as you review the basic configuration is an excellent way to introduce yourself to the features included with the JBoss EAP messaging server.

Build and Deploy the helloworld-mdb Quickstart

See the instructions in the README.md file provided with the quickstart for instructions on building and deploying the helloworld-mdb quickstart. You will need to start the JBoss EAP server specifying the full configuration, which contains the messaging-activemq subsystem. See the README.md file or the JBoss EAP Configuration Guide for details on starting JBoss EAP with a different configuration file.

Default configuration for the messaging-activemq subsystem is included when starting the JBoss EAP server with the full or full-ha configuration. The full-ha option includes advanced configuration for features like clustering and high availability.

Although not necessary, it is recommended that you use the helloworld-mdb quickstart as a working example to have running alongside this overview of the configuration.

For information on all settings available in the messaging-activemq subsystem, see the schema definitions located in the EAP_HOME/docs/schema/ directory, or run the read-resource-description operation on the subsystem from the management CLI, as shown below.

/subsystem=messaging-activemq:read-resource-description(recursive=true)

The following extension in the server configuration file tells JBoss EAP to include the messaging-activemq subsystem as part of its runtime.

<extensions>
  ...
  <extension module="org.wildfly.extension.messaging-activemq"/>
  ...
</extensions>

The configuration for the messaging-activemq subsystem is contained within the <subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0"> element.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
    <server name="default">
        <cluster password="${jboss.messaging.cluster.password:CHANGE ME!!}"/>
        <security-setting name="#">
            <role name="guest" send="true" consume="true" create-non-durable-queue="true" delete-non-durable-queue="true"/>
        </security-setting>
        <address-setting name="#" dead-letter-address="jms.queue.DLQ" expiry-address="jms.queue.ExpiryQueue" max-size-bytes="10485760" page-size-bytes="2097152" message-counter-history-day-limit="10" redistribution-delay="1000"/>
        <http-connector name="http-connector" socket-binding="http" endpoint="http-acceptor"/>
        <http-connector name="http-connector-throughput" socket-binding="http" endpoint="http-acceptor-throughput">
            <param name="batch-delay" value="50"/>
        </http-connector>
        <in-vm-connector name="in-vm" server-id="0"/>
        <http-acceptor name="http-acceptor" http-listener="default"/>
        <http-acceptor name="http-acceptor-throughput" http-listener="default">
            <param name="batch-delay" value="50"/>
            <param name="direct-deliver" value="false"/>
        </http-acceptor>
        <in-vm-acceptor name="in-vm" server-id="0"/>
        <broadcast-group name="bg-group1" connectors="http-connector" jgroups-channel="activemq-cluster"/>
        <discovery-group name="dg-group1" jgroups-channel="activemq-cluster"/>
        <cluster-connection name="my-cluster" address="jms" connector-name="http-connector" discovery-group="dg-group1"/>
        <jms-queue name="ExpiryQueue" entries="java:/jms/queue/ExpiryQueue"/>
        <jms-queue name="DLQ" entries="java:/jms/queue/DLQ"/>
        <connection-factory name="InVmConnectionFactory" connectors="in-vm" entries="java:/ConnectionFactory"/>
        <connection-factory name="RemoteConnectionFactory" ha="true" block-on-acknowledge="true" reconnect-attempts="-1" connectors="http-connector" entries="java:jboss/exported/jms/RemoteConnectionFactory"/>
        <pooled-connection-factory name="activemq-ra" transaction="xa" connectors="in-vm" entries="java:/JmsXA java:jboss/DefaultJMSConnectionFactory"/>
    </server>
</subsystem>

Connection Factories

Messaging clients use a JMS ConnectionFactory object to make connections to the server. The default JBoss EAP configuration defines several connection factories. Note that there is a <connection-factory> for in-vm, http, and pooled connections.

  <connection-factory name="InVmConnectionFactory" connectors="in-vm" entries="java:/ConnectionFactory"/>
  <connection-factory name="RemoteConnectionFactory" ha="true" block-on-acknowledge="true" reconnect-attempts="-1" connectors="http-connector" entries="java:jboss/exported/jms/RemoteConnectionFactory"/>
  <pooled-connection-factory name="activemq-ra" transaction="xa" connectors="in-vm" entries="java:/JmsXA java:jboss/DefaultJMSConnectionFactory"/>

See the Configuring Connection Factories section for more details.

Connectors and Acceptors

Each JMS connection factory uses connectors to enable JMS-enabled communication from a client producer or consumer to a messaging server. The connector object defines the transport and parameters used to connect to the messaging server. Its counterpart is the acceptor object, which identifies the type of connections accepted by the messaging server.

The default JBoss EAP configuration defines several connectors and acceptors.

<http-connector name="http-connector" socket-binding="http" endpoint="http-acceptor"/>
<http-connector name="http-connector-throughput" socket-binding="http" endpoint="http-acceptor-throughput">
  <param name="batch-delay" value="50"/>
</http-connector>
<in-vm-connector name="in-vm" server-id="0"/>

<http-acceptor name="http-acceptor" http-listener="default"/>
<http-acceptor name="http-acceptor-throughput" http-listener="default">
  <param name="batch-delay" value="50"/>
  <param name="direct-deliver" value="false"/>
</http-acceptor>

See the Acceptors and Connectors section for more details.

Socket Binding Groups

The socket-binding attribute for the default connectors reference a socket binding named http. The http connector is used because JBoss EAP can multiplex inbound requests over standard web ports.

You can find this socket-binding as part of the <socket-binding-group> section elsewhere in the configuration file. Note how the configuration for the http and https socket bindings appear within the <socket-binding-groups> element:

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
   ...
  <socket-binding name="http" port="${jboss.http.port:8080}"/>
  <socket-binding name="https" port="${jboss.https.port:8443}"/>
   ...
</socket-binding-group>

For information on socket bindings, see Configuring Socket Bindings in the JBoss EAP Configuration Guide.

Messaging Security

The messaging-activemq subsystem includes a single security-setting element when JBoss EAP is first installed:

<security-setting name="#">
  <role name="guest" delete-non-durable-queue="true" create-non-durable-queue="true" consume="true" send="true"/>
</security-setting>

This declares that any user with the role guest can access any address on the server, as noted by the wildcard #. See Configuring Address Settings for more information on the wildcard syntax .

For more information on securing destinations and remote connections see Configuring Messaging Security.

Messaging Destinations

The full and full-ha configurations include two helpful queues that JBoss EAP can use to hold messages that have expired or that cannot be routed to their proper destination.

<jms-queue name="ExpiryQueue" entries="java:/jms/queue/ExpiryQueue"/>
<jms-queue name="DLQ" entries="java:/jms/queue/DLQ"/>

You can add your own messaging destinations in JBoss EAP using one of the following methods.

See Configuring Messaging Destinations for more detailed information.

To add a JMS queue, use the jms-queue command from the management CLI:

jms-queue add --queue-address=myQueue --entries=[queue/myQueue jms/queue/myQueue java:jboss/exported/jms/queue/myQueue]

Note how the entries attribute is a list containing multiple JNDI names separated by a single space. Also note the use of square brackets, [], to enclose the list of JNDI names. The queue-address provides routing configuration, and entries provides a list of JNDI names that clients can use to look up the queue.

Reading a Queue’s attributes

You can read a queue’s configuration using the jms-queue command in the management CLI.

jms-queue read-resource --queue-address=myQueue

Alternatively, you can read a queue’s configuration by accessing the messaging-activemq subsystem using the management CLI:

/subsystem=messaging-activemq/server=default/jms-queue=myQueue:read-resource()
{
    "outcome" => "success",
    "result" => {
        "durable" => true,
        "entries" => ["queue/myQueue jms/queue/myQueue java:jboss/exported/jms/queue/myQueue"],
        "legacy-entries" => undefined,
        "selector" => undefined
    }
}

Attributes of a jms-queue

The management CLI displays all the attributes of the jms-queue configuration element when given the following command:

/subsystem=messaging-activemq/server=default/jms-queue=*:read-resource-description()

The table below provides all the attributes of a jms-queue:

Adding or reading a Topic is much like adding a Queue:

jms-topic add --topic-address=myTopic --entries=[topic/myTopic jms/topic/myTopic java:jboss/exported/jms/topic/myTopic]

Reading a Topic’s attributes

Reading Topic attributes also has syntax similar to that used for a Queue:

jms-topic read-resource --topic-address=myTopic

entries
  topic/myTopic jms/topic/myTopic java:jboss/exported/jms/topic/myTopic
legacy-entries=n/a

/subsystem=messaging-activemq/server=default/jms-topic=myTopic:read-resource
{
    "outcome" => "success",
    "result" => {
        "entries" => ["topic/myTopic jms/topic/myTopic java:jboss/exported/jms/topic/myTopic"],
        "legacy-entries" => undefined
    }
}

Attributes of a jms-topic

The management CLI displays all the attributes of the jms-topic configuration element when given the following command:

/subsystem=messaging-activemq/server=default/jms-topic=*:read-resource-description()

The table below lists the attributes of a jms-topic:

A Queue or Topic must be bound to the java:jboss/exported namespace for a remote client to be able to look it up. The client must use the text after java:jboss/exported/ when doing the lookup. For example, a queue named testQueue has for its entries the list jms/queue/test java:jboss/exported/jms/queue/test. A remote client wanting to send messages to testQueue would look up the queue using the string jms/queue/test. A local client on the other hand could look it up using java:jboss/exported/jms/queue/test, java:jms/queue/test, or more simply jms/queue/test.

Management CLI Help

You can find more information about the jms-queue and jms-topic commands by using the --help --commands flags:

jms-queue --help --commands

jms-topic --help --commands

Wildcards can be used to match similar addresses with a single statement, much like how many systems use the asterisk character, *, to match multiple files or strings with a single query. The following table lists the special characters that can be used to define an <address-setting>.

The examples in the table below illustrate how wildcards are used to match a set of addresses.

Out of the box, JBoss EAP includes a single address-setting element as part of the configuration for the messaging-activemq subsystem:

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
      ...
      <address-setting
        name="#"
        dead-letter-address="jms.queue.DLQ"
        expiry-address="jms.queue.ExpiryQueue"
        max-size-bytes="10485760"
        page-size-bytes="2097152"
        message-counter-history-day-limit="10" />
      ...
  </server>
</subsystem>

Configuring Address Settings Using the Management CLI

Configuring address settings is done by using either the management CLI or the management console, but the management CLI exposes more of the configuration attributes for editing. See Address Setting Attributes in the appendix of this guide for the full list of attributes.

Add a new address-setting

Use the add operation to create a new address setting if required. You can run this command from the root of the management CLI session, which in the following examples creates a new pattern named . You can include configuration attributes for the address-setting. Below, a new address-setting matching news.europe.# is created with its dead-letter-address attribute set to the queue DLQ.news, which was created beforehand. Examples for both a standalone server and a managed server domain using the full profile are shown respectively.

/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:add(dead-letter-address=DLQ.news)

/profile=full/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:add(dead-letter-address=DLQ.news)

Edit an address-setting attribute

Use the write-attribute operation to write a new value to an attribute. You can use tab completion to help complete the command string as you type, as well as to expose the available attributes. The following example updates the max-delivery-attempts value to 10.

/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:write-attribute(name=max-delivery-attempts,value=10)

/profile=full/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:write-attribute(name=max-delivery-attempts,value=10)

Read address-setting Attributes

Confirm the values are changed by running the read-resource operation with the include-runtime=true parameter to expose all current values active in the server model.

/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:read-resource(include-runtime=true)

/profile=full/subsystem=messaging-activemq/server=default/address-setting=news.europe.#/:read-resource(include-runtime=true)

Configuring Address Settings Using the Management Console

You can use the management console to create and review address settings by following these steps:

Remember that when adding a new pattern, for example news.europe.#, the Pattern field refers to the name attribute of the address-setting element. You enter this value when using the management CLI to read or write attributes.

You can edit only the dead-letter-address, expiry-address, redelivery-delay, and max-delivery-attempts attributes while using the management console. Other attributes must be configured using the management CLI.

Last-value queues are special queues which discard any messages when a newer message with the same value for a well-defined last-value property is put in the queue. In other words, a last-value queue only retains the last value. A typical application of a last-value queue might involve stock prices, where you are interested only in the latest price of a particular stock.

Configuring Last-value Queues

Last-value queues are defined within the address-setting configuration element:

<address-setting name="jms.queue.lastValueQueue" last-value-queue="true" />

Use the management CLI to read the value of last-value-queue for a given address-setting:

/subsystem=messaging-activemq/server=default/address-setting=news.europe.#:read-attribute(name=last-value-queue)
{
    "outcome" => "success",
    "result" => false
}

The accepted values for last-value-queue are true or false. Use the management CLI to set either value, like so:

/subsystem=messaging-activemq/server=default/address-setting=news.europe.#:write-attribute(name=last-value-queue,value=true)

/subsystem=messaging-activemq/server=default/address-setting=news.asia.#:write-attribute(name=last-value-queue,value=false)

Using the Last-value Property

The property name used to identify the last value is _AMQ_LVQ_NAME (or the constant Message.HDR_LAST_VALUE_NAME from the Core API). Let the following Java code illustrate how to use the last-value property.

TextMessage message = session.createTextMessage("My 1st message with the last-value property set");
message.setStringProperty("_AMQ_LVQ_NAME", "MY_MESSAGE");
producer.send(message);

message = session.createTextMessage("My 2nd message with the last-value property set");
message.setStringProperty("_AMQ_LVQ_NAME", "MY_MESSAGE");
producer.send(message);

TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
System.out.format("Received message: %s\n", messageReceived.getText());

In the above example the client’s output would be "My 2nd message with the last-value property set" since both messages set _AMQ_LVQ_NAME to "MY_MESSAGE", and the second message was received in the queue after the first.

JBoss EAP secures the messaging-activemq subsystem with the help of security realms and domains. See the JBoss EAP Security Architecture guide for more information on security realms and security domains. The messaging-activemq subsystem is pre-configured to use the security realm named ApplicationRealm and the security domain named other.

The ApplicationRealm is defined near the top of the configuration file.

<management>
  <security-realms>
      ...
       <security-realm name="ApplicationRealm">
          <authentication>
              <local default-user="$local" allowed-users="*" skip-group-loading="true"/>
              <properties
                path="application-users.properties"
                relative-to="jboss.server.config.dir" />
          </authentication>
          <authorization>
              <properties
                path="application-roles.properties"
                relative-to="jboss.server.config.dir" />
          </authorization>
       </security-realm>
  </security-realms>
  ...
</management>

As its name implies, ApplicationRealm is the default security realm for all application-focused subsystems in JBoss EAP such as the messaging-activemq, undertow, and ejb3 subsystems. ApplicationRealm uses the local filesystem to store usernames and hashed passwords. For convenience JBoss EAP includes a script that you can use to add users to the ApplicationRealm. See Default User Configuration in the JBoss EAP How To Configure Server Security guide for details.

The other security domain is the default security domain for the application-related subsystems like messaging-activemq. It is not explicitly declared in the configuration; however, you can confirm which security domain is used by the messaging-activemq subsystem with the following management CLI command:

/subsystem=messaging-activemq/server=default:read-attribute(name=security-domain)
{
    "outcome" => "success",
    "result" => "other"
}

You can also update which security domain is used:

/subsystem=messaging-activemq/server=default:write-attribute(name=security-domain, value=mySecurityDomain)

The JBoss EAP How To Configure Server Security guide has more information on how to create new security realms and domains. For now, it is worth noting how the other domain appears in the configuration:

<subsystem xmlns="urn:jboss:domain:security:1.2">
     <security-domains>
         <security-domain name="other" cache-type="default">
             <authentication>
                 <login-module code="Remoting" flag="optional">
                     <module-option name="password-stacking" value="useFirstPass"/>
                 </login-module>
                 <login-module code="RealmDirect" flag="required">
                     <module-option name="password-stacking" value="useFirstPass"/>
                 </login-module>
             </authentication>
         </security-domain>
         ...
     <security-domains>
 </subsystem>

The 'other' domain uses two login-modules as its means of authentication. The first module, Remoting, authenticates remote EJB invocations, while the RealmDirect module uses the information store defined in a given realm to authenticate users. In this case the default realm ApplicationRealm is used, since no realm is declared. Each module has its password-stacking option set to useFirstPass, which tells the login-module to store the principal name and password of the authenticated user. See the JBoss EAP Login Module Reference for more details on the login modules and their options.

Role-based access is configured at the address level, see Role Based Security for Addresses.

/subsystem=messaging-activemq/server=default/remote-acceptor=mySslAcceptor:add(socket-binding=netty,params={ssl-enabled=true, key-store-path=path/to/server.jks, key-store-password=${VAULT::server-key::key-store-password::sharedKey}})

/subsystem=messaging-activemq/server=default/remote-connector=mySslConnector:add(socket-binding=netty,params={ssl-enabled=true})

/subsystem=messaging-activemq/server=default/remote-connector=myOtherSslConnector:map-put(name=params,key=ssl-enabled,value=true)

In addition to securing remote connections into the messaging server, you can also configure security around specific destinations. This is done by adding a security constraint using the security-setting configuration element. JBoss EAP messaging comes with a security-setting configured by default, as shown in the output from the following management CLI command:

/subsystem=messaging-activemq/server=default:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        ....
        "security-setting" => {"#" => {"role" => {"guest" => {
            "consume" => true,
            "create-durable-queue" => false,
            "create-non-durable-queue" => true,
            "delete-durable-queue" => false,
            "delete-non-durable-queue" => true,
            "manage" => false,
            "send" => true
        }}}}
    }
}

The security-setting option makes use of wildcards in the name field to handle which destinations to apply the security constraint. The value of a single # will match any address. For more information on using wildcards in security constraints, see Role Based Security for Addresses.

/subsystem=messaging-activemq/server=default/security-setting=news.europe.#:add()
{"outcome" => "success"}

/subsystem=messaging-activemq/server=default/security-setting=news.europe.#/role=dev:add(consume=true,delete-non-durable-queue=true,create-non-durable-queue=true,send=true)
{"outcome" => "success"}

/subsystem=messaging-activemq/server=default/security-setting=news.europe.#/role=admin:add(manage=true,create-durable-queue=true,delete-durable-queue=true)
{"outcome" => "success"}

/subsystem=messaging-activemq/server=default:read-children-resources(child-type=security-setting,recursive=true)
{
    "outcome" => "success",
    "result" => {
        "#" => {"role" => {"guest" => {
            "consume" => true,
            "create-durable-queue" => false,
            "create-non-durable-queue" => true,
            "delete-durable-queue" => false,
            "delete-non-durable-queue" => true,
            "manage" => false,
            "send" => true
        }}},
        "news.europe.#" => {"role" => {
            "dev" => {
                "consume" => true,
                "create-durable-queue" => false,
                "create-non-durable-queue" => true,
                "delete-durable-queue" => false,
                "delete-non-durable-queue" => true,
                "manage" => false,
                "send" => true
            },
            "admin" => {
                "consume" => false,
                "create-durable-queue" => true,
                "create-non-durable-queue" => false,
                "delete-durable-queue" => true,
                "delete-non-durable-queue" => false,
                "manage" => true,
                "send" => false
            }
        }}
    }

There are three main types of acceptor and connector defined in the configuration of JBoss EAP.

in-vm: In-vm is short for Intra Virtual Machine. Use this connector type when both the client and the server are running in the same JVM eg., Message Driven Beans (MDBs) running in the same instance of JBoss EAP.

http: Used when client and server are running in different JVMs. Uses the undertow subsystem’s default port of 8080 and is thus able to multiplex messaging communications over HTTP. Red Hat recommends using the http connector when the client and server are running in different JVMs due to considerations such as port management, especially in a cloud environment.

remote: Remote transports are Netty-based components used for native TCP communication when the client and server are running in different JVMs. An alternative to http when it cannot be used.

A client must use a connector that is compatible with one of the server’s acceptors. For example, only an in-vm-connector can connect to an in-vm-acceptor, and only a http-connector can connect to an http-acceptor, and so on.

You can have the management CLI list the attributes for a given acceptor or connector type using the read-children-attributes operation. For example, to see the attributes of all the http-connectors for the default messaging server you would enter:

/subsystem=messaging-activemq/server=default:read-children-resources(child-type=http-connector,include-runtime=true)

The attributes of all the http-acceptors are read using a similar command:

/subsystem=messaging-activemq/server=default:read-children-resources(child-type=http-acceptor,include-runtime=true)

The other acceptor and connector types follow the same syntax. Just provide child-type with the acceptor or connector type, for example, remote-connector or in-vm-acceptor.

An acceptor defines which types of connection are accepted by the JBoss EAP integrated messaging server. You can define any number of acceptors per server. The sample configuration below is modified from the default full-ha configuration profile and provides an example of each acceptor type.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <http-acceptor name="http-acceptor" http-listener="default"/>
    <remote-acceptor name="legacy-messaging-acceptor" socket-binding="legacy-messaging"/>
    <in-vm-acceptor name="in-vm" server-id="0"/>
    ...
  </server>
</subsystem>

In the above configuration, the http-acceptor is using Undertow’s default http-listener which listens on JBoss EAP’s default http port, 8080. The http-listener is defined in the undertow subsystem:

<subsystem xmlns="urn:jboss:domain:undertow:3.0">
  ...
  <server name="default-server">
    <http-listener name="default" redirect-socket="https" socket-binding="http"/>
    ...
  </server>
  ...
</subsystem>

Also note how the remote-acceptor above uses the socket-binding named legacy-messaging, which is defined later in the configuration as part of the server’s default socking-binding-group.

<server xmlns="urn:jboss:domain:4.1">
  ...
  <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
      ...
      <socket-binding name="legacy-messaging" port="5445"/>
      ...
  </socket-binding-group>
</server>

In this example, the legacy-messaging socket-binding binds JBoss EAP to port 5445, and the remote-acceptor above claims the port on behalf of the messaging-activemq subsystem for use by legacy clients.

Lastly, the in-vm-acceptor uses a unique value for the server-id attribute so that this server instance can be distinguished from other servers that might be running in the same JVM.

A connector defines how to connect to an integrated JBoss EAP messaging server, and is used by a client to make connections.

You might wonder why connectors are defined on the server when they are actually used by the client. The reasons for this include:

You can define any number of connectors per server. The sample configuration below is based on the full-ha configuration profile and includes connectors of each type.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <http-connector name="http-connector" endpoint="http-acceptor" socket-binding="http"/>
    <remote-connector name="legacy-remoting-connector" socket-binding="legacy-remoting"/>
    <in-vm-connector name="in-vm" server-id="0"/>
    ...
  </server>
</subsystem>

Like the http-acceptor from the full-ha profile, the http-connector uses the default http-listener defined by the undertow subsystem. The endpoint attribute declares which http-acceptor to connect to. In this case, the connector will connect to the default http-acceptor.

Also, note that the remote-connector references the same socket-binding as its remote-acceptor counterpart. Lastly, the in-vm-connector uses the same value for server-id as the in-vm-acceptor since they both run inside the same server instance.

There are a number of configuration options for connectors and acceptors. They appear in the configuration as child <param> elements. Each <param> element includes a name and value attribute pair that is understood and used by the default Netty-based factory class responsible for instantiating a connector or acceptor.

In the management CLI, each remote connector or acceptor element includes an internal map of the parameter name and value pairs. For example, to add a new param to a remote-connector named myRemote use the following command:

/subsystem=messaging-activemq/server=default/remote-connector=myRemote:map-put(name=params,key=foo,value=bar)

Retrieve parameter values using a similar syntax.

/subsystem=messaging-activemq/server=default/remote-connector=myRemote:map-get(name=params,key=foo)
{
    "outcome" => "success",
    "result" => "bar"
}

You can also include parameters when you create an acceptor or connector, as in the example below.

/subsystem=messaging-activemq/server=default/remote-connector=myRemote:add(socket-binding=mysocket,params={foo=bar,foo2=bar2})

If you want to connect a client to a server, you have to have a proper connector. There are two ways to do that. You could use a ConnectionFactory which is configured on the server and can be obtained via JNDI lookup. Alternatively, you could use the ActiveMQ Artemis core API and configure the whole ConnectionFactory on the client side.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
<server name="default">
[...]
<http-connector name="http-connector" socket-binding="http" endpoint="http-acceptor" />
<http-connector name="http-connector-throughput" socket-binding="http" endpoint="http-acceptor-throughput">
  <param name="batch-delay" value="50"/>
</http-connector>
<in-vm-connector name="in-vm" server-id="0"/>
[...]
<connection-factory name="InVmConnectionFactory" connectors="in-vm" entries="java:/ConnectionFactory" />
<pooled-connection-factory name="activemq-ra" transaction="xa" connectors="in-vm" entries="java:/JmsXA java:jboss/DefaultJMSConnectionFactory"/>
[...]
</server>
</subsystem>

<connection-factory
  name="InVmConnectionFactory"
  entries="java:/ConnectionFactory"
  connectors="in-vm" />

InitialContext ctx = new InitialContext();
ConnectionFactory cf = (ConnectionFactory)ctx.lookup("ConnectionFactory");
Connection connection = cf.createConnection();

<connection-factory
  name="RemoteConnectionFactory"
  scheduled-thread-pool-max-size="10"
  entries="java:jboss/exported/jms/RemoteConnectionFactory"
  connectors="http-connector"/>

final Properties env = new Properties();
env.put(Context.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
env.put(Context.PROVIDER_URL, "http-remoting://remotehost:8080");
InitialContext remotingCtx = new InitialContext(env);
ConnectionFactory cf = (ConnectionFactory) remotingCtx.lookup("jms/RemoteConnectionFactory");

<dependencies>
  <dependency>
    <groupId>org.wildfly</groupId>
    <artifactId>wildfly-jms-client-bom</artifactId>
    <type>pom</type>
  </dependency>
</dependencies>

ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(InVMConnectorFactory.class.getName()));

ClientSessionFactory factory =  locator.createClientSessionFactory();

ClientSession session = factory.createSession();

ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(
  new TransportConfiguration( InVMConnectorFactory.class.getName()));

// In this simple example, we just use one session for both
// producing and consuming
ClientSessionFactory factory =  locator.createClientSessionFactory();
ClientSession session = factory.createSession();

// A producer is associated with an address ...
ClientProducer producer = session.createProducer("example");
ClientMessage message = session.createMessage(true);
message.getBodyBuffer().writeString("Hello");

// We need a queue attached to the address ...
session.createQueue("example", "example", true);

// And a consumer attached to the queue ...
ClientConsumer consumer = session.createConsumer("example");

// Once we have a queue, we can send the message ...
producer.send(message);

// We need to start the session before we can -receive- messages ...
session.start();
ClientMessage msgReceived = consumer.receive();

System.out.println("message = " + msgReceived.getBodyBuffer().readString());

session.close();

JBoss EAP messaging handles its own persistence. It ships with a high-performance journal, which is optimized for messaging.

The JBoss EAP messaging journal has a configurable file size and is append only, which improves performance by enabling single write operations. It consists of a set of files on disk, which are initially pre-created to a fixed size and filled with padding. As server operations (add message, delete message, update message, etc.) are performed, records of the operations are appended to the journal until the journal file is full, at which point the next journal file is used.

A sophisticated garbage collection algorithm determines whether journal files can be reclaimed and re-used when all of their data has been deleted. A compaction algorithm removes dead space from journal files and compresses the data.

The journal also fully supports both local and XA transactions.

The majority of the journal is written in Java, but interaction with the file system has been abstracted to allow different pluggable implementations. The two implementations shipped with JBoss EAP messaging are:

The standard JBoss EAP messaging core server uses the following journal instances:

For large messages, JBoss EAP messaging persists them outside the message journal. This is discussed in the section on Large Messages.

JBoss EAP messaging can also be configured to page messages to disk in low memory situations. This is discussed in the Paging section.

If no persistence is required at all, JBoss EAP messaging can also be configured not to persist any data at all to storage as discussed in the Configuring JBoss EAP Messaging for Zero Persistence section.

Because the bindings journal shares its configuration with the JMS journal, you can read the current configuration for both by using the single management CLI command below. The output is also included to highlight default configuration.

/subsystem=messaging-activemq/server=default/path=bindings-directory:read-resource

{
    "outcome" => "success",
    "result" => {
        "path" => "activemq/bindings",
        "relative-to" => "jboss.server.data.dir"
    }
}

Note that by default the path to the journal is activemq/bindings. You can change the location for path by using the following management CLI command.

/subsystem=messaging-activemq/server=default/path=bindings-directory:write-attribute(name=path,value=<PATH_LOCATION>)

Also note the relative-to attribute in the output above. When relative-to is used, the value of the path attribute is treated as relative to the file path specified by relative-to. By default this value is the JBoss EAP property jboss.server.data.dir. For standalone servers, jboss.server.data.dir is located at EAP_HOME/standalone/data. For domains, each server will have its own serverX/data/activemq directory located under EAP_HOME/domain/servers. You can change the value of relative-to using the following management CLI command.

/subsystem=messaging-activemq/server=default/path=bindings-directory:write-attribute(name=relative-to,value=<RELATIVE_LOCATION>)

By default, JBoss EAP is configured to automatically create the bindings directory if it does not exist. Use the following management CLI command to toggle this behavior.

/subsystem=messaging-activemq/server=default:write-attribute(name=create-bindings-dir,value=<TRUE_FALSE>)

Setting value to true will enable automatic directory creation. Setting value to false will disable it.

You can read the location information for the message journal by using the management CLI command below. The output is also included to highlight default configuration.

/subsystem=messaging-activemq/server=default/path=journal-directory:read-resource
{
    "outcome" => "success",
    "result" => {
        "path" => "activemq/journal",
        "relative-to" => "jboss.server.data.dir"
    }
}

Note that by default the path to the journal is activemq/journal. You can change the location for path by using the following management CLI command.

/subsystem=messaging-activemq/server=default/path=journal-directory:write-attribute(name=path,value=<PATH_LOCATION>)

Also note the relative-to attribute in the output above. When relative-to is used, the value of the path attribute is treated as relative to the file path specified by relative-to. By default this value is the JBoss EAP property jboss.server.data.dir. For standalone servers, jboss.server.data.dir is located at EAP_HOME/standalone/data. For domains, each server will have its own serverX/data/activemq directory located under EAP_HOME/domain/servers. You can change the value of relative-to using the following management CLI command.

/subsystem=messaging-activemq/server=default/path=journal-directory:write-attribute(name=relative-to,value=<RELATIVE_LOCATION>)

By default, JBoss EAP is configured to automatically create the journal directory if it does not exist. Use the following management CLI command to toggle this behavior.

/subsystem=messaging-activemq/server=default:write-attribute(name=create-journal-dir,value=<TRUE_FALSE>)

Setting value to true will enable automatic directory creation. Setting value to false will disable it.

The attributes listed below are all child properties of the messaging server. Therefore, the command syntax for getting and setting their values using the management CLI is the same for each.

To read the current value of a given attribute, the syntax is as follows:

/subsystem=messaging-activemq/server=default:read-attribute(name=<ATTRIBUTE_NAME>)

The syntax for writing an attribute’s value follows a corresponding pattern.

/subsystem=messaging-activemq/server=default:write-attribute(name=<ATTRIBUTE_NAME>,value=<NEW_VALUE>)

This happens irrespective of whether you have executed a fsync() from the operating system or correctly synced data from inside a Java program!

By default many systems ship with disk write cache enabled. This means that even after syncing from the operating system there is no guarantee the data has actually made it to disk, so if a failure occurs, critical data can be lost.

Some more expensive disks have non volatile or battery backed write caches which won’t necessarily lose data on event of failure, but you need to test them!

If your disk does not have an expensive non volatile or battery backed cache and it’s not part of some kind of redundant array (e.g. RAID), and you value your data integrity you need to make sure disk write cache is disabled.

Be aware that disabling disk write cache can give you a nasty shock performance wise. If you’ve been used to using disks with write cache enabled in their default setting, unaware that your data integrity could be compromised, then disabling it will give you an idea of how fast your disk can perform when acting really reliably.

On Linux you can inspect or change your disk’s write cache settings using the tools hdparm (for IDE disks) or sdparm or sginfo (for SDSI/SATA disks)

On Windows you can check / change the setting by right clicking on the disk and clicking properties.

The Java NIO journal is highly performant, but if you are running JBoss EAP messaging using Linux Kernel 2.6 or later, Red Hat highly recommends that you use the ASYNCIO journal for the very best persistence performance.

You will need libaio installed to use the ASYNCIO journal. You can easily install it using the following YUM command:

yum install libaio

When using dedicated, shared store, high availability for data replication, you must configure both the live server and the backup server to use a shared directory on the NFS client. If you configure one server to use a shared directory on the NFS server and the other server to use a shared directory on the NFS client, the backup server cannot recognize when the live server starts or is running. So to work properly, both servers must specify a shared directory on the NFS client.

You must also configure the following options for the NFS client mount:

See the Shared Store section in this guide for more information about how to use a shared file system for high availability.

In some situations, zero persistence is required for a messaging system. Zero persistence means that no bindings data, message data, large message data, duplicate id caches, or paging data should be persisted.

To configure the messaging-activemq subsystem to perform zero persistence, set the persistence-enabled parameter to false.

/subsystem=messaging-activemq/server=default:write-attribute(name=persistence-enabled,value=false)

See the JBoss EAP 7 Migration Guide for information on importing and exporting journal data.

JBoss EAP messaging supports many message queues with each queue containing millions of messages. The JBoss EAP messaging server runs with limited memory thereby making it difficult to store all message queues in memory at one time.

Paging is a mechanism used by the JBoss EAP messaging server to transparently page messages in and out of memory on an as-needed basis in order to accommodate large message queues in a limited memory.

JBoss EAP messaging starts paging messages to disk, when the size of messages in memory for a particular address exceeds the maximum configured message size.

There is an individual folder for each address on the file system which stores messages in multiple files. These files which store the messages are called page files. Each file contains messages up to the maximum configured message size set by the page-size-bytes attribute.

The system navigates the page files as needed and removes the page files as soon as all messages in the page were received by client.

You can read the configuration for the paging directory by using the management CLI command below. In this example, the output displays the default configuration.

/subsystem=messaging-activemq/server=default/path=paging-directory:read-resource
{
    "outcome" => "success",
    "result" => {
        "path" => "activemq/paging",
        "relative-to" => "jboss.server.data.dir"
    }
}

The paging-directory configuration element specifies the location on the file system to store the page files. JBoss EAP creates one folder for each paging address in this paging directory and the page files are stored within these folders. By default, this path is activemq/paging/. You can change the path location by using the following management CLI command.

/subsystem=messaging-activemq/server=default/path=paging-directory:write-attribute(name=path,value=<PATH_LOCATION>)

Also note the relative-to attribute in the example output above. When relative-to is specified, the value of the path attribute is treated as relative to the file path specified by the relative-to attribute. By default, this value is the JBoss EAP jboss.server.data.dir property. For standalone servers, jboss.server.data.dir is located at EAP_HOME/standalone/data/. For managed domains, each server will have its own serverX/data/activemq/ directory located under EAP_HOME/domain/servers/. You can change the value of relative-to using the following management CLI command.

/subsystem=messaging-activemq/server=default/path=paging-directory:write-attribute(name=relative-to,value=<RELATIVE_LOCATION>)

When messages delivered to an address exceed the configured size, that address goes into "paging mode".

Even with page mode, the server may crash due to an out-of-memory error. JBoss EAP messaging keeps a reference to each page file on the disk. In a situation with millions of page files, JBoss EAP messaging can face memory exhaustion. To minimize this risk, it is important to set the attribute page-size-bytes to a suitable value. You must configure the memory for your JBoss EAP messaging server to be greater than two times the number of destinations times the max-size-bytes, otherwise an out-of-memory error can occur.

You can read the current maximum size in bytes (max-size-bytes) for an address by using the following management CLI command.

/subsystem=messaging-activemq/server=default/address-setting=<ADDRESS_SETTING>:read-attribute(name=max-size-bytes)

You can configure the maximum size in bytes (max-size-bytes) for an address by using the following management CLI command.

/subsystem=messaging-activemq/server=default/address-setting=<ADDRESS_SETTING>:write-attribute(name=max-size-bytes,value=MAX_SIZE)

Use a similar syntax when reading or writing the values for the other paging-related attributes of an address setting. The table below lists each attribute, along with a description and a default value.

The following table describes the parameters on the address settings:

Addresses with Multiple Queues

When a message is routed to an address that has multiple queues bound to it, there is only a single copy of the message in memory. Each queue only handles a reference to this original copy of the message, so the memory is freed up only when all the queues referencing the original message, have delivered the message.

JBoss EAP messaging supports setting the body of messages using the java.io.InputStream and java.io.OutputStream classes. Input streams are used directly for sending messages and output streams are used for receiving messages.

When receiving messages, there are two ways to deal with the output stream:

You can use any kind of stream you like, for example files, JDBC Blobs, or SocketInputStream, as long as it implements java.io.InputStream for sending messages and java.io.OutputStream for receiving messages.

Streaming Large Messages Using the Core API

The following table shows the methods available on the ClientMessage class that are available through JMS by using object properties.

The following code example sets the output stream when receiving a core message.

ClientMessage firstMessage = consumer.receive(...);

// Block until the stream is transferred
firstMessage.saveOutputStream(firstOutputStream);

ClientMessage secondMessage = consumer.receive(...);

// Do not wait for the transfer to finish
secondMessage.setOutputStream(secondOutputStream);

The following code example sets the input stream when sending a core message:

ClientMessage clientMessage = session.createMessage();
clientMessage.setInputStream(dataInputStream);

Streaming Large Messages Over JMS

When using JMS, JBoss EAP messaging maps the core API streaming methods by setting object properties. You use the Message.setObjectProperty(String name, Object value) method to set the input and output streams.

The InputStream is set using the JMS_AMQ_InputStream property on messages being sent.

BytesMessage bytesMessage = session.createBytesMessage();
FileInputStream fileInputStream = new FileInputStream(fileInput);
BufferedInputStream bufferedInput = new BufferedInputStream(fileInputStream);
bytesMessage.setObjectProperty("JMS_AMQ_InputStream", bufferedInput);
someProducer.send(bytesMessage);

The OutputStream is set using the JMS_AMQ_SaveStream property on messages being received in a blocking manner.

BytesMessage messageReceived = (BytesMessage) messageConsumer.receive(120000);
File outputFile = new File("huge_message_received.dat");
FileOutputStream fileOutputStream = new FileOutputStream(outputFile);
BufferedOutputStream bufferedOutput = new BufferedOutputStream(fileOutputStream);

// This will block until the entire content is saved on disk
messageReceived.setObjectProperty("JMS_AMQ_SaveStream", bufferedOutput);

The OutputStream can also be set in a non-blocking manner by using the JMS_AMQ_OutputStream property.

// This does not wait for the stream to finish. You must keep the consumer active.
messageReceived.setObjectProperty("JMS_AMQ_OutputStream", bufferedOutput);

You can specify where to send expired messages by setting an expiry address. If a message expires and no expiry address is specified, the message is removed from the queue and dropped.

You can set an expiry-address for an address-setting using the management CLI. In the below example, expired messages in the jms.queue.exampleQueue queue will be sent to the jms.queue.expiryQueue expiry address.

/subsystem=messaging-activemq/server=default/address-setting=jms.queue.exampleQueue:write-attribute(name=expiry-address,value=jms.queue.expiryQueue)

A reaper thread periodically inspects the queues to check whether messages have expired. You can set the scan period and thread priority for the reaper thread using the management CLI.

Set the scan period for the expiry reaper thread, which is how often, in milliseconds, the queues will be scanned to detect expired messages. The default is 30000. You can set this to -1 to disable the reaper thread.

/subsystem=messaging-activemq/server=default:write-attribute(name=message-expiry-scan-period,value=30000)

Set the thread priority for the expiry reaper thread. Possible values are from 0 to 9, with 9 being the highest priority. The default is 3.

/subsystem=messaging-activemq/server=default:write-attribute(name=message-expiry-thread-priority,value=3)

JBoss EAP messaging includes configuration that defines how much data to pre-fetch on behalf of consumers and that controls the rate at which consumers can consume messages.

Window-based flow control

JBoss EAP messaging pre-fetches messages into a buffer on each consumer. The size of the buffer is determined by the consumer-window-size attribute of a connection-factory. The example configuration below shows a connection-factory with the consumer-window-size attribute explicitly set.

<connection-factory name="MyConnFactory" ... consumer-window-size="1048576" />

Use the management CLI to read and write the value of consumer-window-size attribute for a given connection-factory. The examples below show how this done using the InVmConnectionFactory connection factory, which is the default for consumers residing in the same virtual machine as the server, e.g. a local MessageDrivenBean.

/subsystem=messaging-activemq/server=default/connection-factory=InVmConnectionFactory:read-attribute(name=consumer-window-size)
{
    "outcome" => "success",
    "result" => 1048576
}

/subsystem=messaging-activemq/server=default/connection-factory=InVmConnectionFactory:write-attribute(name=consumer-window-size,value=1048576)
{"outcome" => "success"}

The value for consumer-window-size must be an integer. Some values have special meaning as noted in the table below.

If you are using the core API, the consumer window size can be set from the ServerLocator using its setConsumerWindowSize() method.

If you are using JMS, the client can specify the consumer window size by using the setConsumerWindowSize() method of the instantiated ConnectionFactory.

Rate-limited flow control

JBoss EAP messaging can regulate the rate of messages consumed per second, a flow control method known as throttling. Use the consumer-max-rate attribute of the appropriate connection-factory to ensure that a consumer never consumes messages at a rate faster than specified.

<connection-factory name="MyConnFactory" ... consumer-max-rate="10" />

The default value is -1, which disables rate limited flow control.

The management CLI is the recommended way to read and write the consumer-max-rate attribute. The examples below show how this done using the InVmConnectionFactory connection factory, which is the default for consumers residing in the same virtual machine as the server, e.g. a local MessageDrivenBean.

/subsystem=messaging-activemq/server=default/connection-factory=InVmConnectionFactory:read-attribute(name=consumer-max-rate)
{
    "outcome" => "success",
    "result" => -1
}

/subsystem=messaging-activemq/server=default/connection-factory=InVmConnectionFactory:write-attribute(name=consumer-max-rate,value=100)
{"outcome" => "success"}

If you are using JMS the max rate size can be set using setConsumerMaxRate(int consumerMaxRate) method of the instantiated ConnectionFactory.

If you are using the Core API the rate can be set with the ServerLocator.setConsumerMaxRate(int consumerMaxRate) method.

JBoss EAP messaging can also limit the amount of data sent from a client in order to prevent the server from receiving too many messages.

Window-based flow control

JBoss EAP messaging regulates message producers by using an exchange of credits. Producers can send messages to an address as long as they have sufficient credits to do so. The amount of credits required to send a message is determined by its size. As producers run low on credits, they must request more from the server. Within the server configuration, the amount of credits a producer can request at one time is known as the producer-window-size, an attribute of the connection-factory element:

<connection-factory name="MyConnFactory" ... producer-window-size="1048576" />

The window size determines the amount of bytes that can be in-flight at any one time, thus preventing the remote connection from overloading the server.

Use the management CLI to read and write the producer-window-size attribute of a given connection factory. The examples below use the RemoteConnectionFactory, which is included in the default configuration and intended for use by remote clients.

subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:read-attribute(name=producer-window-size)
{
    "outcome" => "success",
    "result" => 65536
}

/subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:write-attribute(name=producer-window-size,value=65536)
{"outcome" => "success"}

If you are using JMS, the client can call the setProducerWindowSize(int producerWindowSize) method of the ConnectionFactory to set the window size directly.

If you are using the core API, the window size can be set using the setProducerWindowSize(int producerWindowSize) method of the ServerLocator.

Blocking producer window-based flow control

Typically, the messaging server always provides the same number of credits that was requested. However, it is possible to limit the number of credits sent by the server, which can prevent it from running out of memory due to producers sending more messages than can be handled at one time.

For example, if you have a JMS queue called myqueue and you set the maximum memory size to 10MB, the server will regulate the number of messages in the queue so that its size never exceeds 10MB. When the address gets full, producers will block on the client side until sufficient space is freed up on the address.

The address-setting configuration element contains the configuration for managing blocking producer flow control. An address-setting is used to apply a set of configuration to all queues registered to that address. See Configuring Address Settings for more information on how this is done.

For each address-setting requiring blocking producer flow control, you must include a value for the max-size-bytes attribute. The total memory for all queues bound to that address cannot exceed max-size-bytes. In the case of JMS topics, this means the total memory of all subscriptions in the topic cannot exceed max-size-bytes.

You must also set the address-full-policy attribute to BLOCK so the server knows that producers should be blocked if max-size-bytes is reached. Below is an example address-setting with both attributes set:

<address-setting ...
      name="myqueue"
      address-full-policy="BLOCK"
      max-size-bytes="100000" />

The above example would set the maximum size of the JMS queue "myqueue" to 100000 bytes. Producers will be blocked from sending to that address once it has reached its maximum size.

Use the management CLI to set these attributes, as in the examples below:

/subsystem=messaging-activemq/server=default/address-setting=myqueue:write-attribute(name=max-size-bytes,value=100000)
{"outcome" => "success"}

/subsystem=messaging-activemq/server=default/address-setting=myqueue:write-attribute(name=address-full-policy,value=BLOCK)
{"outcome" => "success"}

Rate-limited flow control

JBoss EAP messaging limits the number of messages a producer can send per second if you specify a producer-max-rate for the connection-factory it uses, as in the example below:

<connection-factory name="MyConnFactory" producer-max-rate="1000" />

The default value is -1, which disables rate limited flow control.

Use the management CLI to read and write the value for producer-max-rate. The examples below use the RemoteConnectionFactory, which is included in the default configuration and intended for use by remote clients.

/subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:read-attribute(name=producer-max-rate)
{
    "outcome" => "success",
    "result" => -1
}

/subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:write-attribute(name=producer-max-rate,value=100)
{"outcome" => "success"}

If you use the core API, set the rate by using the method ServerLocator.setProducerMaxRate(int producerMaxRate).

If you are using JNDI to instantiate and look up the connection factory, the max rate can be set on the client using the setProducerMaxRate(int producerMaxRate) method of the instantiated connection factory.

A connection factory can be configured to use pre-acknowledge mode by setting its pre-acknowledge attribute to true using the management CLI as below:

/subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:write-attribute(name=pre-acknowledge,value=true)

Pre-acknowledge mode can be configured in a client’s JNDI context environment, e.g. in a jndi.properties file:

java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
connection.ConnectionFactory=tcp://localhost:8080?preAcknowledge=true

Alternatively, to use pre-acknowledge mode using the JMS API, create a JMS Session with the ActiveMQSession.PRE_ACKNOWLEDGE constant.

// messages will be acknowledge on the server *before* being delivered to the client
Session session = connection.createSession(false, ActiveMQJMSConstants.PRE_ACKNOWLEDGE);

An interceptor must implement the Interceptor interface:

package org.apache.artemis.activemq.api.core.interceptor;

public interface Interceptor
{
   boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException;
}

The returned boolean value is important:

Interceptor classes should be added to JBoss EAP as a module. See Create a Custom Module in the JBoss EAP [Configuration Guide] for more information.

After adding their module to JBoss EAP as a custom module, both incoming and outgoing interceptors are added to the messaging subsystem configuration by using the management CLI.

Each interceptor should be added according to the example management CLI command below. The examples assume each interceptor has already been added to JBoss EAP as a custom module.

/subsystem=messaging-activemq/server=default:list-add(name=incoming-interceptors, value={name => "foo.bar.MyIncomingInterceptor", module=>"foo.bar.interceptors"})

Adding an outgoing interceptor follows a similar syntax, as the example below illustrates.

/subsystem=messaging-activemq/server=default:list-add(name=outgoing-interceptors, value={name => "foo.bar.MyOutgoingInterceptor", module=>"foo.bar.interceptors"})

The property _AMQ_GROUP_ID is used to identify a message group using the Core API on the client side. To pick a random unique message group identifier, you can also set the auto-group property to true on the SessionFactory.

The property JMSXGroupID is used to identify a message group for Java Messaging Service (JMS) clients. If you wish to send a message group with different messages to one consumer, you can set the same JMSXGroupID for different messages.

Message message = ...
message.setStringProperty("JMSXGroupID", "Group-0");
producer.send(message);

message = ...
message.setStringProperty("JMSXGroupID", "Group-0");
producer.send(message);

An alternative approach is to use the one of the following attributes of the connection-factory to be used by the client: auto-group or group-id.

When auto-group is set to true, the connection-factory will begin to use a random unique message group identifier for all messages sent through it. You can use the management CLI to set the auto-group attribute.

/subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:write-attribute(name=auto-group,value=true)

The group-id attribute will set the property JMSXGroupID to the specified value for all messages sent through the connection factory. To set a specific group-id on the connection factory, use the management CLI.

/subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:write-attribute(name=group-id,value="Group-0")

Below is in an example of an exclusive divert as it might appear in configuration:

<divert
  name="prices-divert"
  address="jms.topic.priceUpdates"
  forwarding-address="jms.queue.priceForwarding"
  filter="office='New York'"
  transformer-class-name="org.apache.activemq.artemis.jms.example.AddForwardingTimeTransformer"
  exclusive="true"/>

In this example, a divert called prices-divert is configured that will divert any messages sent to the address jms.topic.priceUpdates, which maps to any messages sent to a JMS topic called priceUpdates, to another local address jms.queue.priceForwarding, corresponding to a local JMS queue called priceForwarding

We also specify a message filter string so that only messages with the message property office with a value of New York will be diverted. All other messages will continue to be routed to the normal address. The filter string is optional, if not specified then all messages will be considered matched.

Note that a transformer class is specified. In this example the transformer simply adds a header that records the time the divert happened.

This example is actually diverting messages to a local store and forward queue, which is configured with a bridge that forwards the message to an address on another server. See Configuring Core Bridges for more details.

Below is an example of a non-exclusive divert. Non exclusive diverts can be configured in the same way as exclusive diverts with an optional filter and transformer.

<divert
  name="order-divert"
  address="jms.queue.orders"
  forwarding-address="jms.topic.spytopic"
  exclusive="false"/>

The above divert takes a copy of every message sent to the address jms.queue.orders, which maps to a JMS Queue called orders, and sends it to a local address called jms.topic.SpyTopic, corresponding to a JMS topic called SpyTopic).

Creating diverts

Use the management CLI to create the type of divert you want:

/subsystem=messaging-activemq/server=default/divert=my-divert:add(divert-address=news.in,forwarding-address=news.forward)

Non-exclusive diverts are created by default. To create an exclusive divert use the exclusive attribute:

/subsystem=messaging-activemq/server=default/divert=my-exclusive-divert:add(divert-address=news.in,forwarding-address=news.forward,exclusive=true)

The below table captures a divert’s attributes and their description. You can have the management CLI display this information using the following command:

/subsystem=messaging-activemq/server=default/divert=*:read-resource-description()

The server scheduled thread pool is used for most activities on the server side that require running periodically or with delays. It maps internally to a java.util.concurrent.ScheduledThreadPoolExecutor instance.

The maximum number of thread used by this pool is configured using the scheduled-thread-pool-max-size parameter. The default value is 5 threads. A small number of threads is usually sufficient for this pool. To change this value for the default JBoss EAP messaging server, use the following management CLI command:

/subsystem=messaging-activemq/server=default:write-attribute(name=scheduled-thread-pool-max-size,value=10)

The general purpose thread pool is used for most asynchronous actions on the server side. It maps internally to a java.util.concurrent.ThreadPoolExecutor instance.

The maximum number of threads used by this pool is configured using the thread-pool-max-size attribute.

If thread-pool-max-size is set to -1, the thread pool has no upper bound and new threads are created on demand if there are not enough threads available to fulfill a request. If activity later subsides, then threads are timed out and closed.

If thread-pool-max-size is set to a positive integer greater than zero, the thread pool is bounded. If requests come in and there are no free threads available in the pool, requests will block until a thread becomes available. It is recommended that a bounded thread pool be used with caution since it can lead to deadlock situations if the upper bound is configured too low.

The default value for thread-pool-max-size is 30. To set a new value for the default JBoss EAP messaging server, use the following management CLI command.

/subsystem=messaging-activemq/server=default:write-attribute(name=thread-pool-max-size,value=40)

See the Java 8 Javadoc for more information on unbounded (cached), and bounded (fixed) thread pools.

A single thread is also used on the server side to scan for expired messages in queues. We cannot use either of the thread pools for this since this thread needs to run at its own configurable priority.

Asynchronous IO has a thread pool for receiving and dispatching events out of the native layer. It is on a thread dump with the prefix ArtemisMQ-AIO-poller-pool. JBoss EAP messaging uses one thread per opened file on the journal (there is usually one).

There is also a single thread used to invoke writes on libaio. It is done to avoid context switching on libaio that would cause performance issues. This thread is found on a thread dump with the prefix ArtemisMQ-AIO-writer-pool.

JBoss EAP includes a client thread pool used for creating client connections. This pool is separate from the static pools mentioned earlier in this chapter and is used by JBoss EAP when it behaves like a client. For example, client thread pool clients are created as cluster connections with other nodes in the same cluster, or when the Artemis resource adapter connects to a remote Apache ActiveMQ Artemis messaging server integrated in a remote instance of JBoss EAP. The size of the client thread pool is set using the activemq.artemis.client.global.thread.pool.max.size system property.

However, the main use of the client thread pool is on the client side. A client can configure each ClientSessionFactory instance to not use the provided pool, but instead to create and maintain its own client thread pool. Any sessions created from that ClientSessionFactory will use the newly created pool.

To configure a ClientSessionFactory instance to use its own pools, use the appropriate setter methods immediately after creation. For example:

ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(...)
ClientSessionFactory myFactory = locator.createClientSessionFactory();
myFactory.setUseGlobalPools(false);
myFactory.setScheduledThreadPoolMaxSize(10);
myFactory.setThreadPoolMaxSize(-1);

If you are using the JMS API, you can set the same parameters on the ClientSessionFactory. For example:

ConnectionFactory myFactory = ActiveMQJMSClient.createConnectionFactory(myFactory);
myFactory.isUseGlobalPools(false);
myFactory.setScheduledThreadPoolMaxSize(10);
myFactory.setThreadPoolMaxSize(-1);

If you are using JNDI to instantiate ActiveMQConnectionFactory instances, you can also set these parameters using the management CLI, as in the examples given below for a standalone instance of JBoss EAP.

/subsystem=messaging-activemq/server=default/connection-factory=myConnectionFactory:write-attribute(name=use-global-pools,value=false)

/subsystem=messaging-activemq/server=default/connection-factory=myConnectionFactory:write-attribute(name=scheduled-thread-pool-max-size,value=10)

/subsystem=messaging-activemq/server=default/connection-factory=myConnectionFactory:write-attribute(name=thread-pool-max-size,value=1)

Note that the management CLI will remind you that a reload of the instance is required after you execute each of the above commands.

To enable duplicate message detection for sent messages, you need to set the value of the org.apache.activemq.artemis.api.core.Message.HDR_DUPLICATE_DETECTION_ID property, which resolves to _AMQ_DUPL_ID, to a unique value. When the target server receives the messages, if the _AMQ_DUPL_ID property is set, it will check its memory cache to see if it has already received a message with the value of that header. If it has, then this message will be ignored. See Configuring the Duplicate ID Cache for more information.

The value of the _AMQ_DUPL_ID property can be of type byte[] or SimpleString if you are using the core API. If you are using JMS, it must be a String.

The following example shows how to set the property for core API.

SimpleString myUniqueID = "This is my unique id";   // Can use a UUID for this

ClientMessage message = session.createMessage(true);
message.setStringProperty(HDR_DUPLICATE_DETECTION_ID, myUniqueID);

The following example shows how to set the property for JMS clients.

String myUniqueID = "This is my unique id";   // Can use a UUID for this

Message jmsMessage = session.createMessage();
message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(), myUniqueID);

The server maintains caches of received values of the _AMQ_DUPL_ID property that is sent to each address. Each address maintains its own address cache.

The cache is fixed in terms of size. The maximum size of cache is configured using the id-cache-size attribute. The default value of this parameter is 20000 elements. If the cache has a maximum size of n elements, then the (n + 1)th ID stored will overwrite the element 0 in the cache. The value is set using the following management CLI command:

/subsystem=messaging-activemq/server=default:write-attribute(name=id-cache-size,value=SIZE)

The caches can also be configured to persist to disk. This can be configured by setting the persist-id-cache attribute using the following management CLI command.

/subsystem=messaging-activemq/server=default:write-attribute(name=persist-id-cache,value=true)

If this value is set to true, then each ID will be persisted to permanent storage as they are received. The default value for this parameter is true.

In JBoss EAP, quality-of-service is a configurable attribute that determines how messages are consumed and acknowledged. The valid values for quality-of-service and their descriptions are below. See the table in the appendix for a full list of JMS bridge attributes.

It may possible to provide once and only once semantics by using the DUPLICATES_OK mode instead of ONCE_AND_ONLY_ONCE and then checking for duplicates at the destination and discarding them. See Configuring Duplicate Message Detection for more information. However, the cache would only be valid for a certain period of time. This approach therefore is not as watertight as using ONCE_AND_ONLY_ONCE, but it may be a good choice depending on your specific application needs.

There is a possibility that the target or source server will not be available at some point in time. If this occurs, the bridge will try to reconnect a number of times equal to the value of max-retries. The wait between attempts is set by failure-retry-interval.

However, it is possible for the JNDI lookup to hang if the network were to disappear during the JNDI lookup. To stop this from occurring, configure the JNDI definition to time out by setting the following properties on the JNDI InitialContext.

Once the initial JNDI connection has succeeded all subsequent calls are made using RMI. If you want to control the timeouts for the RMI connections, then this can be done with system properties. JBoss EAP uses Sun’s RMI, and the properties can be found in the Java SE documentation. The default connection timeout is 10 seconds and the default read timeout is 18 seconds.

If you implement your own factories for looking up JMS resources, you will have to manage any timeout issues in the implementation and expose configuration properties accordingly.

Core bridges can be configured to automatically add a unique duplicate ID value, if there is not already one in the message, before forwarding the message to the target. To configure a core bridge for duplicate message detection set the use-duplicate-detection attribute to true, which is the default value.

/subsystem=messaging-activemq/server=default/bridge=my-core-bridge:write-attribute(name=use-duplicate-detection,value=true)

Server discovery is a mechanism by which servers can propagate their connection details to:

This information, or cluster topology, is sent around normal JBoss EAP messaging connections to clients and to other servers over cluster connections. However, you need a way to establish the initial first connection. This can be done using dynamic discovery techniques like UDP and JGroups, or by providing a static list of initial connectors.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <broadcast-group name="my-broadcast-group" connectors="http-connector" socket-binding="messaging-group"/>
    ...
  </server>
</subsystem>
...
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
  ...
  <socket-binding name="messaging-group" interface="private" port="5432" multicast-address="231.7.7.7" multicast-port="9876"/>
  ...
</socket-binding-group>

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <broadcast-group name="my-broadcast-group" connectors="http-connector" jgroups-channel="activemq-cluster"/>
    ...
  </server>
</subsystem>

/subsystem=messaging-activemq/server=default/broadcast-group=my-broadcast-group:add(connectors=[http-connector],jgroups-channel=activemq-cluster)

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <discovery-group name="my-discovery-group" refresh-timeout="10000" socket-binding="messaging-group"/>
    ...
  </server>
</subsystem>
...
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
  ...
  <socket-binding name="messaging-group" interface="private" port="5432" multicast-address="231.7.7.7" multicast-port="9876"/>
  ...
</socket-binding-group>

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <discovery-group name="my-discovery-group" refresh-timeout="10000" jgroups-channel="activemq-cluster"/>
    ...
  </server>
</subsystem>

/subsystem=messaging-activemq/server=default/discovery-group=my-discovery-group:add(refresh-timeout=10000,jgroups-channel=activemq-cluster)

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <connection-factory name="RemoteConnectionFactory" entries="java:jboss/exported/jms/RemoteConnectionFactory" connectors="http-connector"/>
    ...
  </server>
</subsystem>

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <pooled-connection-factory name="activemq-ra" transaction="xa" entries="java:/JmsXA java:jboss/DefaultJMSConnectionFactory" connectors="in-vm"/>
    ...
  </server>
</subsystem>

final String groupAddress = "231.7.7.7";
final int groupPort = 9876;

ServerLocator factory =
  ActiveMQClient.createServerLocatorWithHA(new DiscoveryGroupConfiguration(
      groupAddress,
      groupPort,
      new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1)));
ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session1 = factory.createSession();
ClientSession session2 = factory.createSession();

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <connection-factory name="MyConnectionFactory" entries="..." connectors="http-connector http-node1 http-node2"/>
    ...
  </server>
</subsystem>

HashMap<String, Object> map = new HashMap<String, Object>();
map.put("host", "myhost");
map.put("port", "8080");

HashMap<String, Object> map2 = new HashMap<String, Object>();
map2.put("host", "myhost2");
map2.put("port", "8080");

TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);

ServerLocator locator = ActiveMQClient.createServerLocatorWithHA(server1, server2);
ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session = factory.createSession();

If a cluster connection is defined between nodes of a cluster, then JBoss EAP messaging will load balance messages arriving at a particular node from a client.

A messaging cluster connection can be configured to load balance messages in a round robin fashion, irrespective of whether there are any matching consumers on other nodes. It can also be configured to distribute to other nodes only if matching consumers exist. See the Message Redistribution section for more information.

Configuring the Cluster Connection

A cluster connection group servers into clusters so that messages can be load balanced between the nodes of the cluster. A cluster connection is defined in the JBoss EAP server configuration using the cluster-connection element.

Below is the default cluster-connection as defined in the *-full and *-full-ha profiles. See Cluster Connection Attributes for the complete list of attributes.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <cluster-connection name="my-cluster" discovery-group="dg-group1" connector-name="http-connector" address="jms"/>
    ...
  </server>
</subsystem>

In the case shown above the cluster connection will load balance messages sent to addresses that start with "jms". This cluster connection will, in effect, apply to all JMS queues and topics since they map to core queues that start with the substring "jms".

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <cluster-connection name="my-cluster" static-connectors="server0-connector server1-connector" .../>
    ...
  </server>
</subsystem>

Configuring a Cluster Connection for Duplicate Detection

The cluster connection internally uses a core bridge to move messages between nodes of the cluster. To configure a cluster connection for duplicate message detection, set the use-duplicate-detection attribute to true, which is the default value.

/subsystem=messaging-activemq/server=default/cluster-connection=my-cluster:write-attribute(name=use-duplicate-detection,value=true)

Cluster User Credentials

When creating connections between nodes of a cluster to form a cluster connection, JBoss EAP messaging uses a cluster user and password.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <cluster password="${jboss.messaging.cluster.password:CHANGE ME!!}"/>
    ...
  </server>
</subsystem>

With JBoss EAP messaging client-side load balancing, subsequent sessions created using a single session factory can be connected to different nodes of the cluster. This allows sessions to spread smoothly across the nodes of a cluster and not be clumped on any particular node.

The recommended way to declare a load balancing policy to be used by the client factory is to set the connection-load-balancing-policy-class-name attribute of the <connection-factory> resource. JBoss EAP messaging provides the following out-of-the-box load balancing policies, and you can also implement your own.

You can also implement your own policy by implementing the interface org.apache.activemq.artemis.api.core.client.loadbalance.ConnectionLoadBalancingPolicy

With message redistribution, JBoss EAP messaging can be configured to automatically redistribute messages from queues which have no consumers back to other nodes in the cluster which do have matching consumers. To enable this functionality, cluster connection’s message-load-balancing-type must be set to ON_DEMAND, which is the default value. You can set this using the following management CLI command.

/subsystem=messaging-activemq/server=default/cluster-connection=my-cluster:write-attribute(name=message-load-balancing-type,value=ON_DEMAND)

Message redistribution can be configured to kick in immediately after the last consumer on a queue is closed, or to wait a configurable delay after the last consumer on a queue is closed before redistributing. This is configured using the redistribution-delay attribute.

You use the redistribution-delay attribute to set how many milliseconds to wait after the last consumer is closed on a queue before redistributing messages from that queue to other nodes of the cluster that have matching consumers. A value of -1, which is the default value, means that messages will never be redistributed. A value of 0 means that messages will be immediately redistributed.

The address-setting in the default JBoss EAP configuration sets a redistribution-delay value of 1000, meaning that it will wait 1000 milliseconds before redistributing messages.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <address-setting name="#" redistribution-delay="1000" message-counter-history-day-limit="10" page-size-bytes="2097152" max-size-bytes="10485760" expiry-address="jms.queue.ExpiryQueue" dead-letter-address="jms.queue.DLQ"/>
    ...
  </server>
</subsystem>

It often makes sense to introduce a delay before redistributing as it is a common case that a consumer closes but another one quickly is created on the same queue. In this case, you may not want to redistribute immediately since the new consumer will arrive shortly.

Below is an example of an address-setting that sets a redistribution-delay of 0 for any queue or topic that is bound to an address that starts with "jms.". In this case, messages will be redistributed immediately.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
  <server name="default">
    ...
    <address-setting name="jms.#" redistribution-delay="0"/>
    ...
  </server>
</subsystem>

This address setting can be added using the following management CLI command.

/subsystem=messaging-activemq/server=default/address-setting=jms.#:add(redistribution-delay=1000)

Clustered grouping follows a different approach relative to normal message grouping. In a cluster, message groups with specific group ids can arrive on any of the nodes. It is important for a node to determine which group ids are bound to which consumer on which node. Each node is responsible for routing message groups correctly to the node which has the consumer processing those group ids, irrespective of where the message groups arrive by default. Once messages with a given group id are sent to a specific consumer connected to the given node in the cluster, then those messages are never sent to another node even if the consumer is disconnected.

This situation is addressed by a grouping handler. Each node has a grouping handler and this grouping handler (along with other handlers) is responsible for routing the message groups to the correct node. There are two types of grouping handlers: LOCAL and REMOTE.

The local handler is responsible for deciding the route that a message group should take. The remote handlers communicate with the local handler and work accordingly. Each cluster should choose a specific node to have a local grouping handler and all the other nodes should have remote handlers.

The node that initially receives a message group takes the routing decision based on regular cluster routing conditions (round-robin queue availability). The node proposes this decision to the respective grouping handler which then routes the messages to the proposed queue if it accepts the proposal.

If the grouping handler rejects the proposal, it proposes some other route and the routing takes place accordingly. The other nodes follow suite and forward the message groups to the chosen queue. After a message arrives on a queue, it is pinned to a customer on that queue.

You can configure grouping handlers using the management CLI. The following command adds a LOCAL grouping handler with the address news.europe.#.

/subsystem=messaging-activemq/server=default/grouping-handler=my-group-handler:add(grouping-handler-address="news.europe.#",type=LOCAL)

This will require a server reload.

reload

The below table lists the configurable attributes for a grouping-handler.

JBoss EAP 7 messaging allows servers to be linked together as live - backup pairs where each live server has a backup. Live servers receive messages from clients, while a backup server is not operational until failover occurs. A backup server can be owned by only one live server, and it will remain in passive mode, waiting to take over the live server’s work.

When a live server crashes or is brought down in the correct mode, the backup server currently in passive mode will become the new live server. If the new live server is configured to allow automatic failback, it will detect the old live server coming back up and automatically stop, allowing the old live server to start receiving messages again.

JBoss EAP messaging supports two different strategies for backing up a server: replication and shared store. Use the ha-policy attribute of the server configuration element to assign the policy of your choice to the given server. There are four valid values for ha-policy:

As you can see, the value specifies whether the server uses a data replication or a shared store ha policy, and whether it takes the role of master or slave.

Use the management CLI console to add an ha-policy to the server of your choice.

/subsystem=messaging-activemq/server=<SERVER>/ha-policy=<POLICY>:add

For example, use the following command to add the replication-master policy to the default server.

/subsystem=messaging-activemq/server=default/ha-policy=replication-master:add

The replication-master policy is configured with the default values. Values to override the default configuration can be included when you add the policy. The management CLI command to read the current configuration uses the following basic syntax.

/subsystem=messaging-activemq/server=<SERVER>/ha-policy=<POLICY>:read-resource

For example, use the following command to read the current configuration for the replication-master policy that was added above to the default server. The output is also is also included to highlight the default configuration.

/subsystem=messaging-activemq/server=default/ha-policy=replication-master:read-resource

{
    "outcome" => "success",
    "result" => {
        "check-for-live-server" => false,
        "cluster-name" => undefined,
        "group-name" => undefined,
        "initial-replication-sync-timeout" => 30000L
    }
}

See Data Replication and Shared Store for details on the configuration options available for each policy.

When using replication, the live and the backup server pairs do not share the same data directories, all data synchronization is done over the network. Therefore all (persistent) data received by the live server will be duplicated to the backup.

If the live server is cleanly shut down, the backup server will activate and clients will failover to backup. This behavior is pre-determined and is therefore not configurable when using data replication.

The backup server will first need to synchronize all existing data from the live server before replacing it. Unlike shared storage, therefore, a replicating backup will not be fully operational immediately after startup. The time it will take for the synchronization to happen depends on the amount of data to be synchronized and the network speed. Also note that clients are blocked for the duration of initial-replication-sync-timeout when the backup is started. After this timeout elapses, clients will be unblocked, even if synchronization is not completed.

After a successful failover, the backup’s journal will start holding newer data than the data on the live server. You can configure the original live server to perform a failback and become the live server once restarted. A failback will synchronize data between the backup and the live server before the live server comes back online.

In cases were both servers are shut down, the administrator will have to determine which server’s journal has the latest data. If the backup journal has the latest data, copy that journal to the live server. Otherwise, whenever it activates again, the backup will replicate the stale journal data from the live server and will delete its own journal data. If the live server’s data is the latest, no action is needed and the servers can be started normally.

The replicating live and backup pair must be part of a cluster, and it is the cluster-connection configuration element that defines how a backup server will find its live pair. See Configuring Cluster Connections for details on how to configure a cluster connection. When configuring a cluster-connection, keep in mind the following:

Specify a pair of live / backup servers by configuring the group-name attribute in either the master or the slave element. A backup server will only connect to a live server that shares the same group-name.

As a simple example of using a group-name, suppose you have 2 live servers and 2 backup servers. Because each live server needs to pair with its own backup, you would assign names like so:

In the above example, server backup1 with will search for the live server with the same group-name, pair1, which in this case is the server live1.

Much like in the shared store case, when the live server stops or crashes, its replicating, paired backup will become active and take over its duties. Specifically, the paired backup will become active when it loses connection to its live server. This can be problematic because this can also happen because of a temporary network problem. In order to address this issue, the paired backup will try to determine whether it still can connect to the other servers in the cluster. If it can connect to more than half the servers, it will become active. If it loses communication to its live server plus more than half the other servers in the cluster, the paired backup will wait and try reconnecting with the live server. This reduces the risk of a "split brain" situation where both the backup and live servers are processing messages without the other knowing it.

/subsystem=messaging-activemq/server=default/ha-policy=<POLICY>:write-attribute(name=<ATTRIBUTE>,value=<VALUE>)

/subsystem=messaging-activemq/server=default/ha-policy=replication-slave:write-attribute(name=restart-backup,value=true)

AMQ222207: The backup server is not responding promptly introducing latency beyond the limit. Replication server being disconnected now.

  drwxr-xr-x  May 20 18:12 journal
  drwxr-xr-x  May 10 18:12 journal1
  drwxr-xr-x  May 15 18:12 journal2

This style of high availability differs from data replication in that it requires a shared file system which is accessible by both the live and backup node. This means that the server pairs use the same location for their paging, message journal, bindings journal, and large messages in their configuration.

Also, each participating server in the pair, live and backup, will need to have a cluster-connection defined, even if not part of a cluster, because the cluster-connection defines how the backup server announces its presence to its live server and any other nodes. See Configuring Cluster Connections for details on how this is done.

When failover occurs and a backup server takes over, it will need to load the persistent storage from the shared file system before clients can connect to it. This style of high availability differs from data replication in that it requires a shared file system which is accessible by both the live and backup pair. Typically this will be some kind of high performance Storage Area Network, or SAN. Red Hat does not recommend using Network Attached Storage, known as a NAS, for your storage solution.

The advantage of shared store high availability is that no replication occurs between the live and backup nodes, this means it does not suffer any performance penalties due to the overhead of replication during normal operation.

The disadvantage of shared store replication is that when the backup server activates it needs to load the journal from the shared store which can take some time depending on the amount of data in the store. Also, it requires a shared storage solution supported by JBoss EAP.

If you require the highest performance during normal operation, Red Hat recommends having access to a highly performant SAN and accept the slightly slower failover costs. Exact costs will depend on the amount of data.

/subsystem=messaging-activemq/server=default/ha-policy=<POLICY>:write-attribute(name=<ATTRIBUTE>,value=<VALUE>)

/subsystem=messaging-activemq/server=default/ha-policy=shared-store-slave:write-attribute(name=restart-backup,value=true)

After a live server has failed and a backup taken has taken over its duties, you may want to restart the live server and have clients fail back to it.

In case of a shared store, simply restart the original live server and kill the new live server by killing the process itself. Alternatively, you can set allow-fail-back to true on the slave which will force it to automatically stop once the master is back online. The management CLI command to set allow-fail-back looks like the following:

/subsystem=messaging-activemq/server=default/ha-policy=shared-store-slave:write-attribute(name=allow-fail-back,value=true)

In replication HA mode you need to set an extra property check-for-live-server to true in the master configuration.

/subsystem=messaging-activemq/server=default/ha-policy=replication-master:write-attribute(name=check-for-live-server,value=true)

If set to true, a live server will search the cluster during startup for another server using its nodeID. If it finds one, it will contact this server and try to "fail-back". Since this is a remote replication scenario, the original live server will have to synchronize its data with the backup running with its ID. Once they are in sync, it will request the backup server to shut down so it can take over active processing. This behavior allows the original live server to determine whether there was a fail-over, and if so whether the server that took its duties is still running or not.

For shared stores, it is also possible to cause failover to occur on normal server shut down, to enable this set failover-on-server-shutdown to true in the HA configuration on either the master or slave like so:

/subsystem=messaging-activemq/server=default/ha-policy=shared-store-slave:write-attribute(name=failover-on-server-shutdown,value=true)

You can also force the running backup server to shut down when the original live server comes back up, allowing the original live server to take over automatically, by setting allow-failback to true.

/subsystem=messaging-activemq/server=default/ha-policy=shared-store-slave:write-attribute(name=allow-failback,value=true)

JBoss EAP also makes it possible to colocate backup messaging servers in the same JVM as another live server. Take for example a simple two node cluster of standalone servers where each live server colocates the backup for the other. You can use either a shared store or a replicated HA policy when colocating servers in this way. There are two important things to remember when configuring messaging servers for colocation.

First, each server element in the configuration will need its own remote-connector and remote-acceptor that listen on unique ports. For example, a live server can be configured to listen on port 5445, while its backup uses 5446. The ports are defined in socket-binding elements that must be added to the default socket-binding-group. Cluster-related configuration elements in each server configuration will use the new remote-connector. The relevant configuration is included in each of the examples that follow.

Secondly, remember to properly configure paths for journal related directories. For example, in a shared store colocated topology, both the live server and its backup, colocated on another live server, must be configured to share directory locations for the binding and message journals, for large messages, and for paging.

JBoss EAP messaging defines two types of client failover:

JBoss EAP messaging also provides 100% transparent automatic reattachment of connections to the same server (e.g. in case of transient network problems). This is similar to failover, except it is reconnecting to the same server and is discussed in Client Reconnection and Session Reattachment.

During failover, if the client has consumers on any non persistent or temporary queues, those queues will be automatically recreated during failover on the backup node, since the backup node will not have any knowledge of non persistent queues.

/subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:read-resource

/subsystem=messaging-activemq/server=default/cluster-connection=my-cluster:read-resource

/subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:write-attribute(name=reconnect-attempts,value=<NEW_VALUE>)

/subsystem=messaging-activemq/server=default/connection-factory=RemoteConnectionFactory:write-attribute(name=initial-connect-attempts,value=<NEW_VALUE>)

This section discusses connection time to live (TTL) and explains how JBoss EAP messaging handles crashed clients and clients that have exited without cleanly closing their resources.

Cleaning up Dead Connection Resources on the Server

Before a JBoss EAP client application exits, it should close its resources in a controlled manner, using a finally block.

Below is an example of a core client appropriately closing its session and session factory in a finally block:

ServerLocator locator = null;
ClientSessionFactory sf = null;
ClientSession session = null;

try {
   locator = ActiveMQClient.createServerLocatorWithoutHA(..);

   sf = locator.createClientSessionFactory();;

   session = sf.createSession(...);

   ... do some stuff with the session...
}
finally {
   if (session != null) {
      session.close();
   }

   if (sf != null) {
      sf.close();
   }

   if(locator != null) {
      locator.close();
   }
}

And here is an example of a well behaved JMS client application:

Connection jmsConnection = null;

try {
   ConnectionFactory jmsConnectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(...);

   jmsConnection = jmsConnectionFactory.createConnection();

   ... do some stuff with the connection...
}
finally {
   if (connection != null) {
      connection.close();
   }
}

Unfortunately sometimes clients crash and do not have a chance to clean up their resources. If this occurs, it can leave server side resources hanging on the server. If these resources are not removed they would cause a resource leak on the server, and over time this likely would result in the server running out of memory or other resources.

When looking to clean up dead client resources, it is important to be aware of the fact that sometimes the network between the client and the server can fail and then come back, allowing the client to reconnect. Because JBoss EAP supports client reconnection, it is important that it not clean up "dead" server side resources too soon, or clients will be prevented any client from reconnecting and regaining their old sessions on the server.

JBoss EAP makes all of this configurable. For each ClientSessionFactory configured, a Time-To-Live, or TTL, property can be used to set how long the server will keep a connection alive in milliseconds in the absence of any data from the client. The client will automatically send "ping" packets periodically to prevent the server from closing its connection. If the server does not receive any packets on a connection for the length of the TTL time, it will automatically close all the sessions on the server that relate to that connection.

If you are using JMS, the connection TTL is defined by the ConnectionTTL attribute on a ActiveMQConnectionFactory instance, or if you are deploying JMS connection factory instances direct into JNDI on the server side, you can specify it in the xml config, using the parameter connectionTtl.

The default value for ConnectionTTL on an network-based connection, such as an http-connector, is 60000, i.e. 1 minute. The default value for connection TTL on a internal connection, e.g. an in-vm connection, is -1. A value of -1 for ConnectionTTL means the server will never time out the connection on the server side.

If you do not want clients to specify their own connection TTL, you can set a global value on the server side. This can be done by specifying the connection-ttl-override attribute in the server configuration. The default value for connection-ttl-override is -1 which means "do not override", i.e. let clients use their own values.

Closing Core Sessions or JMS Connections

It is important that all core client sessions and JMS connections are always closed explicitly in a finally block when you are finished using them.

If you fail to do so, JBoss EAP will detect this at garbage collection time. It will then close the connection and log a warning similar to the following:

[Finalizer] 20:14:43,244 WARNING [org.apache.activemq.artemis.core.client.impl.DelegatingSession]  I'm closing a ClientSession you left open. Please make sure you close all ClientSessions explicitly before let
ting them go out of scope!
[Finalizer] 20:14:43,244 WARNING [org.apache.activemq.artemis.core.client.impl.DelegatingSession]  The session you didn't close was created here:
java.lang.Exception
   at org.apache.activemq.artemis.core.client.impl.DelegatingSession.<init>(DelegatingSession.java:83)
   at org.acme.yourproject.YourClass (YourClass.java:666)

Note that if you are using JMS the warning will involve a JMS connection, not a client session. Also, the log will tell you the exact line of code where the unclosed JMS connection or core client session was instantiated. This will enable you to pinpoint the error in your code and correct it appropriately.

Detecting Failure from the Client Side

As long as the client is receiving data from the server it will consider the connection to be alive. If the client does not receive any packets for client-failure-check-period milliseconds, it will consider the connection failed and will either initiate failover, or call any FailureListener instances, or ExceptionListener instances if you are using JMS, depending on how the client has been configured.

If you are using JMS the behavior is defined by the ClientFailureCheckPeriod attribute on a ActiveMQConnectionFactory instance.

The default value for client failure check period on a network connection, for example an HTTP connection, is 30000, or 30 seconds. The default value for client failure check period on an in-vm connection, is -1. A value of -1 means the client will never fail the connection on the client side if no data is received from the server. Whatever the type of connection, the check period is typically much lower than the value for connection TTL on the server so that clients can reconnect in case of transitory failure.

Configuring Asynchronous Connection Execution

Most packets received on the server side are executed on the remoting thread. These packets represent short-running operations and are always executed on the remoting thread for performance reasons.

However, by default some kinds of packets are executed using a thread from a thread pool so that the remoting thread is not tied up for too long. Please note that processing operations asynchronously on another thread adds a little more latency. These packets are:

org.apache.activemq.artemis.core.protocol.core.impl.wireformat.RollbackMessage

org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionCloseMessage

org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionCommitMessage

org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionXACommitMessage

org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionXAPrepareMessage

org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionXARollbackMessage

To disable asynchronous connection execution, set the parameter async-connection-execution-enabled to false. The default value is true.

JBoss EAP messaging clients can be configured to automatically reconnect or reattach to the server in the event that a failure is detected in the connection between the client and the server.

Transparent Session Reattachment

If the failure was due to some transient cause such as a temporary network outage, and the target server was not restarted, the sessions will still exist on the server, assuming the client has not been disconnected for more than the value of connection-ttl. See Detecting Dead Connections.

In this scenario, JBoss EAP will automatically reattach the client sessions to the server sessions when the re-connection is made. This is done 100% transparently and the client can continue exactly as if nothing had happened.

As JBoss EAP messaging clients send commands to their servers they store each sent command in an in-memory buffer. When a connection fails and the client subsequently attempts to reattach to the same server, as part of the reattachment protocol, the server gives the client the id of the last command it successfully received.

If the client has sent more commands than were received before failover it can replay any sent commands from its buffer so that the client and server can reconcile their states.

The size in bytes of this buffer is set by the confirmationWindowSize property. When the server has received confirmationWindowSize bytes of commands and processed them it will send back a command confirmation to the client, and the client can then free up space in the buffer.

If you are using the JMS service on the server to load your JMS connection factory instances into JNDI, then this property can be configured in the server configuration, by setting the confirmation-window-size attribute of the chosen connection-factory. If you are using JMS but not using JNDI then you can set these values directly on the ActiveMQConnectionFactory instance using the appropriate setter method, setConfirmationWindowSize. If you are using the core API, the ServerLocator instance has a setConfirmationWindowSize method exposed as well.

Setting confirmationWindowSize to -1, which is also the default, disables any buffering and prevents any reattachment from occurring, forcing a reconnect instead.

Session Reconnection

Alternatively, the server might have actually been restarted after crashing or it might have been stopped. In such a case any sessions will no longer exist on the server and it will not be possible to 100% transparently reattach to them.

In this case, JBoss EAP will automatically reconnect the connection and recreate any sessions and consumers on the server corresponding to the sessions and consumers on the client. This process is exactly the same as what happens when failing over to a backup server.

Client reconnection is also used internally by components such as core bridges to allow them to reconnect to their target servers.

See the section on Automatic Client Failover to get a full understanding of how transacted and non-transacted sessions are reconnected during a reconnect and what you need to do to maintain once and only once delivery guarantees.

Configuring Reconnection Attributes

Client reconnection is configured by setting the following properties:

If you are using JMS and JNDI on the client to look up your JMS connection factory instances then you can specify these parameters in the JNDI context environment. For example, your jndi.properties file might look like the following.

java.naming.factory.initial = ActiveMQInitialContextFactory
connection.ConnectionFactory=tcp://localhost:8080?retryInterval=1000&retryIntervalMultiplier=1.5&maxRetryInterval=60000&reconnectAttempts=1000

If you are using JMS, but instantiating your JMS connection factory directly, you can specify the parameters using the appropriate setter methods on the ActiveMQConnectionFactory immediately after creating it.

If you are using the core API and instantiating the ServerLocator instance directly you can also specify the parameters using the appropriate setter methods on the ServerLocator immediately after creating it.

If your client does manage to reconnect but the session is no longer available on the server, for instance if the server has been restarted or it has timed out, then the client will not be able to reattach, and any ExceptionListener or FailureListener instances registered on the connection or session will be called.

ExceptionListeners and SessionFailureListeners

Note that when a client reconnects or reattaches, any registered JMS ExceptionListener or core API SessionFailureListener will be called.

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

Forward compatibility requires no code changes to legacy JBoss EAP 6 JMS clients. Support is provided by the JBoss EAP messaging-activemq subsystem and its resources. To enable support of forward compatibility make the following changes to the configuration of the JBoss EAP 7 server. Example management CLI commands for a standalone server are provided for each step.

Management CLI migrate Operation

When you run the management CLI migrate operation to update your messaging subsystem configuration, if the boolean argument add-legacy-entries is set to true, the messaging-activemq subsystem creates the legacy-connection-factory resource and adds legacy-entries to the jms-queue and jms-topic resources. The legacy entries in the migrated messaging-activemq subsystem will correspond to the entries specified in the legacy messaging subsystem and the regular entries are created with a -new suffix.

If the boolean argument add-legacy-entries is set to false when you run the migrate operation, no legacy resources are created in the messaging-activemq subsystem and legacy JMS clients will not be able to communicate with the JBoss EAP 7 servers.

Backward compatibility requires no configuration change in the legacy JBoss EAP 7 servers. JBoss EAP 7 JMS clients do not look up resources on the legacy server, but instead use client-side JNDI to create JMS resources. JBoss EAP 7 JMS clients can then use these resources to communicate with the legacy server using the HornetQ core protocol.

JBoss EAP messaging supports client-side JNDI to create JMS ConnectionFactory and Destination resources.

For example, if a JBoss EAP 7 JMS client wants to communicate with a legacy server using a JMS queue named "myQueue", it must use the following properties to configure its JNDI InitialContext:

java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
connectionFactory.jms/ConnectionFactory=tcp://<legacy server address>:5445? \
    protocolManagerFactoryStr=org.apache.activemq.artemis.core.protocol.hornetq.client.HornetQClientProtocolManagerFactory
queue.jms/myQueue=myQueue

The client can then use the jms/ConnectionFactory name to create the JMS ConnectionFactory and use the jms/myQueue to create the JMS Queue. Note that the property protocolManagerFactoryStr=org.apache.activemq.artemis.core.protocol.hornetq.client.HornetQClientProtocolManagerFactory is mandatory when specifying the URL of the legacy connection factory. This allows the JBoss EAP messaging JMS client to communicate with the HornetQ broker in the legacy server.