JBoss Community Archive (Read Only)

JBoss AS 7.2

Messaging configuration

The JMS server configuration is done through the messaging subsystem. In this chapter we are going outline the frequently used configuration options. For a more detailed explanation please consult the HornetQ user guide (See "Component Reference"). 

Connection Factories

There are two kinds of basic JMS connection-factory:

  • In-VM connection factories can be used by a local client (i.e. one running in the same JVM as the server)

  • Netty connections factories can be used by a remote client. 

There is also a pooled-connection-factory which is special in that it leverages the outbound adapter of the HornetQ JCA Resource Adapter.  It is also special because:

  • It is only available to local clients, although it can be configured to point to a remote server.

  • As the name suggests, it is pooled and therefore provides superior performance to the clients which are able to use it.  The pool size can be configured via the max-pool-size and min-pool-size attributes.

  • It should only be used to send (i.e. produce) messages.

  • It can be configured to use specific security credentials via the user and password attributes.  This is useful if the remote server to which it is pointing is secured.

  • Resources acquired from it will be automatically enlisted any on-going JTA transaction.  If you want to send a message from an EJB using CMT then this is likely the connection factory you want to use so the send operation will be atomically committed along with the rest of the EJB's transaction operations.

To be clear, the inbound adapter of the HornetQ JCA RA (which is for consuming messages) is only used by MDBs and other JCA-based components.  It is not available to traditional clients.

Both a connection-factory a pooled-connection-factory reference a connector declaration.  

A netty-connector is associated with a socket-binding which tells the client using the connection-factory where to connect.

  • A connection-factory referencing a netty-connector is suitable to be used by a remote client to send messages to or receive messages from the server (assuming the connection-factory has an appropriately exported entry).  

  • A pooled-connection-factory referencing a netty-connector is suitable to be used by a local client to send messages to a remote server granted the socket-binding references an outboud-socket-binding pointing to the remote server in question.

An in-vm-connector is associated with a server-id which tells the client using the connection-factory where to connect (since multiple HornetQ servers can run in a single JVM).

  • A connection-factory referencing an in-vm-connector is suitable to be used by a local client to either send messages to or receive messages from a local server.  

  • A pooled-connection-factory referencing an in-vm-connector is suitable to be used by a local client only to send messages to a local server.

The entry declaration of a connection-factory or a pooled-connection-factory specifies the JNDI name under which the factory will be exposed.  Only JNDI names bound in the "java:jboss/exported" namespace are available to remote clients.  If a connection-factory has an entry bound in the "java:jboss/exported" namespace a remote client would look-up the connection-factory using the text after "java:jboss/exported".  For example, the "RemoteConnectionFactory" is bound by default to "java:jboss/exported/jms/RemoteConnectionFactory" which means a remote client would look-up this connection-factory using "jms/RemoteConnectionFactory".  A pooled-connection-factory should not have any entry bound in the "java:jboss/exported" namespace because a pooled-connection-factory is not suitable for remote clients. 

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <connectors>
      <netty-connector name="netty" socket-binding="messaging"/>
      <netty-connector name="netty-throughput" socket-binding="messaging-throughput">
          <param key="batch-delay" value="50"/>
      </netty-connector>
      <in-vm-connector name="in-vm" server-id="0"/>
   </connectors>
   [...]
   <jms-connection-factories>
      <connection-factory name="InVmConnectionFactory">
          <connectors>
              <connector-ref connector-name="in-vm"/>
          </connectors>
          <entries>
              <entry name="java:/ConnectionFactory"/>
          </entries>
      </connection-factory>
      <connection-factory name="RemoteConnectionFactory">
          <connectors>
              <connector-ref connector-name="netty"/>
          </connectors>
          <entries>
              <entry name="java:jboss/exported/jms/RemoteConnectionFactory"/>
          </entries>
      </connection-factory>
      <pooled-connection-factory name="hornetq-ra">
          <transaction mode="xa"/>
          <connectors>
              <connector-ref connector-name="in-vm"/>
          </connectors>
          <entries>
              <entry name="java:/JmsXA"/>
          </entries>
      </pooled-connection-factory>
   </jms-connection-factories>
   [...]
</subsystem>

(See standalone/configuration/standalone-full.xml)

JMS Queues and Topics

JMS queues and topics are sub resources of the messaging subsystem.  They are defined in the jms-destinations section.  One can define either a jms-queue or jms-topic.  Each destination must be given a name and contain at least one entry element.

