JBoss.orgCommunity Documentation
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:
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.
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.
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 48, 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.
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.
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
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.
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
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.