20.8. Configuration

20.8.1. Configure the JMS Server

To configure the JMS Server for HornetQ, edit the server configuration file. The server configuration is contained in the EAP_HOME/domain/configuration/domain.xml file for domain servers, or in the EAP_HOME/standalone/configuration/standalone-full.xml file for standalone servers.
The <subsystem xmlns="urn:jboss:domain:messaging:1.4"> element in the server configuration file contains all JMS configuration. Add any JMS ConnectionFactory, Queue, or Topic instances required for the JNDI.
  1. Enable the JMS subsystem in JBoss EAP 6.

    Within the <extensions> element, verify that the following line is present and is not commented out:
    <extension module="org.jboss.as.messaging"/>
  2. Add the basic JMS subsystem.

    If the Messaging subsystem is not present in your configuration file, add it.
    1. Look for the <profile> which corresponds to the profile you use, and locate its <subsystems> tag.
    2. Paste the following XML immediately following the <profile> tag.
      <subsystem xmlns="urn:jboss:domain:messaging:1.4">
          <hornetq-server>
          <!-- ALL XML CONFIGURATION IS ADDED HERE -->
          </hornetq-server>
      </subsystem>
      All further configuration will be added to the empty line above.
  3. Add basic configuration for JMS.

    Add the following XML in the blank line after the <subsystem xmlns="urn:jboss:domain:messaging:1.4"><hornetq-server> tag:
    <journal-min-files>2</journal-min-files>
    <journal-type>NIO</journal-type>
    <persistence-enabled>true</persistence-enabled>
    Customize the values above to meet your needs.

    Warning

    The value of journal-file-size must be higher than or equal to min-large-message-size (100KiB by default), or the server won't be able to store the message.
  4. Add connection factory instances to HornetQ

    The client uses a JMS ConnectionFactory object to make connections to the server. To add a JMS connection factory object to HornetQ, include a single <jms-connection-factories> tag and <connection-factory> element for each connection factory as follows:
      <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>
    
  5. Configure the netty connectors and acceptors

    This JMS connection factory uses netty acceptors and connectors. These are references to connector and acceptor objects deployed in the server configuration file. The connector object defines the transport and parameters used to connect to the HornetQ server. The acceptor object identifies the type of connections accepted by the HornetQ server.
    To configure the netty connectors, include the following settings:
    <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>
    
    To configure the netty acceptors, include the following settings:
    <acceptors>
        <netty-acceptor name="netty" socket-binding="messaging"/>
        <netty-acceptor name="netty-throughput" socket-binding="messaging-throughput">
            <param key="batch-delay" value="50"/>
            <param key="direct-deliver" value="false"/>
        </netty-acceptor>
        <in-vm-acceptor name="in-vm" server-id="0"/>
    </acceptors>
    
  6. Review the configuration

    If you have followed the previous steps, your messaging subsystem should look like the following:
    <subsystem xmlns="urn:jboss:domain:messaging:1.4">
        <hornetq-server>
            <journal-min-files>2</journal-min-files>
            <journal-type>NIO</journal-type>
            <persistence-enabled>true</persistence-enabled>
            <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>
            <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>	
            <acceptors>
                <netty-acceptor name="netty" socket-binding="messaging"/>
                <netty-acceptor name="netty-throughput" socket-binding="messaging-throughput">
                    <param key="batch-delay" value="50"/>
                    <param key="direct-deliver" value="false"/>
                </netty-acceptor>
                <in-vm-acceptor name="in-vm" server-id="0"/>
            </acceptors>
        </hornetq-server>
    </subsystem>
    
  7. Configure the socket binding groups

    The netty connectors reference the messaging and messaging-throughput socket bindings. The messaging socket binding uses port 5445, and the messaging-throughput socket binding uses port 5455. The <socket-binding-group> tag is in a separate section of the server configuration file. Ensure the following socket bindings are present in 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="messaging" port="5445"/>
        <socket-binding name="messaging-throughput" port="5455"/>
        ...
      </socket-binding-group>
    
  8. Add queue instances to HornetQ

    There are 4 ways to setup the queue instances (or JMS destinations) for HornetQ.
    • Use the Management Console
      To use the Management Console, the server must have been started in the Message-Enabled mode. You can do this by using the -c option and forcing the use of the standalone-full.xml (for standalone servers) configuration file. For example, in the standalone mode, the following will start the server in a message enabled mode
      ./standalone.sh -c standalone-full.xml
      Once the server has started, logon to the Management Console and select the Configuration tab. Expand the Subsystems menu, then expand the Messaging menu and click Destinations. Next to Default on the JMS Messaging Provider table, click View, and then click Add to enter details of the JMS destination.
    • Use the Management CLI:
      First, connect to the Management CLI:
       bin/jboss-cli.sh --connect
      Next, change into the messaging subsystem:
      cd /subsystem=messaging/hornetq-server=default
      Finally, execute an add operation, replacing the examples values given below with your own:
      ./jms-queue=testQueue:add(durable=false,entries=["java:jboss/exported/jms/queue/test"])
    • Create a JMS configuration file and add it to the deployments folder
      Start by creating a JMS configuration file: example-jms.xml. Add the following entries to it, replacing the values with your own:
      <?xml version="1.0" encoding="UTF-8"?>				  	  <messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
          <hornetq-server>
              <jms-destinations>
                  <jms-queue name="testQueue">
                      <entry name="queue/test"/>
                      <entry name="java:jboss/exported/jms/queue/test"/>
                  </jms-queue>
                  <jms-topic name="testTopic">
                      <entry name="topic/test"/>
                      <entry name="java:jboss/exported/jms/topic/test"/>
                  </jms-topic>
              </jms-destinations>
          </hornetq-server>
      </messaging-deployment>
      Save this file in the deployments folder and do a deployment.
    • Add entries in the JBoss EAP 6 configuration file.
      Using the standalone-full.xml as an example, find the messaging subsystem in this file.
      <subsystem xmlns="urn:jboss:domain:messaging:1.4">
      Add the following entries in it, again, replacing the example values with your own. You will need to add these entries in after the </jms-connection-factories> end tag but before the </hornetq-server> element:
      <jms-destinations>
              <jms-queue name="testQueue">
                  <entry name="queue/test"/>
                  <entry name="java:jboss/exported/jms/queue/test"/>
              </jms-queue>
              <jms-topic name="testTopic">
                  <entry name="topic/test"/>
                  <entry name="java:jboss/exported/jms/topic/test"/>
              </jms-topic>
      </jms-destinations>
  9. Perform additional configuration

    If you need additional settings, review the DTD in EAP_HOME/docs/schema/jboss-as-messaging_1_4.xsd.