Red Hat JBoss Enterprise Application Platform Administration I

During the remainder of this book, the Red Hat JBoss Enterprise Application Platform (JBoss EAP) embedded ActiveMQ Artemis is referred to as ActiveMQ. Red Hat JBoss Enterprise Application Platform (JBoss EAP) provides an embedded instance of ActiveMQ Artemis. Its network configuration is based on the following components:

Because JBoss EAP acts as both a server and a client for ActiveMQ, the default configuration files include definitions for both component types. The following two kinds of ActiveMQ acceptors and connectors are provided:

Networking parameters for an ActiveMQ connector are defined indirectly by referring to an acceptor element. The connector connects to the IP address and TCP port from which the acceptor accepts connections. This indirection is related to ActiveMQ remote clients using a discovery mechanism to find connectable servers.

The following listing shows the connectors and acceptors in the default JBoss EAP configuration files:

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
    <server name="default">
        ...

        <http-connector
          name="http-connector"
          socket-binding="http"
          endpoint="http-acceptor" /> 

        ...

        <in-vm-connector
          name="in-vm"
          server-id="0" /> 

        <http-acceptor
          name="http-acceptor"
          "http-listener="default"> 

        ...

        <in-vm-acceptor
          name="in-vm"
          server-id="0" />

        ...
    </server>
</subsystem>

The remote type is a third connector and acceptor type that JBoss EAP supports. This type enables remote clients to connect to the messaging server by using the ActiveMQ native protocol instead of HTTP tunneling. The ActiveMQ native protocol is required by remote clients running external to the JBoss EAP server. Additionally, it enables remote clients to connect to standalone ActiveMQ servers.

Creating a new <remote-connector> and <remote-acceptor> pair on JBoss EAP also requires creating a new <socket-binding>. These provide the IP address and TCP port to be used by the <remote-acceptor>.

Connection factory resources defined inside the messaging-activemq subsystem refer to an ActiveMQ connector also defined in the same subsystem. The following excerpt shows the connection-factory resources in the default JBoss EAP configuration files:

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0">
    <server name="default">
        ....
        <connection-factory
          name="InVmConnectionFactory"
          connectors="in-vm"
          entries="java:/ConnectionFactory" /> 

        <connection-factory
          name="RemoteConnectionFactory"
          connectors="http-connector"
          entries="java:jboss/exported/jms/RemoteConnectionFactory"/> 
        ...
    </server>
</subsystem>

Each <connection-factory> element refers to a different connector and is bound to different JNDI names by using the entries attribute.

Jakarta EE applications should not use the JMS ConnectionFactory resources. Instead, they should use a JMS PooledConnectionFactory, which provides the following:

The following excerpt shows the pooled-connection-factory resource in the default JBoss EAP configuration files:

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

In this example, the pooled connection factory is used by Jakarta EE applications when no connection factory is declared. Notice that the pooled connection factory refers to the in-vm connector.

If a different messaging server is to be used by default, then the factory should either be changed to refer to a different connector element or replaced by one referring to a JCA resource adapter.

Applications might refer to a connection factory via a JNDI name that does not exist. Thus, administrators must create a new pooled-connection-factory resource under the same JNDI name referring to the correct connector.

For example, to use the JNDI name java:/MyCF and point to the embedded messaging server, add the following to the messaging-activemq subsystem:

<pooled-connection-factory name="mycf" transaction="xa" connectors="in-vm" entries="java:/MyCF"/>

The following CLI command creates the resource from the previous listing under the full profile for a JBoss EAP managed domain:

[domain@localhost:9990 /] cd /profile=full/subsystem=messaging-activemq/​server=default
[domain@localhost:9990 server=default] ./pooled-connection-factory=mycf:add(\
connectors=[in-vm], entries=[java:/jms/MyCF])

If an application refers to a non-existing JNDI name it might deploy without errors, and throw Java NamingException errors only at run-time, when the application tries to actually connect to the messaging server.

The reason to use a pooled connection factory instead of a regular connection factory is the same as using a JDBC datasource instead of a driver manager. Although Jakarta EE applications can use connection factories and driver managers, they are less efficient due to the following reasons:

Both JDBC datasource and JMS pooled connection factory objects bring connection pools to improve application performance and scalability. With JDBC, the difference is that the developer must use the right interface, but for JMS only the administrator has to create the correct resource type. This is because a PooledConnectionFactory is also a ConnectionFactory.

When using the embedded Message-oriented Middleware (MOM) from JBoss EAP, creating the JMS destinations resources also creates the underlying MOM objects. This facility is provided by the messaging-activemq subsystem that closely integrates JBoss EAP with the embedded ActiveMQ instance.

To create a destination by using the CLI, create either a jms-queue or a jms-topic resource. For example, the following command create a topic called stocks that is bound to the JNDI name java:/jms/broker/StockUpdates:

[domain@localhost:9990 server=default] ./jms-topic=stocks:add(entries=[java:/jms/broker/StockUpdates])

The previous command adds the following to the domain mode configuration files:

<jms-topic
  name="stocks" 
  entries="java:/jms/broker/StockUpdates"/> 

A jms-queue resource can have all attributes from a jms-topic resource as well as the following attributes:

JMS destinations for the embedded MOM in JBoss EAP are created and configured by using the management console. To view the destinations in managed domain mode, navigate to Configuration → Profiles, select either full or menu:[\full-ha], and select Messaging → Server → default → Destinations. Click View next to the Destinations button.

Figure 8.1: Destinations navigation

Within the destinations page, click either JMS Queue or JMS Topic to manage the corresponding destinations.

Figure 8.2: Managing JMS queues

From this page, destinations can be created, modified, and removed. Use the links on the left to configure other messaging parameters.

In the embedded ActiveMQ instance, JMS destinations are monitored by using object run-time attributes and operations.

In standalone server mode, monitoring attributes and operations are available on the same object that defines the resource as part of the server profile. For example, on a queue object, the message-count attribute stores the number of messages waiting to be consumed. To view this count on a hypothetical queue called MyQueue, use the following command:

[standalone@localhost:9990 /] cd /subsystem=messaging-activemq/server=default
[standalone@localhost:9990 server=default] ./jms-queue=MyQueue:read-attribute(\
name=message-count)

In managed domain server mode, the same attributes and operations are available from a running server instance, but not from the subsystem configuration. For example, the messages-added operation counts the number of messages published to the destination since the MOM was started.

Messages are listed in the DMR format, but each message only shows headers and properties as object attributes. There is no way to see a message body by using the management CLI.

To list the number of messages waiting to be consumed in a queue called MyQueue within the srv1 server on the devhost host, use the following command to invoke the list-messages operation:

[domain@localhost:9990 /] cd /host=devhost/server=srv1
[domain@localhost:9990 server=srv1] cd ./subsystem=messaging-activemq/server=default
[domain@localhost:9990 server=default] ./jms-queue=MyQueue:list-messages
{
    "outcome" => "success",
    "result" => [ 
        {
            "JMSPriority" => 4, 
            "JMSMessageID" => "ID:b921a30-12e4-11e6-ae18-597e323e1397",
            "address" => "jms.queue.TestQueue", 
            "JMSExpiration" => 0,
            "AMQ_CID" => "f51cfb7a-12e4-11e6-ae18-597e323e151397",
            "MyAppProperty" => "MyAppValueXYZ", 
            "JMSTimestamp" => 1462468442322L,
            "messageID" => 5,
            "JMSDeliveryMode" => "PERSISTENT"
        },
        {
            "JMSPriority" => 4,
            "JMSMessageID" => "ID:f5136421-12e4-11e6-ae18-597e323e2def",
            "address" => "jms.queue.TestQueue",
            "JMSExpiration" => 0,
            "AMQ_CID" => "3d0cfb7a-12e4-11e6-ae18-597e323e2def",
            "OtherAppProperty" => "OtherValueASD",
            "JMSTimestamp" => 1462468442339L,
            "messageID" => 9,
            "JMSDeliveryMode" => "PERSISTENT"
        }
    ]
}

There is no way to distinguish attributes and message headers from message properties just by the list-messages operation output. It is similarly impossible to determine which ones are defined by the MOM.

Naturally, the attributes and operations differ for queues and topics. For example, only topics have subscribers. Check the JBoss EAP and A-MQ product documentation and the JMS specification for information about specific headers and properties. Also check with the application developer about application-defined properties.