Each entry refers to a JNDI name of the queue or topic.  Keep in mind that any jms-queue or jms-topic which needs to be accessed by a remote client needs to have an entry in the "java:jboss/exported" namespace.  As with connection factories, if a jms-queue or jms-topic has an entry bound in the "java:jboss/exported" namespace a remote client would look it up using the text after "java:jboss/exported".  For example, the following jms-queue "testQueue" is bound to "java:jboss/exported/jms/queue/test" which means a remote client would look-up this jms-queue using "jms/queue/test".  A local client could look it up using "java:jboss/exported/jms/queue/test", "java:jms/queue/test", or more simply "jms/queue/test": 

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <jms-destinations>
       <jms-queue name="testQueue">
           <entry name="jms/queue/test"/>
           <entry name="java:jboss/exported/jms/queue/test"/>
       </jms-queue>
       <jms-topic name="testTopic">
           <entry name="jms/topic/test"/>
           <entry name="java:jboss/exported/jms/topic/test"/>
       </jms-topic>
   </jms-destinations>
</subsystem>

(See standalone/configuration/standalone-full.xml)

JMS endpoints can easily be created through the CLI: 

[standalone@localhost:9999 /] jms-queue add --queue-address=myQueue --entries=queue/myQueue
[standalone@localhost:9999 /] /subsystem=messaging/hornetq-server=default/jms-queue=myQueue:read-resource
{
    "outcome" => "success",
    "result" => {
        "durable" => true,
        "entries" => ["queue/myQueue"],
        "selector" => undefined
    }
}

A number of additional commands to maintain the JMS subsystem are available as well: 

[standalone@localhost:9999 /] jms-queue --help --commands
add
...
remove
To read the description of a specific command execute 'jms-queue command_name --help'.

Dead Letter & Redelivery

Some of the settings are applied against an address wild card instead of a specific messaging destination. The dead letter queue and redelivery settings belong into this group: 

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <address-settings>
      <address-setting match="#">
         <dead-letter-address>jms.queue.DLQ</dead-letter-address>
         <expiry-address>jms.queue.ExpiryQueue</expiry-address>
         <redelivery-delay>0</redelivery-delay>
         [...]
      </address-setting>
   </address-settings>
   [...]
</subsystem>

(See standalone/configuration/standalone-full.xml)

Security Settings for HornetQ addresses and JMS destinations

Security constraints are matched against an address wildcard, similar to the DLQ and redelivery settings.  Note: Multiple roles are separated by spaces. 

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <security-settings>
      <security-setting match="#">
         <permission type="send" roles="guest"/>
         <permission type="consume" roles="guest"/>
         <permission type="createNonDurableQueue" roles="role1"/>
         <permission type="deleteNonDurableQueue" roles="role1 role2"/>
      </security-setting>
   </security-settings>
   [...]
</subsystem>

(See standalone/configuration/standalone-full.xml)

Security Domain for Users

By default, HornetQ will use the "other" JAAS security domain.  This domain is used to authenticate users making connections to HornetQ and then they are authorized to perform specific functions based on their role(s) and the security-settings described above.  This domain can be changed by using security-domain, e.g.: 

<subsystem xmlns="urn:jboss:domain:messaging:1.0">
   [...]
   <security-domain>mySecurityDomain</security-domain>
   [...]
</subsystem>

Deployment of -jms.xml files

Starting with JBoss Application Server 7.1.0.Final you have the ability to deploy a -jms.xml file defining JMS destinations, e.g.: 

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
   <hornetq-server>
      <jms-destinations>
         <jms-queue name="sample">
            <entry name="jms/queue/sample"/>
            <entry name="java:jboss/exported/jms/queue/sample"/>
         </jms-queue>
      </jms-destinations>
   </hornetq-server>
</messaging-deployment>

images/author/images/icons/emoticons/warning.gif

This feature is primarily intended for development as destinations deployed this way can not be managed with any of the provided management tools (e.g. console, CLI, etc).

JMS Bridge

The function of a JMS bridge is to consume messages from a source JMS destination, and send them to a target JMS destination. Typically either the source or the target destinations are on different servers.
The bridge can also be used to bridge messages from other non HornetQ JMS servers, as long as they are JMS 1.1 compliant.

The JMS Bridge is provided by the HornetQ project. Fo a detailed description of the available configuration properties, please consult the project documentation.

Modules for other messaging brokers

Source and target JMS resources (destination and connection factories) are looked up using JNDI.
If either the source or the target resources are managed by another messaging server than AS7, the required client classes must be bundled in a module. The name of the module must then be declared when the JMS Bridge is configured.

The use of a JMS bridges with any messaging provider will require to create a module containing the jar of this provider.

