In this chapter, we discuss how to configure JBoss Messaging
JBoss Messaging configuration is spread among several configuration files:
The next sections explain each configuration file in detail.
This configuration file is the core configuration for the JBM server. The following is an example of a typical configuration:
<deployment>
<configuration>
<clustered>false</clustered>
<scheduled-executor-max-pool-size>30</scheduled-executor-max-pool-size>
<require-destinations>true</require-destinations>
<!-- Remoting configuration -->
<!-- one of: TCP, INVM -->
<!-- INVM: the server is accessible only by clients in the same VM
(no sockets are opened) -->
<remoting-transport>TCP</remoting-transport>
<remoting-bind-address>5400</remoting-bind-address>
<remoting-host>localhost</remoting-host>
<!-- timeout in milliseconds -->
<remoting-timeout>5000</remoting-timeout>
<!-- true to disable invm communication when the client and the server are in the
same JVM. -->
<!-- it is not allowed to disable invm communication when the remoting-transport
is set to INVM -->
<remoting-disable-invm>false</remoting-disable-invm>
<!-- Enable/Disable Nagle's Algorithm (resp. true/false) -->
<!-- This setting is taken into account only when remoting-transport is set to
TCP -->
<remoting-tcp-nodelay>false</remoting-tcp-nodelay>
<!-- Set the TCP Receive Buffer size (SO_RCVBUF). -->
<!-- Set it to -1 if you want to use the value hinted by the Operating System -->
<!-- This setting is taken into account only when remoting-transport is set to
TCP -->
<remoting-tcp-receive-buffer-size>-1</remoting-tcp-receive-buffer-size>
<!-- Set the TCP Send Buffer size (SO_SNDBUF).-->
<!-- Set it to -1 if you want to use the value hinted by the Operating System-->
<!-- This setting is taken into account only when remoting-transport is set to
TCP -->
<remoting-tcp-send-buffer-size>-1</remoting-tcp-send-buffer-size>
<!-- The interval to send a ping message to send to the client/server to make sure
it is still alive.-->
<!-- Set to 0 if you want to disable this functionality-->
<remoting-keep-alive-interval>10000</remoting-keep-alive-interval>
<!--How long to wait for a returning pong after sending a ping message to a
client/server.-->
<!-- If no pong is received after this time resources are cleaned up-->
<remoting-keep-alive-timeout>5000</remoting-keep-alive-timeout>
<!-- if ssl is enabled, all remoting-ssl-* properties must be set -->
<remoting-enable-ssl>false</remoting-enable-ssl>
<remoting-ssl-keystore-path>messaging.keystore</remoting-ssl-keystore-path>
<remoting-ssl-keystore-password>secureexample</remoting-ssl-keystore-password>
<remoting-ssl-truststore-path>messaging.truststore</remoting-ssl-truststore-path>
<remoting-ssl-truststore-password>secureexample</remoting-ssl-truststore-password>
<!-- Storage configuration -->
<bindings-directory>${user.home}/jbm-test/data/bindings</bindings-directory>
<create-bindings-dir>true</create-bindings-dir>
<journal-directory>${user.home}/jbm-test/data/journal</journal-directory>
<create-journal-dir>true</create-journal-dir>
<journal-type>asyncio</journal-type>
<!-- Does the journal sync to disk on each transaction commit,
prepare or rollback? -->
<journal-sync-transactional>true</journal-sync-transactional>
<!-- Does the journal sync to disk for every non transactional
persistent operation? -->
<journal-sync-non-transactional>false</journal-sync-non-transactional>
<journal-file-size>10485760</journal-file-size>
<journal-min-files>10</journal-min-files>
<!-- Maximum simultaneous asynchronous writes accepted by the native layer.
(parameter ignored on NIO) -->
<journal-max-aio>9000</journal-max-aio>
<!-- Maximum time in milliseconds an AIO operation could take.
This includes:
- closing Asynchronous files
- Transaction awaits
- Awaits on non transactional writes
-->
<journal-aio-timeout>90000</journal-aio-timeout>
<journal-task-period>5000</journal-task-period>
<security-enabled>true</security-enabled>
</configuration>
</deployment>
The available configuration attributes are:
scheduled-executor-max-pool-size
The maximum number of threads available for scheduling delivery of scheduled messages
require-destinations
Whether or not a destination needs to pre-exist when delivering a message
remoting-transport
Type of transport to use, currently there is only TCP
remoting-bind-address
The port that JBM will bind to.
remoting-host
The name of the host that JBM will bind to
remoting-timeout
The timeout setting, in milliseconds, for both client and server connections
remoting-disable-invm
not used at present
remoting-tcp-nodelay
Sets the TCP nodelay setting when a TCP transport is used
remoting-tcp-receive-buffer-size
sets the TCP receive buffer size, -1 will set it to the value that the OS hints at to use. This is only used when TCP transport is configured
remoting-tcp-send-buffer-size
sets the TCP send buffer size, -1 will set it to the value that the OS hints at to use. This is only used when TCP transport is configured
remoting-keep-alive-interval
The interval, in milliseconds, at which a ping message will be sent to the client/server to make sure it is still alive. Setting to 0 will disable pinging
remoting-keep-alive-timeout
The time, in milliseconds, to wait for a pong after a ping has ben sent to a client/server. If the pong isn't received after this timeout then the resources are cleaned up.
remoting-enable-ssl
Whether SSL is enabled for this server. If this is true then next 4 SSL properties need to be set
remoting-ssl-keystore-path>messaging.keystore
The location of the SSL keystore
remoting-ssl-keystore-password
The password for the SSL keystore
remoting-ssl-truststore-path
The location of the SSL truststore
remoting-ssl-truststore-password
The password for the truststore
bindings-directory
The directory to create the bindings persistence files in.
create-bindings-dir
Whether to create the bindings directory if it doesnt exist.
journal-type
The type of journal to use, valid configurations are 'asyncio','nio' and 'jdbc'. refere to the 'The journal based persistence approach' chapter for more detailed information
journal-sync-transactional
Whether or not to synch to disk for a transaction on commit, prepare or rollback. false will only write to the OS buffers and lets the OS deal with synching
journal-sync-non-transactional
Whether or not to synch to disk for every non transaction persistent operation. false will only write to the OS buffers and lets the OS deal with synching
journal-file-size
The size of the data file to create, these files are pre-allocated and filled as needed.
journal-min-files
Minimum number of created files to start with
journal-max-aio
Maximum pending asynchronous writes accepted by the native layer per opened file. There is a limit and the total max AIO can't be higher than /proc/sys/fs/aio-max-nr. If you are combining the usage of JBoss Messaging with other systems that are using libaio (e.g. Oracle) you might need to increase this value on the OS. This parameter is only available on AIO which is only available on Linux at the moment.
journal-aio-timeout
Maximum amount of time any asynchronous operation can take in milliseconds. If any operation takes more than this amount a timeout exception will be logged. This parameter is only available on AIO which is only available on Linux.
journal-task-period
How frequently to reclaim unused journal data files, in milliseconds.
security-enabled
Whether security is enabled, if false no security checks are made.
This configuration file is used to configure users and roles when JBM is running in standalone mode using the JBM Security Manager. The Security manager used is a pluggable component whose implementation can be changed by configuring the appropriate beans configuration file. Refer to the beans configuration section on how to do this. A typical jbm-security.xml config looks like:
<deployment>
<user name="guest" password="guest">
<role name="guest"/>
</user>
</deployment>
The available configuration attributes are:
user
The user to add to the security manager. This must have the attribute 'name' and 'password' set.
role
A role that the user has, a user may have multiple roles configured.
This configuration file is used to configure the security and settings for destinations. These are matched against a destination using an hierarchical style match that supports both wild cards ('*') and word replacement ('^')
For instance a destination withname 'queuejms.aqueue.myQueue' would match against 'queuejms.*', 'queuejms.aqueue.^', 'queuejms.^.myQueue' and obviously 'queuejms.aqueue.myQueue'. If a destination has multiple matches then the most precise match is used
<deployment>
<security match="topicjms.testTopic">
<permission type="create" roles="durpublisher"/>
<permission type="read" roles="guest,publisher,durpublisher"/>
<permission type="write" roles="guest,publisher,durpublisher"/>
</security>
<security match="topicjms.securedTopic">
<permission type="write" roles="publisher"/>
<permission type="read" roles="publisher"/>
</security>
<security match="topicjms.testDurableTopic">
<permission type="create" roles="durpublisher"/>
<permission type="read" roles="guest,publisher,durpublisher"/>
<permission type="write" roles="guest,publisher,durpublisher"/>
</security>
<security match="queuejms.testQueue">
<permission type="read" roles="guest,publisher"/>
<permission type="write" roles="guest,publisher"/>
</security>
<security match="queuejms.NoSuchQueue">
<permission type="read" roles="guest,publisher"/>
<permission type="write" roles="guest,publisher"/>
</security>
<security match="topicjms.NoSuchTopic">
<permission type="read" roles="guest,publisher"/>
<permission type="write" roles="guest,publisher"/>
</security>
<security match="queuetempjms.*">
<permission type="create" roles="guest,def"/>
<permission type="read" roles="guest,def"/>
<permission type="write" roles="guest,def"/>
</security>
<security match="topictempjms.*">
<permission type="create" roles="guest,def"/>
<permission type="read" roles="guest,def"/>
<permission type="write" roles="guest,def"/>
</security>
<!--this will catch any word i.e. queuejms.anything-->
<!--<security match="queuejms.^">
<permission type="read" roles="guest,publisher"/>
<permission type="write" roles="guest,publisher"/>
</security>-->
<!--this will catch any word i.e. queuejms.anything-->
<!--<security match="topicjms.^">
<permission type="read" roles="guest,publisher"/>
<permission type="write" roles="guest,publisher"/>
</security>-->
<!--default security to catch all-->
<security match="*">
<permission type="create" roles="guest,def"/>
<permission type="read" roles="guest,def"/>
<permission type="write" roles="guest,def"/>
</security>
<queue-settings match="queuejms.QueueWithOwnDLQAndExpiryQueue">
<dlq>PrivateDLQ</dlq>
<expiry-queue>queuejms.PrivateExpiryQueue</expiry-queue>
</queue-settings>
<queue-settings match="topicjms.TopicWithOwnDLQAndExpiryQueue">
<dlq>PrivateDLQ</dlq>
<expiry-queue>queuejms.PrivateExpiryQueue</expiry-queue>
</queue-settings>
<queue-settings match="queuejms.QueueWithOwnRedeliveryDelay">
<redelivery-delay>5000</redelivery-delay>
</queue-settings>
<queue-settings match="topicjms.TopicWithOwnRedeliveryDelay">
<redelivery-delay>5000</redelivery-delay>
</queue-settings>
<queue-settings match="queuejms.testDistributedQueue">
<clustered>true</clustered>
</queue-settings>
<queue-settings match="topicjms.testDistributedTopic">
<clustered>true</clustered>
</queue-settings>
<queue-settings match="queuejms.testPerfQueue">
<clustered>false</clustered>
</queue-settings>
<!--default for catch all-->
<queue-settings match="*">
<clustered>false</clustered>
<dlq>DLQ</dlq>
<expiry-queue>queuejms.ExpiryQueue</expiry-queue>
<redelivery-delay>0</redelivery-delay>
<max-size>-1</max-size>
<distribution-policy-class>
org.jboss.messaging.core.server.impl.RoundRobinDistributionPolicy
</distribution-policy-class>
<message-counter-history-day-limit>10</message-counter-history-day-limit>
</queue-settings>
</deployment>
The available configuration attributes are:
security
The securitysettings to use when clients access a destination.
permission
This describes the permissions a user must have to perform certain tasks. The permission type can be 'create','write' or 'read' and the roles are a comma seperated list of roles.
queue-settings
These are the settings applied to a queue its creation.
clustered
Whether or not this queue is clustered
dlq
The name of the Dead Letter Queue to use for this queue
expiry-queue
The name of the Expiry Queue to use for this queue
redelivery-delay
How long to wait, in milliseconds, before trying to redeliver a message.
max-size
The maximum number of messages a queue can hold before rejecting. -1 means unlimited which is the default
distribution-policy-class
The distribution policy class to use when multiple consumers are registered with a single queue. A round robin policy is used by default.
This configuration file is used to create destinations and Connection Factories and make them available in JNDI. Note that this is the only configuration file that exposes JMS functionality, the rest of the configuration is 100% JMS agnostic.
A typical jbm-jndi.xml config looks like:
<deployment>
<connection-factory name="testConnectionFactory">
<entry name="testConnectionFactory"/>
</connection-factory>
<connection-factory name="ConnectionFactory">
<entry name="/ConnectionFactory"/>
<entry name="/XAConnectionFactory"/>
<entry name="java:/ConnectionFactory"/>
<entry name="java:/XAConnectionFactory"/>
</connection-factory>
<connection-factory name="ClusteredConnectionFactory">
<entry name="/ClusteredConnectionFactory"/>
<entry name="/ClusteredXAConnectionFactory"/>
<entry name="java:/ClusteredConnectionFactory"/>
<entry name="java:/ClusteredXAConnectionFactory"/>
<supports-failover>true</supports-failover>
<supports-load-balancing>true</supports-load-balancing>
</connection-factory>
<connection-factory name="MyExampleConnectionFactory">
<entry name="/MyExampleConnectionFactory"/>
<entry name="/acme/MyExampleConnectionFactoryDupe"/>
<entry name="java:/xyz/CF1"/>
<entry name="java:/connectionfactories/acme/connection_factory"/>
<!-- You can specify the default Client ID to use for connections created using
this factory -->
<client-id>MyClientID</client-id>
<!-- The batch size to use when using the DUPS_OK_ACKNOWLEDGE acknowledgement mode -->
<dups-ok-batch-size>5000</dups-ok-batch-size>-size>
<!-- This is the window size in number of messages to use when using producer window
based flow control -->
<producer-window-size>1000</producer-window-size>
<!-- This is the maximum producer send rate that will be applied when using rate
based producer flow control -->
<producer-max-rate>100</producer-max-rate>
<!-- This is the window size in number of messages to use when using consumer window
based flow control -->
<consumer-window-size>1000</consumer-window-size>
<!-- This is the maximum producer send rate that will be applied when using rate
based consumer flow control -->
<consumer-max-rate>5000</consumer-max-rate>
<!--Whether or not we use a blocking call when acknowledging a message-->
<block-on-acknowledge>false</block-on-acknowledge>
<!--Whether we send non persistent messages synchronously-->
<send-np-messages-synchronously>true</send-np-messages-synchronously>
<!--Whether we send persistent messages synchronously-->
<send-p-messages-synchronously>true</send-p-messages-synchronously>
</connection-factory>
<queue name="DLQ">
<entry name="/queue/DLQ"/>
</queue>
<queue name="ExpiryQueue">
<entry name="/queue/ExpiryQueue"/>
</queue>
<topic name="testTopic">
<entry name="/topic/testTopic"/>
</topic>
<topic name="securedTopic">
<entry name="/topic/securedTopic"/>
</topic>
<topic name="testDurableTopic">
<entry name="/topic/testDurableTopic"/>
</topic>
<queue name="testQueue">
<entry name="/queue/testQueue"/>
</queue>
<queue name="testPerfQueue">
<entry name="/queue/testPerfQueue"/>
</queue>
<queue name="A">
<entry name="/queue/A"/>
</queue>
<queue name="B">
<entry name="/queue/B"/>
</queue>
<queue name="C">
<entry name="/queue/C"/>
</queue>
<queue name="D">
<entry name="/queue/D"/>
</queue>
<queue name="ex">
<entry name="/queue/ex"/>
</queue>
<queue name="PrivateDLQ">
<entry name="/queue/PrivateDLQ"/>
</queue>
<queue name="PrivateExpiryQueue">
<entry name="/queue/PrivateExpiryQueue"/>
</queue>
<queue name="QueueWithOwnDLQAndExpiryQueue">
<entry name="/queue/QueueWithOwnDLQAndExpiryQueue"/>
</queue>
<topic name="TopicWithOwnDLQAndExpiryQueue">
<entry name="/topic/QueueWithOwnDLQAndExpiryQueue"/>
</topic>
<queue name="QueueWithOwnRedeliveryDelay">
<entry name="/queue/QueueWithOwnRedeliveryDelay"/>
</queue>
<topic name="TopicWithOwnRedeliveryDelay">
<entry name="/queue/TopicWithOwnRedeliveryDelay"/>
</topic>
<queue name="testDistributedQueue">
<entry name="/topic/testDistributedQueue"/>
</queue>
<topic name="testDistributedTopic">
<entry name="/topic/testDistributedTopic"/>
</topic>
</deployment>
The available configuration attributes are:
connection-factory
The connection factory to create with a unique name
entry
The name to store the Connection Factory object in JNDI with. Multiple JNDI entries can be added.
client-id
The client id for connections created using this Connection Factory
dups-ok-batch-size
The number of acks to batch up when DUPS_OK_ACKNOWLEDGE acknowledgement mode is used
producer-window-size
This is the window size in number of messages to use when using producer window based flow control
producer-max-rate
This is the maximum producer send rate that will be applied when using rate based producer flow control.
consumer-window-size
This is the window size in number of messages to use when using consumer window based flow control
consumer-max-rate
This is the maximum producer send rate that will be applied when using rate based consumer flow control.
block-on-acknowledge
Whether or not we use a blocking call when acknowledging a message
send-np-messages-synchronously
Whether we send non persistent messages synchronously.
send-p-messages-synchronously
Whether we send persistent messages synchronously.
queue
The queue to create with a unique name.
entry
The name to store the Connection Factory object in JNDI with. Multiple JNDI entries can be added.
topic
The queue to create with a unique name.
entry
The name to store the Connection Factory object in JNDI with. Multiple JNDI entries can be added.
This beans deployment file, usually jbm-beans.xml orjbm-standalone-beans.xml, is used by the JBoss Microcontainer to bootstrap all the components needed to run a JBoss Messaging Server. For the purposes of configuring JBM it is sufficient to know that the implementation details of pluggable components are configured here.
The following explains each component in more detail
The naming Service
This is only found in the standalone version of the beans file. When running within the App Server this is not needed since it is available as its own service. This is also where you can change the ports used.
It is possible to replace this with any Naming Service however only the JBoss naming provider has been tested. If you do provide your own implementation remember to edit the file jndi.properties
<bean name="Naming" class="org.jnp.server.NamingBeanImpl"/>
<bean name="Main" class="org.jnp.server.Main">
<property name="namingInfo"><inject bean="Naming"/> </property>
<property name="port">1099</property>
<property name="bindAddress"><inject bean="Configuration" property="host"/></property>
<property name="rmiPort">1098</property>
<property name="rmiBindAddress"><inject bean="Configuration" property="host"/></property>
</bean>
The Configuration component
<bean name="Configuration"
class="org.jboss.messaging.core.config.impl.FileConfiguration"/>
The Configuration component is used to configure the JBM Server and transports. The default implementation, FileConfiguration reads in the configuration from the filejbm-configuration.xml. To replace this component your class must implement following interface:
org.jboss.messaging.core.config.Configuration
The Security Manager
There are 2 Security Manager implementations available to use. In standalone the default is the following
<bean name="JBMSecurityManager"
class="org.jboss.messaging.core.security.impl.JBMSecurityManagerImpl">
<constructor>
<parameter>false</parameter>
</constructor>
</bean>
This uses a simple security manager that also needs the following bean deployed which will read the security configuration from the file jbm-security.xml
<bean name="SecurityManagerDeployer"
class="org.jboss.messaging.core.deployers.impl.SecurityManagerDeployer">
<property name="jbmSecurityManager">
<inject bean="JBMSecurityManager"/>
</property>
<property name="messagingServer">
<inject bean="MessagingServer"/>
</property>
</bean>
The second is used when deployed in the JBoss App Server and will make use of JAAS:
<bean name="JBMSecurityManager"
class="org.jboss.messaging.core.security.impl.JAASSecurityManager"/>
To replace the Security Manager implement the following interface:
org.jboss.messaging.core.security.JBMSecurityManager
Messaging Server Management
This exposes Server management operations via JMX. This can be removed if this functionality is not needed
<bean name="MessagingServerManagement"
class="org.jboss.messaging.core.management.impl.MessagingServerManagementImpl">
<annotation>
@org.jboss.aop.microcontainer.aspects.jmx.JMX(
name="jboss.messaging:service=MessagingServerManagement",
exposedInterface=org.jboss.messaging.core.management.MessagingServerManagement.class
)</annotation>
<property name="messagingServer">
<inject bean="MessagingServer"/>
</property>
</bean>
The Messaging Server
This must never be changed as it is the core messaging server
<bean name="MessagingServer"
class="org.jboss.messaging.core.server.impl.MessagingServerImpl">
<property name="storageManager">
<inject bean="StorageManager"/>
</property>
<property name="remotingService">
<inject bean="RemotingService"/>
</property>
<property name="configuration">
<inject bean="Configuration"/>
</property>
<property name="securityManager">
<inject bean="JBMSecurityManager"/>
</property>
</bean>
The Storage Manager
The Storage manager deals with the persistence of messages and bindings. For more information on this refer to the chapter 'The journal based persistence approach'.
<bean name="StorageManager"
class="org.jboss.messaging.core.persistence.impl.journal.JournalStorageManager">
<constructor>
<parameter>
<inject bean="Configuration"/>
</parameter>
</constructor>
</bean>
To replace this pluggable component implement the following interface:
org.jboss.messaging.core.persistence.StorageManager
The Remoting Service
The Remoting Service is the transport used by the JBM server
<bean name="RemotingService"
class="org.jboss.messaging.core.remoting.impl.mina.MinaService">
<constructor>
<parameter>
<inject bean="Configuration"/>
</parameter>
</constructor>
</bean>
To replace this pluggable component implement the following interface:
org.jboss.messaging.core.remoting.RemotingService
The JMS Server Manager
The JMS Server Manager exposes JMS operations via JMX. This can be removed if not needed.
<bean name="JMSServerManager"
class="org.jboss.messaging.jms.server.impl.JMSServerManagerImpl">
<annotation>
@org.jboss.aop.microcontainer.aspects.jmx.JMX(
name="jboss.messaging:service=JMSServerManager",
exposedInterface=org.jboss.messaging.jms.server.JMSServerManager.class)
</annotation>
<property name="messagingServerManagement">
<inject bean="MessagingServerManagement"/>
</property>
</bean>
The JMS Server Deployer
The JMS Server Deployer takes care of deploying Destinations and Connection Factories into JNDi via the filejbm-jndi.xml. This can be removed if no objects are needed in JNDI or if only core messaging is being used.
<bean name="JMSServerDeployer"
class="org.jboss.messaging.jms.server.impl.JMSServerDeployer">
<property name="jmsServerManager">
<inject bean="JMSServerManager"/>
</property>
<property name="messagingServer">
<inject bean="MessagingServer"/>
</property>
</bean>