Chapter 6. Using the Server

This chapter will familiarise you with how to use the HornetQ server.

We'll show where it is, how to start and stop it, and we'll describe the directory layout and what all the files are and what they do.

For the remainder of this chapter when we talk about the HornetQ server we mean the HornetQ standalone server, in its default configuration with a JMS Service and JNDI service enabled.

When running embedded in JBoss Application Server the layout may be slightly different but by-and-large will be the same.

6.1. Starting and Stopping the standalone server

In the distribution you will find a directory called bin.

cd into that directory and you'll find a unix/linux script called run.sh and a windows batch file called run.bat

To run on Unix/Linux type ./run.sh

To run on Windows type run.bat

These scripts are very simple and basically just set-up the classpath and some JVM parameters and start the JBoss Microcontainer. The Microcontainer is a light weight container used to deploy the HornetQ POJO's

To stop the server you'll also find a unix/linux script stop.sh and a windows batch file run.bat

To run on Unix/Linux type ./stop.sh

To run on Windows type stop.bat

Please note that HornetQ requires a Java 5 or later runtime to run. We recommend running on Java 6.

Both the run and the stop scripts use the config under config/stand-alone/non-clustered by default. The configuration can be changed by running ./run.sh ../config/stand-alone/clustered or another config of your choosing. This is the same for the stop script and the windows bat files.

6.2. Server JVM settings

The run scripts run.sh and run.bat set some JVM settings for tuning running on Java 6 and choosing the garbage collection policy. We recommend using a parallel garbage collection algorithm to smooth out latency and minimise large GC pauses.

By default HornetQ runs in a maximum of 1GiB of RAM. To increase the memory settings change the -Xms and -Xmx memory settings as you would for any Java program.

If you wish to add any more JVM arguments or tune the existing ones, the run scripts are the place to do it.

6.3. Server classpath

HornetQ looks for its configuration files on the Java classpath.

The scripts run.sh and run.bat specify the classpath when calling Java to run the server.

In the distribution, the run scripts will add the non clustered configuration directory to the classpath. This is a directory which contains a set of configuration files for running the HornetQ server in a basic non-clustered configuration. In the distribution this directory is config/stand-alone/non-clustered/ from the root of the distribution.

The distribution contains several standard configuration sets for running:

  • Non clustered stand-alone.

  • Clustered stand-alone

  • Non clustered in JBoss Application Server

  • Clustered in JBoss Application Server

You can of course create your own configuration and specify any configuration directory when running the run script.

Just make sure the directory is on the classpath and HornetQ will search there when starting up.

6.4. Library Path

If you're using the Asynchronous IO Journal on Linux, you need to specify java.library.path as a property on your Java options. This is done automatically in the run.sh script.

If you don't specify java.library.path at your Java options then the JVM will use the environment variable LD_LIBRARY_PATH.

6.5. System properties

HornetQ can take a system property on the command line for configuring logging.

For more information on configuring logging, please see Chapter 42, Logging.

6.6. Configuration files