Let's suppose we want to use an hypothetical messaging provider named AcmeMQ. We want to bridge messages coming from a source AcmeMQ destination to a target destination on the local AS7 messaging server. To lookup AcmeMQ resources from JNDI, 2 jars are required, acmemq-1.2.3.jar, mylogapi-0.0.1.jar (please note these jars do not exist, this is just for the example purpose). We must not include a JMS jar since it will be provided by a AS7 module directly.

To use these resources in a JMS bridge, we must bundle them in a JBoss module:

in $JBOSS_HOME/modules, we create the layout: 

modules/
`-- org
    `-- acmemq
        `-- main
            |-- acmemq-1.2.3.jar
            |-- mylogapi-0.0.1.jar
            `-- module.xml

We define the module in module.xml: 

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="org.acmemq">
    <properties>
        <property name="jboss.api" value="private"/>
    </properties>


    <resources>
        <!-- insert resources required to connect to the source or target   -->
        <!-- messaging brokers if it not another AS7 instance               -->
        <resource-root path="acmemq-1.2.3.jar" />
        <resource-root path="mylogapi-0.0.1.jar" />
    </resources>


    <dependencies>
       <!-- add the dependencies required by JMS Bridge code                -->
       <module name="javax.api" />
       <module name="javax.jms.api" />
       <module name="javax.transaction.api"/>
       <module name="org.jboss.remote-naming"/>
       <!-- we depend on org.hornetq module since we will send messages to  -->
       <!-- the HornetQ server embedded in the local AS7 instance           -->
       <module name="org.hornetq" />
    </dependencies>
</module>

Configuration

A JMS bridge is defined inside a jms-bridge section of the `messaging` subsystem in the XML configuration files. 

<subsystem xmlns="urn:jboss:domain:messaging:1.3">
   <jms-bridge name="myBridge" module="org.acmemq">
      <source>
         <connection-factory name="ConnectionFactory"/>
         <destination name="sourceQ"/>
         <user>user1</user>
         <password>pwd1</password>
         <context>
            <property key="java.naming.factory.initial" value="org.acmemq.jndi.AcmeMQInitialContextFactory"/>
            <property key="java.naming.provider.url"    value="tcp://127.0.0.1:9292"/>
         </context>
      </source>
      <target>
         <connection-factory name="/jms/invmTargetCF"/>
         <destination name="/jms/targetQ"/>
      </target>
      <quality-of-service>AT_MOST_ONCE</quality-of-service>
      <failure-retry-interval>500</failure-retry-interval>
      <max-retries>1</max-retries>
      <max-batch-size>500</max-batch-size>
      <max-batch-time>500</max-batch-time>
      <add-messageID-in-header>true</add-messageID-in-header>
   </jms-bridge>
</subsystem>

The source and target sections contain the name of the JMS resource (connection-factory and destination) that will be looked up in JNDI.
It optionally defines the user and password credentials. If they are set, they will be passed as arguments when creating the JMS connection from the looked up ConnectionFactory.
It is also possible to define JNDI context properties in the context section. If the context section is absent, the JMS resources will be looked up in the local AS7 instance (as it is the case in the target section in the example above).

Management commands

A JMS Bridge can also be managed using the JBoss command line interface: 

[standalone@localhost:9999 /] /subsystem=messaging/jms-bridge=myBridge/:add(module="org.acmemq",      \
      source-destination="sourceQ",                                                                   \
      source-connection-factory="ConnectionFactory",                                                  \
      source-user="user1",                                                                            \
      source-password="pwd1",                                                                         \
      source-context={"java.naming.factory.initial" => "org.acmemq.jndi.AcmeMQInitialContextFactory", \
                      "java.naming.provider.url" => "tcp://127.0.0.1:9292"},                          \
      target-destination="/jms/targetQ",                                                              \
      target-connection-factory="/jms/invmTargetCF",                                                  \
      quality-of-service=AT_MOST_ONCE,                                                                \
      failure-retry-interval=500,                                                                     \
      max-retries=1,                                                                                  \
      max-batch-size=500,                                                                             \
      max-batch-time=500,                                                                             \
      add-messageID-in-header=true)
{"outcome" => "success"}

You can also see the complete JMS Bridge resource description from the CLI: 

[standalone@localhost:9999 /] /subsystem=messaging/jms-bridge=*/:read-resource-description
{
    "outcome" => "success",
    "result" => [{
        "address" => [
            ("subsystem" => "messaging"),
            ("jms-bridge" => "*")
        ],
        "outcome" => "success",
        "result" => {
            "description" => "A JMS bridge instance.",
            "attributes" => {
                ...
        }
    }]
}

Component Reference

The messaging subsystem is provided by the HornetQ project. Fo a detailed description of the available configuration properties, please consult the project documentation.

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 13:27:36 UTC, last content change 2014-06-13 14:16:36 UTC.