JBoss.orgCommunity Documentation

Chapter 6. Using the Server

6.1. Starting and Stopping the standalone server
6.2. Server JVM settings
6.3. Server classpath
6.4. Library Path
6.5. System properties
6.6. Configuration files
6.7. JBoss Microcontainer Beans File
6.8. JBoss AS4 MBean Service.
6.9. The main configuration file.

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.

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 stop.bat

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

To run on Windows type stop.bat

Please note that HornetQ requires a Java 6 or later runtime to run.

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.

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.

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:

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.

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.

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

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

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

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.core.remoting.impl.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.

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:

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

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.