The configuration directory is specified on the classpath in the run scripts run.sh and run.bat This directory can contain the following files.

  • hornetq-beans.xml (or hornetq-jboss-beans.xml if you're running inside JBoss Application Server). This is the JBoss Microcontainer beans file which defines what beans the Microcontainer should create and what dependencies to enforce between them. Remember that HornetQ is just a set of POJOs. In the stand-alone server, it's the JBoss Microcontainer which instantiates these POJOs and enforces dependencies between them and other beans.

  • hornetq-configuration.xml. This is the main HornetQ configuration file. All the parameters in this file are described in Chapter 47, Configuration Reference. Please see Section 6.9, “The main configuration file.” for more information on this file.

  • hornetq-queues.xml. This file contains predefined queues, queue settings and security settings. The file is optional - all this configuration can also live in hornetq-configuration.xml. In fact, the default configuration sets do not have a hornetq-queues.xml file. The purpose of allowing queues to be configured in these files is to allow you to manage your queue configuration over many files instead of being forced to maintain it in a single file. There can be many hornetq-queues.xml files on the classpath. All will be loaded if found.

  • hornetq-users.xml HornetQ ships with a basic security manager implementation which obtains user credentials from the hornetq-users.xml file. This file contains user, password and role information. For more information on security ,please see Chapter 31, Security.

  • hornetq-jms.xml The distro configuration by default includes a server side JMS service which mainly deploys JMS Queues, Topics and ConnectionFactorys from this file into JNDI. If you're not using JMS, or you don't need to deploy JMS objects on the server side, then you don't need this file. For more information on using JMS, please see Chapter 7, Using JMS.

  • logging.properties This is used to configure the logging handlers used by the Java logger. For more information on configuring logging, please see Chapter 42, Logging.

  • log4j.xml This is the Log4j configuration if the Log4j handler is configured.

Note

The property file-deployment-enabled in the hornetq-configuration.xml configuration when set to false means that the other configuration files are not loaded. This is true by default.

It is also possible to use system property substitution in all the configuration files. by replacing a value with the name of a system property. Here is an example of this with a connector configuration:

<connector name="netty">
         <factory-class>org.hornetq.integration.transports.netty.NettyConnectorFactory
           </factory-class>
         <param key="host"  value="${hornetq.remoting.netty.host:localhost}" type="String"/>
         <param key="port"  value="${hornetq.remoting.netty.port:5445}" type="Integer"/>
</connector>

Here you can see we have replaced 2 values with system properties hornetq.remoting.netty.host and hornetq.remoting.netty.port. These values will be replaced by the value found in the system property if there is one, if not they default back to localhost or 5445 respectively. It is also possible to not supply a default. i.e. ${hornetq.remoting.netty.host}, however the system property must be supplied in that case.

6.7. JBoss Microcontainer Beans File

The stand-alone server is basically a set of POJOs which are instantiated by the light weight JBoss Microcontainer engine.

Note

A beans file is also needed when the server is deployed in the JBoss Application Server but this will deploy a slightly different set of objects since the Application Server will already have things like security etc deployed.

Let's take a look at an example beans file from the stand-alone server:

<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns="urn:jboss:bean-deployer:2.0">

<bean name="Naming" class="org.jnp.server.NamingBeanImpl"/>

<!-- JNDI server. Disable this if you don't want JNDI -->
<bean name="JNDIServer" class="org.jnp.server.Main">
   <property name="namingInfo">
      <inject bean="Naming"/>
   </property>
   <property name="port">1099</property>
   <property name="bindAddress">localhost</property>
   <property name="rmiPort">1098</property>
   <property name="rmiBindAddress">localhost</property>
</bean>

<!-- MBean server -->
<bean name="MBeanServer" class="javax.management.MBeanServer">
   <constructor factoryClass="java.lang.management.ManagementFactory"
      factoryMethod="getPlatformMBeanServer"/>
</bean> 

<!-- The core configuration -->
<bean name="Configuration" class="org.hornetq.core.config.impl.FileConfiguration">
</bean>

<!-- The security manager -->
<bean name="HornetQSecurityManager" 
      class="org.hornetq.spi.core.security.HornetQSecurityManagerImpl">
   <start ignored="true"/>
   <stop ignored="true"/>
</bean>

<!-- The core server -->
<bean name="HornetQServer" class="org.hornetq.core.server.impl.HornetQServerImpl">
   <start ignored="true"/>
   <stop ignored="true"/>  
   <constructor>
      <parameter>
         <inject bean="Configuration"/>
      </parameter>
      <parameter>
         <inject bean="MBeanServer"/>
      </parameter>
      <parameter>
         <inject bean="HornetQSecurityManager"/>
      </parameter>        
   </constructor>         
</bean>

<!-- The JMS server -->
<bean name="JMSServerManager" 
      class="org.hornetq.jms.server.impl.JMSServerManagerImpl">
   <constructor>         
      <parameter>
         <inject bean="HornetQServer"/>
      </parameter>         
   </constructor>
</bean>

</deployment>

We can see that, as well as the core HornetQ server, the stand-alone server instantiates various different POJOs, lets look at them in turn:

  • JNDIServer

    Many clients like to look up JMS Objects from JNDI so we provide a JNDI server for them to do that. If you don't need JNDI this can be commented out or removed.

  • MBeanServer

    In order to provide a JMX management interface a JMS MBean server is necessary in which to register the management objects. Normally this is just the default platform MBean server available in the JVM instance. If you don't want to provide a JMX management interface this can be commented out or removed.

  • Configuration

    The HornetQ server is configured with a Configuration object. In the default stand-alone set-up it uses a FileConfiguration object which knows to read configuration information from the file system. In different configurations such as embedded you might want to provide configuration information from somewhere else.

  • Security Manager. The security manager used by the messaging server is pluggable. The default one used just reads user-role information from the hornetq-users.xml file on disk. However it can be replaced by a JAAS security manager, or when running inside JBoss Application Server it can be configured to use the JBoss AS security manager for tight integration with JBoss AS security. If you've disabled security altogether you can remove this too.

  • HornetQServer

    This is the core server. It's where 99% of the magic happens

  • JMSServerManager

    This deploys any JMS Objects such as JMS Queues, Topics and ConnectionFactory instances from hornetq-jms.xml files on the disk. It also provides a simple management API for manipulating JMS Objects. On the whole it just translates and delegates its work to the core server. If you don't need to deploy JMS Queues, Topics and ConnectionFactorys from server side configuration and don't require the JMS management interface this can be disabled.

6.8. JBoss AS4 MBean Service.

Note

The section is only to configure HornetQ on JBoss AS4. The service funtionality is similar to Microcontainer Beans

<?xml version="1.0" encoding="UTF-8"?>
<server>

   <mbean code="org.hornetq.service.HornetQFileConfigurationService"
      name="org.hornetq:service=HornetQFileConfigurationService">
   </mbean>

   <mbean code="org.hornetq.service.JBossASSecurityManagerService"
      name="org.hornetq:service=JBossASSecurityManagerService">
   </mbean>

   <mbean code="org.hornetq.service.HornetQStarterService" 
      name="org.hornetq:service=HornetQStarterService">
      <!--lets let the JMS Server start us-->
         <attribute name="Start">false</attribute>

      <depends optional-attribute-name="SecurityManagerService"
         proxy-type="attribute">org.hornetq:service=JBossASSecurityManagerService</depends>
      <depends optional-attribute-name="ConfigurationService"
         proxy-type="attribute">org.hornetq:service=HornetQFileConfigurationService</depends>
   </mbean>

   <mbean code="org.hornetq.service.HornetQJMSStarterService"
      name="org.hornetq:service=HornetQJMSStarterService">
      <depends optional-attribute-name="HornetQServer"
         proxy-type="attribute">org.hornetq:service=HornetQStarterService</depends>
   </mbean>
   
</server>
            

This jboss-service.xml configuration file is included inside the hornetq-service.sar on AS4 with embebbed HornetQ. As you can see, on this configuration file we are starting various services:

  • HornetQFileConfigurationService

    This is an MBean Service that takes care of the life cycle of the FileConfiguration POJO

  • JBossASSecurityManagerService

    This is an MBean Service that takes care of the lifecycle of the JBossASSecurityManager POJO

  • HornetQStarterService

    This is an MBean Service that controls the main HornetQServer POJO. this has a dependency on JBossASSecurityManagerService and HornetQFileConfigurationService MBeans

  • HornetQJMSStarterService

    This is an MBean Service that controls the JMSServerManagerImpl POJO. If you aren't using jms this can be removed.

  • JMSServerManager

    Has the responsibility to start the JMSServerManager and the same behaviour that JMSServerManager Bean

6.9. The main configuration file.

The configuration for the HornetQ core server is contained in hornetq-configuration.xml. This is what the FileConfiguration bean uses to configure the messaging server.

There are many attributes which you can configure HornetQ. In most cases the defaults will do fine, in fact every attribute can be defaulted which means a file with a single empty configuration element is a valid configuration file. The different configuration will be explained throughout the manual or you can refer to the configuration reference here.