This chapter will familiarise you with how to use the JBoss Messaging 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 JBoss Messaging server we mean the JBoss Messaging 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 JBoss Messaging 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 JBoss Messaging requires a Java 5 or later JDK 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.
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 minimises large GC pauses.
By default JBoss Messaging runs in a maximum of 1GB 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.
JBoss Messaging 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 JBoss Messaging 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 JBoss Messaging 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.
JBoss Messaging also takes a couple of Java system properties on the command line for configuring logging properties
JBoss Messaging uses JDK logging to minimise dependencies on other logging systems. JDK logging can then be configured to delegate to some other framework, e.g. log4j if that's what you prefer.
For more information on configuring logging, please see Chapter 40, 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.
jbm-jboss-beans.xml. This is the JBoss Microcontainer beans file which defines what beans the Microcontainer should create and what dependencies to enforce between them. Remember that JBoss Messaging 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. Please see Section 4.8, “The main configuration file.” for more information on this file.
jbm-configuration.xml. This is the main JBoss Messaging configuration file. All the parameters in this file are described in Chapter 45, Configuration Reference.
jbm-queues.xml. This file contains predefined queues, queue settings and security settings. The file is optional - all this configuration can also live in jbm-configuration.xml. In fact, the default configuration sets do not have a jbm.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 jbm-queues.xml files on the classpath. All will be loaded if found.
jbm-users.xml JBoss Messaging ships with a security manager implementation which obtains user credentials from the jbm-users.xml file. This file contains user, password and role information. For more information on security ,please see Chapter 30, Security.
jbm-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 5, 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 40, Logging.
log4j.xml This is the Log4j configuration if the Log4j handler is configured.
The property file-deployment-enabled in the jbm-configuration.xml configuration when set to false mans 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.jboss.messaging.integration.transports.netty.NettyConnectorFactory</factory-class>
<param key="jbm.remoting.netty.host" value="${jbm.remoting.netty.host:localhost}" type="String"/>
<param key="jbm.remoting.netty.port" value="${jbm.remoting.netty.port:5445}" type="Integer"/>
</connector>here you can see we have replaced 2 values with system properties jbm.remoting.netty.host and jbm.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. ${jbm.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.jboss.messaging.core.config.impl.FileConfiguration">
</bean>
<!-- The security manager -->
<bean name="JBMSecurityManager"
class="org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl">
<start ignored="true"/>
<stop ignored="true"/>
</bean>
<!-- The core server -->
<bean name="MessagingServer" class="org.jboss.messaging.core.server.impl.MessagingServerImpl">
<start ignored="true"/>
<stop ignored="true"/>
<constructor>
<parameter>
<inject bean="Configuration"/>
</parameter>
<parameter>
<inject bean="MBeanServer"/>
</parameter>
<parameter>
<inject bean="JBMSecurityManager"/>
</parameter>
</constructor>
</bean>
<!-- The JMS server -->
<bean name="JMSServerManager"
class="org.jboss.messaging.jms.server.impl.JMSServerManagerImpl">
<constructor>
<parameter>
<inject bean="MessagingServer"/>
</parameter>
</constructor>
</bean>
</deployment>
We can see that, as well as the core JBoss Messaging 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 messaging 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 jbm-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.
MessagingServer
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 jbm-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 configuration for the JBoss Messaging core server is contained in jbm-configuration.xml. This is what the FileConfiguration bean uses to configure the messaging server.
There are many attributes which you can configure JBoss Messaging. 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.