Skip to end of metadata
Go to start of metadata

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.

To be clear, the inbound adapter of the HornetQ JCA RA (which is for consuming messages) is only used by MDBs and is not available to other kinds of 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 outbound-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).

  • 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.  
  • 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.

(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":

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

JMS endpoints can easily be created through the CLI:

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

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:

(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.

(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.:

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.:

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

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.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jul 19, 2012

    That's very useful information. I had a hard time 'guessing' the correct JNDI names for CFs and Queues until I read this.


    1. Nov 28, 2014

      If I understand correctly, in the above example I should be able to get a connection factory via

      However, trying this on an AS 7.1.1.Final test instance I keep getting a NoInitialContextException, triggered because invoking lookup on the context results in an attempt to construct another InitialContext (possibly a naming subdirectory?), via a call stack of javax.naming.InitialContext.getURLOrDefaultInitCtx, javax.naming.InitialContext.getDefaultInitCtx and finally javax.naming.spi.NamingManager.getInitialContext where the exception occurs.

      I currently suspect that something is missing from / wrong with my, they currently just contain

      I'm running this as a standalone app (launched via java -jar).

      Am I wrong to assume that "java:jboss/exported/jms/RemoteConnectionFactory" is the canonical JNDI name for looking up the ConnectionFactory that should always work?

      1. Nov 28, 2014

        try lookup like this:ConnectionFactory connectionFactory = (ConnectionFactory) context.lookup("jms/RemoteConnectionFactory");

  2. Mar 06, 2013

    The CLI command above is broken, try this instead (I am using jboss-as-7.1.2.Final):

    jms-queue add --queue-address=MyQueueName --entries=[jms/queue/MyQueueName] --durable=true

    jms-queue add-jndi --queue-address=MyQueueName --jndi-binding=java:jboss/exported/jms/queue/MyQueueName

  3. May 20, 2014

    Nice article. The best article found so far for configuring Jboss AS 7.1.

  4. Nov 02, 2014

    I find in several pages how to send a message from a plain Java client (using jboss-client.jar), but I can't find the right way of accessing from one JBoss AS to a queue hosted in another JBoss AS, either to produce or consume (MDB).

    1. Nov 03, 2014

      Jorge, you should move your question to the Wildfly user forum.

  5. Nov 14, 2014

    Thank you, very useful. Does this mean that you can't possibly have a standalone HornetQ server without an embedded one, even if the latter is doing no work, but has to be there in order to setup the connector?