JBoss Messaging 1.4 User's Guide

JBoss Messaging is destined to become part of both Application Server Platform and Service Integration Platform as default JMS provider.Production support will then be fully available for these plaforms and it will cover JBoss Messaging.

There is a currently an early adopters program where production support is given for JBoss Messaging. Applications are considered on a case-by-case basis.

Currently developer support is generally available for JBoss Messaging when installed in JBoss 4.2.x

JBoss Messaging provides:

Other JBoss Messaging features include:

Clustering features:

JBoss MQ is the JMS implementation currently shipped within JBoss AS. Since JBoss Messaging is JMS 1.1 and JMS 1.0.2b compatible, the JMS code written against JBossMQ will run with JBoss Messaging without any changes.

JBoss Messaging does not have wire format compatibility with JBoss MQ so it would be necessary to upgrade JBoss MQ clients with JBoss Messaging client jars

If you want to experiment with the latest developments you may checkout the latest code from the Messaging SVN trunk. Be aware that the information provided in this manual might then not be accurate. For the latest instructions on how to check out and build source code, please go to Messaging Development wiki page, specifically "Building and Running JBoss Messaging" section.

In this section we present two different methods of installing JBoss Messaging in JBoss AS 4.2

To run the server, execute the run.bat or run.sh script as appropriate for your operating system, in the $JBOSS_HOME/bin directory.

cd $JBOSS_HOME/bin
./run.sh -c <config name>
   

Where config_name is the name of the JBoss AS configuration where you have installed messaging. (The default is 'messaging')

A successful JBoss Messaging deployment generates logging output similar to for a non clustered installation (for a clustered installation you will also see extra cluster related output)

....
13:19:14,914 WARN  [JDBCPersistenceManager] 

JBoss Messaging Warning: DataSource connection transaction isolation should be READ_COMMITTED,
but it is currently NONE.
                         Using an isolation level less strict than READ_COMMITTED may lead to
data consistency problems.
                         Using an isolation level more strict than READ_COMMITTED may lead to
deadlock.

13:19:15,166 INFO  [ServerPeer] JBoss Messaging 1.4.0.GA server [0] started
13:19:15,411 INFO  [ConnectionFactory] Connector bisocket://127.0.0.1:4457 has leasing enabled
, lease period 10000 milliseconds
13:19:15,412 INFO  [ConnectionFactory] [/ConnectionFactory, /XAConnectionFactory, java:/Connec
tionFactory, java:/XAConnectionFactory] started
13:19:15,412 WARN  [ConnectionFactoryJNDIMapper] supportsFailover attribute is true on connect
ion factory: jboss.messaging.connectionfactory:service=ClusteredConnectionFactory but
post office is non clustered. So connection factory will *not* support failover
13:19:15,413 WARN  [ConnectionFactoryJNDIMapper] supportsLoadBalancing attribute is true on co
nnection factory: jboss.messaging.connectionfactory:service=ClusteredConnectionFactory
but post office is non clustered. So connection factory will *not* support load balanc
ing
13:19:15,449 INFO  [ConnectionFactory] Connector bisocket://127.0.0.1:4457 has leasing enabled
, lease period 10000 milliseconds
13:19:15,449 INFO  [ConnectionFactory] [/ClusteredConnectionFactory, /ClusteredXAConnectionFac
tory, java:/ClusteredConnectionFactory, java:/ClusteredXAConnectionFactory] started
13:19:15,468 INFO  [QueueService] Queue[/queue/DLQ] started, fullSize=200000, pageSize=2000, d
ownCacheSize=2000
13:19:15,474 INFO  [QueueService] Queue[/queue/ExpiryQueue] started, fullSize=200000, pageSize
=2000, downCacheSize=2000
13:19:15,476 INFO  [TopicService] Topic[/topic/testTopic] started, fullSize=200000, pageSize=2
000, downCacheSize=2000
13:19:15,478 INFO  [TopicService] Topic[/topic/securedTopic] started, fullSize=200000, pageSiz
e=2000, downCacheSize=2000
13:19:15,479 INFO  [TopicService] Topic[/topic/testDurableTopic] started, fullSize=200000, pag
eSize=2000, downCacheSize=2000
13:19:15,482 INFO  [QueueService] Queue[/queue/testQueue] started, fullSize=200000, pageSize=2
000, downCacheSize=2000
13:19:15,483 INFO  [QueueService] Queue[/queue/A] started, fullSize=200000, pageSize=2000, dow
nCacheSize=2000
13:19:15,485 INFO  [QueueService] Queue[/queue/B] started, fullSize=200000, pageSize=2000, dow
nCacheSize=2000
13:19:15,487 INFO  [QueueService] Queue[/queue/C] started, fullSize=200000, pageSize=2000, dow
nCacheSize=2000
13:19:15,489 INFO  [QueueService] Queue[/queue/D] started, fullSize=200000, pageSize=2000, dow
nCacheSize=2000
13:19:15,490 INFO  [QueueService] Queue[/queue/ex] started, fullSize=200000, pageSize=2000, do
wnCacheSize=2000
13:19:15,501 INFO  [QueueService] Queue[/queue/PrivateDLQ] started, fullSize=200000, pageSize=
2000, downCacheSize=2000
13:19:15,503 INFO  [QueueService] Queue[/queue/PrivateExpiryQueue] started, fullSize=200000, p
ageSize=2000, downCacheSize=2000
13:19:15,507 INFO  [QueueService] Queue[/queue/QueueWithOwnDLQAndExpiryQueue] started, fullSiz
e=200000, pageSize=2000, downCacheSize=2000
13:19:15,508 INFO  [TopicService] Topic[/topic/TopicWithOwnDLQAndExpiryQueue] started, fullSiz
e=200000, pageSize=2000, downCacheSize=2000
13:19:15,511 INFO  [QueueService] Queue[/queue/QueueWithOwnRedeliveryDelay] started, fullSize=
200000, pageSize=2000, downCacheSize=2000
13:19:15,512 INFO  [TopicService] Topic[/topic/TopicWithOwnRedeliveryDelay] started, fullSize=
200000, pageSize=2000, downCacheSize=2000
13:19:15,514 INFO  [QueueService] Queue[/queue/testDistributedQueue] started, fullSize=200000,
pageSize=2000, downCacheSize=2000
13:19:15,519 INFO  [TopicService] Topic[/topic/testDistributedTopic] started, fullSize=200000,
pageSize=2000, downCacheSize=2000
13:19:15,809 INFO  [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:servic
e=ConnectionFactoryBinding,name=JmsXA' to JNDI name 'java:JmsXA'
13:19:15,834 INFO  [TomcatDeployer] deploy, ctxPath=/jmx-console, warUrl=.../deploy/jmx-consol
e.war/
13:19:16,322 INFO  [Http11Protocol] Starting Coyote HTTP/1.1 on http-127.0.0.1-8080
13:19:16,342 INFO  [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009
13:19:16,480 INFO  [Server] JBoss (MX MicroKernel) [4.2.0.GA (build: SVNTag=JBoss_4_2_0_GA dat
e=200705111440)] Started in 19s:359ms

   

The release bundle contains a series of examples that should run "out of the box" and could be used to validate a new installation. Such an example sends a persistent JMS message to a queue called queue/testQueue.

To run the example and validate the installation, open an new command line window and set the JBOSS_HOME environment variable to point to the JBoss AS 4.x installation you've just installed Messaging on. Navigate to the folder where you extracted the release bundle and drill down to /examples/queue. Apache Ant must pe present in your path in order to be able to run the example.

Make sure you start the JBoss server before trying to run the tests

setenv JBOSS_HOME=<your_JBoss_installation>
cd .../examples/queue
$ant

   

A successfull execution log output looks similar to:

[tim@Vigor14 queue]$ ant
Buildfile: build.xml

identify:
     [echo] ###########################################################################
     [echo] #                       Running the QUEUE example                         #
     [echo] ###########################################################################
     [echo] The queue:      testQueue
     [echo] The client jar: ../../../output/lib/jboss-messaging-client.jar

sanity-check:

init:
    [mkdir] Created dir: /home/tim/dev/jboss-messaging/trunk/docs/examples/queue/output/classe
s
    [mkdir] Created dir: /home/tim/dev/jboss-messaging/trunk/docs/examples/common/output/class
es

compile:
    [javac] Compiling 5 source files to /home/tim/dev/jboss-messaging/trunk/docs/examples/comm
on/output/classes
    [javac] Compiling 1 source file to /home/tim/dev/jboss-messaging/trunk/docs/examples/queue
/output/classes

run:
     [java] Queue /queue/testQueue exists
     [java] The message was successfully sent to the testQueue queue
     [java] Received message: Hello!
     [java] The example connected to JBoss Messaging version 1.4.0.GA (1.4)

     [java] #####################
     [java] ###    SUCCESS!   ###
     [java] #####################

BUILD SUCCESSFUL
Total time: 5 seconds
[tim@Vigor14 queue]$

It is recommended to run all validation examples available in the example directory (queue, topic, mdb, stateless, etc.). In Chapter 5, Running the Examples, we will have a look at each of those examples.

In order to access JBoss Messaging from a client outside the JBoss app server, you will need to ensure the following jar files are on the client classpath:

The Server Peer is the heart of the JBoss Messaging JMS facade. The server's configuration, resides in messaging-service.xml configuration file.

All JBoss Messaging services are rooted at the server peer

An example of a Server Peer configuration is presented below. Note that not all values for the server peer's attributes are specified in the example

<mbean code="org.jboss.jms.server.ServerPeer"
      name="jboss.messaging:service=ServerPeer"
      xmbean-dd="xmdesc/ServerPeer-xmbean.xml">

      <!-- The unique id of the server peer - in a cluster each node MUST have a unique value - must be an integer -->

      <attribute name="ServerPeerID">0</attribute>
      
      <!-- The default JNDI context to use for queues when they are deployed without specifying one --> 
      
      <attribute name="DefaultQueueJNDIContext">/queue</attribute>
      
      <!-- The default JNDI context to use for topics when they are deployed without specifying one --> 
      
      <attribute name="DefaultTopicJNDIContext">/topic</attribute>

	     <attribute name="PostOffice">jboss.messaging:service=PostOffice</attribute>
	  
	     <!-- The JAAS security domain to use for JBoss Messaging -->
	  
      <attribute name="SecurityDomain">java:/jaas/messaging</attribute>
      
      <!-- The default security configuration to apply to destinations - this can be overridden on a per destination basis -->
      
      <attribute name="DefaultSecurityConfig">
        <security>
            <role name="guest" read="true" write="true" create="true"/>
        </security>
      </attribute>
      
      <!-- The default Dead Letter Queue (DLQ) to use for destinations.
           This can be overridden on a per destinatin basis -->
      
      <attribute name="DefaultDLQ">jboss.messaging.destination:service=Queue,name=DLQ</attribute>
      
      <!-- The default maximum number of times to attempt delivery of a message before sending to the DLQ (if configured).
           This can be overridden on a per destinatin basis -->
      
      <attribute name="DefaultMaxDeliveryAttempts">10</attribute>
      
      <!-- The default Expiry Queue to use for destinations. This can be overridden on a per destinatin basis -->
      
      <attribute name="DefaultExpiryQueue">jboss.messaging.destination:service=Queue,name=ExpiryQueue</attribute>
      
      <!-- The default redelivery delay to impose. This can be overridden on a per destination basis -->
      
      <attribute name="DefaultRedeliveryDelay">0</attribute>
      
      <!-- The periodicity of the message counter manager enquiring on queues for statistics -->
      
      <attribute name="MessageCounterSamplePeriod">5000</attribute>
      
      <!-- The maximum amount of time for a client to wait for failover to start on the server side after
           it has detected failure -->
      
      <attribute name="FailoverStartTimeout">60000</attribute>
      
      <!-- The maximum amount of time for a client to wait for failover to complete on the server side after
           it has detected failure -->
      
      <attribute name="FailoverCompleteTimeout">300000</attribute>
      
      <!-- The maximum number of days results to maintain in the message counter history -->
      
      <attribute name="DefaultMessageCounterHistoryDayLimit">-1</attribute>
      
      <!-- The name of the connection factory to use for creating connections between nodes to pull messages -->
      
      <attribute name="ClusterPullConnectionFactoryName">jboss.messaging.connectionfactory:service=ClusterPullConnectionFactory</attribute>
      
      <!-- Use XA when pulling persistent messages from a remote node to this one. -->
      
      <attribute name="UseXAForMessagePull">false</attribute>
      
      <!-- When redistributing messages in the cluster. Do we need to preserve the order of messages received
            by a particular consumer from a particular producer? -->
            
      <attribute name="DefaultPreserveOrdering">false</attribute>
      
      <!-- Max. time to hold previously delivered messages back waiting for clients to reconnect after failover -->
      
      <attribute name="RecoverDeliveriesTimeout">300000</attribute>
      
      <!-- The password used by the message sucker connections to create connections.
           THIS SHOULD ALWAYS BE CHANGED AT INSTALL TIME TO SECURE SYSTEM
      <attribute name="SuckerPassword"></attribute>
      -->

      <depends optional-attribute-name="PersistenceManager">jboss.messaging:service=PersistenceManager</depends>
      
      <depends optional-attribute-name="JMSUserManager">jboss.messaging:service=JMSUserManager</depends>
      
      <depends>jboss.messaging:service=Connector,transport=bisocket</depends>

   </mbean>
      

Several JBoss Messaging services interact with persistent storage. They include: The Persistence Manager, The PostOffice and the JMS User Manager. The Persistence Manager is used to handle the message-related persistence. The Post Office handles binding related persistence. The JMS User manager handles user related persistence The configuration for all these MBeans is handled in the xxx-persistence-service.xml file.

If the database you want to switch to is one of MySQL, Oracle, PostgreSQL, MS SQL Sever or Sybase, persistence configuration files are already available in the examples/config directory of the release bundle.

In order to enable support for one of these databases, just replace the default hsqldb-persistence-service.xml configuration file with the database-specific configuration file and restart the server.

Also, be aware that by default, the Messaging services relying on a datastore are referencing "java:/DefaultDS" for the datasource. If you are deploying a datasource with a different JNDI name, you need to update all the DataSource attribute in the persistence configuration file. Example data source configurations for each of the popular databases are available in the distribution.

It is the job of the post office to route messages to their destination(s).

The post office maintains the mappings between addresses to which messages can be sent and their final queues.

For example when sending a message with an address that represents a JMS queue name, the post office will route this to a single queue - the JMS queue. When sending a message with an address that repesents a JMS topic name, the post office will route this to a set of queues - one for each JMS subscription.

The post office also handles the persistence for the mapping of addresses.

JBoss Messaging post-offices are also cluster aware. In a cluster they will automatically route and pull messages between them in order to provide fully distributed JMS queues and topics.

The post office configuration is found in the xxx-persistence-service.xml file (where xxx is the name of your database).

Here is an example of a post office configuration:

   <mbean code="org.jboss.messaging.core.jmx.MessagingPostOfficeService"
      name="jboss.messaging:service=PostOffice"
      xmbean-dd="xmdesc/MessagingPostOffice-xmbean.xml">
      
      <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
                
      <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
      
      <depends optional-attribute-name="TransactionManager">jboss:service=TransactionManager</depends>
      
      <!-- The name of the post office -->                  
      
      <attribute name="PostOfficeName">JMS post office</attribute>
      
      <!-- The datasource used by the post office to access it's binding information -->                     
      
      <attribute name="DataSource">java:/DefaultDS</attribute>
      
      <!-- If true will attempt to create tables and indexes on every start-up -->
                        
      <attribute name="CreateTablesOnStartup">true</attribute>
      
      <attribute name="SqlProperties"><![CDATA[
CREATE_POSTOFFICE_TABLE=CREATE TABLE JBM_POSTOFFICE (POSTOFFICE_NAME VARCHAR(255), NODE_ID INTEGER, QUEUE_NAME VARCHAR(255), COND VARCHAR(1023), SELECTOR VARCHAR(1023), CHANNEL_ID BIGINT, CLUSTERED CHAR(1), ALL_NODES CHAR(1), PRIMARY KEY(POSTOFFICE_NAME, NODE_ID, QUEUE_NAME)) ENGINE = INNODB
INSERT_BINDING=INSERT INTO JBM_POSTOFFICE (POSTOFFICE_NAME, NODE_ID, QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED, ALL_NODES) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
DELETE_BINDING=DELETE FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME=? AND NODE_ID=? AND QUEUE_NAME=?
LOAD_BINDINGS=SELECT QUEUE_NAME, COND, SELECTOR, CHANNEL_ID, CLUSTERED, ALL_NODES FROM JBM_POSTOFFICE WHERE POSTOFFICE_NAME=? AND NODE_ID=?
      ]]></attribute>
      
      <!-- This post office is clustered. If you don't want a clustered post office then set to false -->
      
      <attribute name="Clustered">true</attribute>
      
      <!-- All the remaining properties only have to be specified if the post office is clustered.
           You can safely comment them out if your post office is non clustered -->
      
      <!-- The JGroups group name that the post office will use -->            
      
      <attribute name="GroupName">${jboss.messaging.groupname:MessagingPostOffice}</attribute>
      
      <!-- Max time to wait for state to arrive when the post office joins the cluster -->            
                  
      <attribute name="StateTimeout">5000</attribute>
      
      <!-- Max time to wait for a synchronous call to node members using the MessageDispatcher -->            
                  
      <attribute name="CastTimeout">50000</attribute>
      
      <!-- JGroups stack configuration for the data channel - used for sending data across the cluster --> 
                   
      <!-- By default we use the TCP stack for data -->                  
      <attribute name="DataChannelConfig">      
         <config>
            <TCP start_port="7900"
                 loopback="true"
                 recv_buf_size="20000000"
                 send_buf_size="640000"
                 discard_incompatible_packets="true"
                 max_bundle_size="64000"
                 max_bundle_timeout="30"
                 use_incoming_packet_handler="true"
                 use_outgoing_packet_handler="false"
                 down_thread="false" up_thread="false"
                 enable_bundling="false"
                 use_send_queues="false"
                 sock_conn_timeout="300"
                 skip_suspected_members="true"/>
            <MPING timeout="4000"
		         bind_to_all_interfaces="true"
		         mcast_addr="${jboss.messaging.datachanneludpaddress:228.6.6.6}"
		         mcast_port="${jboss.messaging.datachanneludpport:45567}"
		         ip_ttl="8"
		         num_initial_members="2"
		         num_ping_requests="1"/>                     
            <MERGE2 max_interval="100000"
                    down_thread="false" up_thread="false" min_interval="20000"/>
            <FD_SOCK down_thread="false" up_thread="false"/>            
            <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
            <pbcast.NAKACK max_xmit_size="60000"
                           use_mcast_xmit="false" gc_lag="0"
                           retransmit_timeout="300,600,1200,2400,4800"
                           down_thread="false" up_thread="false"
                           discard_delivered_msgs="true"/>
            <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
                           down_thread="false" up_thread="false"
                           max_bytes="400000"/>
            <pbcast.GMS print_local_addr="true" join_timeout="3000"
                        down_thread="false" up_thread="false"
                        join_retry_timeout="2000" shun="false"
                        view_bundling="true"/>
        </config>        
      </attribute>
      
      <!-- JGroups stack configuration to use for the control channel - used for control messages -->         
              
      <!-- We use udp stack for the control channel -->
      <attribute name="ControlChannelConfig">
         <config>
            <UDP
                 mcast_addr="${jboss.messaging.controlchanneludpaddress:228.7.7.7}"
                 mcast_port="${jboss.messaging.controlchanneludpport:45568}"
                 tos="8"
                 ucast_recv_buf_size="20000000"
                 ucast_send_buf_size="640000"
                 mcast_recv_buf_size="25000000"
                 mcast_send_buf_size="640000"
                 loopback="false"
                 discard_incompatible_packets="true"
                 max_bundle_size="64000"
                 max_bundle_timeout="30"
                 use_incoming_packet_handler="true"
                 use_outgoing_packet_handler="false"
                 ip_ttl="2"
                 down_thread="false" up_thread="false"
                 enable_bundling="false"/>
            <PING timeout="2000"
                  down_thread="false" up_thread="false" num_initial_members="3"/>
            <MERGE2 max_interval="100000"
                    down_thread="false" up_thread="false" min_interval="20000"/>
            <FD_SOCK down_thread="false" up_thread="false"/>
            <FD timeout="10000" max_tries="5" down_thread="false" up_thread="false" shun="true"/>
            <VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
            <pbcast.NAKACK max_xmit_size="60000"
                           use_mcast_xmit="false" gc_lag="0"
                           retransmit_timeout="300,600,1200,2400,4800"
                           down_thread="false" up_thread="false"
                           discard_delivered_msgs="true"/>
            <UNICAST timeout="300,600,1200,2400,3600"
                     down_thread="false" up_thread="false"/>
            <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
                           down_thread="false" up_thread="false"
                           max_bytes="400000"/>
            <pbcast.GMS print_local_addr="true" join_timeout="3000" use_flush="true" flush_timeout="3000"
                        down_thread="false" up_thread="false"
                        join_retry_timeout="2000" shun="false"
                        view_bundling="true"/>
            <FRAG2 frag_size="60000" down_thread="false" up_thread="false"/>
            <pbcast.STATE_TRANSFER down_thread="false" up_thread="false" use_flush="true" flush_timeout="3000"/>
            <pbcast.FLUSH down_thread="false" up_thread="false" timeout="20000" auto_flush_conf="false"/>
        </config>
     </attribute>	   
      
   </mbean>
      

It is the job of the persistence manager to manage all message related persistence.

JBoss Messaging ships with a JDBC Persistence Manager used for handling persistence of message data in a relational database accessed via JDBC. The Persistence Manager implementation is pluggable (the Persistence Manager is a Messaging server plug-in), this making possible to provide other implementations for persisting message data in non relational stores, file stores etc.

The configuration of "persistent" services is grouped in a xxx-persistence-service.xml file, where xxx corresponds to the database name. By default, Messaging ships with a hsqldb-persistence-service.xml, which configures the Messaging server to use the in-VM Hypersonic database instance that comes by default with any JBossAS instance.

JBoss Messaging also ships with pre-made Persistence Manager configurations for MySQL, Oracle, PostgreSQL, Sybase and MS SQL Server. The example mysql-persistence-service.xml, oracle-persistence-service.xml, postgres-persistence-service.xml and sybase-persistence-service.xml and mssql-persistence-service.xml configuration files are available in the examples/config directory of the release bundle.

Users are encouraged to contribute their own configuration files where we will thoroughly test them before certifying them for suppported use with JBoss Messaging. The JDBC Persistence Manager has been designed to use standard SQL for the DML so writing a JDBC Persistence Manager configuration for another database is usually only a fairly simple matter of changing DDL in the configuration which is likely to be different for different databases.

The default Hypersonic persistence configuration file is listed below:

	 <mbean code="org.jboss.messaging.core.jmx.JDBCPersistenceManagerService"
      name="jboss.messaging:service=PersistenceManager"
      xmbean-dd="xmdesc/JDBCPersistenceManager-xmbean.xml">
      
      <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
      
      <depends optional-attribute-name="TransactionManager">jboss:service=TransactionManager</depends>
      
      <!-- The datasource to use for the persistence manager -->
                    
      <attribute name="DataSource">java:/DefaultDS</attribute>      
      
      <!-- If true will attempt to create tables and indexes on every start-up -->
                  
      <attribute name="CreateTablesOnStartup">true</attribute>
      
      <!-- If true then will use JDBC batch updates -->
                  
      <attribute name="UsingBatchUpdates">true</attribute>
      
      <attribute name="SqlProperties"><![CDATA[
   CREATE_DUAL=CREATE TABLE JBM_DUAL (DUMMY INTEGER, PRIMARY KEY (DUMMY)) ENGINE = INNODB
   CREATE_MESSAGE_REFERENCE=CREATE TABLE JBM_MSG_REF (CHANNEL_ID BIGINT, MESSAGE_ID BIGINT, TRANSACTION_ID BIGINT, STATE CHAR(1), ORD BIGINT, PAGE_ORD BIGINT, DELIVERY_COUNT INTEGER, SCHED_DELIVERY BIGINT, PRIMARY KEY(CHANNEL_ID, MESSAGE_ID)) ENGINE = INNODB
   CREATE_IDX_MESSAGE_REF_TX=CREATE INDEX JBM_MSG_REF_TX ON JBM_MSG_REF (TRANSACTION_ID)
   CREATE_IDX_MESSAGE_REF_ORD=CREATE INDEX JBM_MSG_REF_ORD ON JBM_MSG_REF (ORD)
   CREATE_IDX_MESSAGE_REF_PAGE_ORD=CREATE INDEX JBM_MSG_REF_PAGE_ORD ON JBM_MSG_REF (PAGE_ORD)
   CREATE_IDX_MESSAGE_REF_MESSAGE_ID=CREATE INDEX JBM_MSG_REF_MESSAGE_ID ON JBM_MSG_REF (MESSAGE_ID)
   CREATE_IDX_MESSAGE_REF_SCHED_DELIVERY=CREATE INDEX JBM_MSG_REF_SCHED_DELIVERY ON JBM_MSG_REF (SCHED_DELIVERY)
   CREATE_MESSAGE=CREATE TABLE JBM_MSG (MESSAGE_ID BIGINT, RELIABLE CHAR(1), EXPIRATION BIGINT, TIMESTAMP BIGINT, PRIORITY TINYINT, TYPE TINYINT, INS_TIME BIGINT, HEADERS MEDIUMBLOB, PAYLOAD LONGBLOB, PRIMARY KEY (MESSAGE_ID)) ENGINE = INNODB
   CREATE_IDX_MESSAGE_TIMESTAMP=CREATE INDEX JBM_MSG_REF_TIMESTAMP ON JBM_MSG (TIMESTAMP)
   CREATE_TRANSACTION=CREATE TABLE JBM_TX (NODE_ID INTEGER, TRANSACTION_ID BIGINT, BRANCH_QUAL VARBINARY(254), FORMAT_ID INTEGER, GLOBAL_TXID VARBINARY(254), PRIMARY KEY (TRANSACTION_ID)) ENGINE = INNODB
   CREATE_COUNTER=CREATE TABLE JBM_COUNTER (NAME VARCHAR(255), NEXT_ID BIGINT, PRIMARY KEY(NAME)) ENGINE = INNODB
   INSERT_DUAL=INSERT INTO JBM_DUAL VALUES (1)
   CHECK_DUAL=SELECT 1 FROM JBM_DUAL
   INSERT_MESSAGE_REF=INSERT INTO JBM_MSG_REF (CHANNEL_ID, MESSAGE_ID, TRANSACTION_ID, STATE, ORD, PAGE_ORD, DELIVERY_COUNT, SCHED_DELIVERY) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
   DELETE_MESSAGE_REF=DELETE FROM JBM_MSG_REF WHERE MESSAGE_ID=? AND CHANNEL_ID=? AND STATE='C'
   UPDATE_MESSAGE_REF=UPDATE JBM_MSG_REF SET TRANSACTION_ID=?, STATE='-' WHERE MESSAGE_ID=? AND CHANNEL_ID=? AND STATE='C'
   UPDATE_PAGE_ORDER=UPDATE JBM_MSG_REF SET PAGE_ORD = ? WHERE MESSAGE_ID=? AND CHANNEL_ID=?
   COMMIT_MESSAGE_REF1=UPDATE JBM_MSG_REF SET STATE='C', TRANSACTION_ID = NULL WHERE TRANSACTION_ID=? AND STATE='+'
   COMMIT_MESSAGE_REF2=DELETE FROM JBM_MSG_REF WHERE TRANSACTION_ID=? AND STATE='-'
   ROLLBACK_MESSAGE_REF1=DELETE FROM JBM_MSG_REF WHERE TRANSACTION_ID=? AND STATE='+'
   ROLLBACK_MESSAGE_REF2=UPDATE JBM_MSG_REF SET STATE='C', TRANSACTION_ID = NULL WHERE TRANSACTION_ID=? AND STATE='-'
   LOAD_PAGED_REFS=SELECT MESSAGE_ID, DELIVERY_COUNT, PAGE_ORD, SCHED_DELIVERY FROM JBM_MSG_REF WHERE CHANNEL_ID = ? AND PAGE_ORD BETWEEN ? AND ? ORDER BY PAGE_ORD
   LOAD_UNPAGED_REFS=SELECT MESSAGE_ID, DELIVERY_COUNT, SCHED_DELIVERY FROM JBM_MSG_REF WHERE STATE = 'C' AND CHANNEL_ID = ? AND PAGE_ORD IS NULL ORDER BY ORD
   LOAD_REFS=SELECT MESSAGE_ID, DELIVERY_COUNT, SCHED_DELIVERY FROM JBM_MSG_REF WHERE STATE = 'C' AND CHANNEL_ID = ? ORDER BY ORD     
   UPDATE_REFS_NOT_PAGED=UPDATE JBM_MSG_REF SET PAGE_ORD = NULL WHERE PAGE_ORD BETWEEN ? AND ? AND CHANNEL_ID=?
   SELECT_MIN_MAX_PAGE_ORD=SELECT MIN(PAGE_ORD), MAX(PAGE_ORD) FROM JBM_MSG_REF WHERE CHANNEL_ID = ?
   SELECT_EXISTS_REF_MESSAGE_ID=SELECT MESSAGE_ID FROM JBM_MSG_REF WHERE MESSAGE_ID = ?
   UPDATE_DELIVERY_COUNT=UPDATE JBM_MSG_REF SET DELIVERY_COUNT = ? WHERE CHANNEL_ID = ? AND MESSAGE_ID = ?
   UPDATE_CHANNEL_ID=UPDATE JBM_MSG_REF SET CHANNEL_ID = ? WHERE CHANNEL_ID = ?
   LOAD_MESSAGES=SELECT MESSAGE_ID, RELIABLE, EXPIRATION, TIMESTAMP, PRIORITY, HEADERS, PAYLOAD, TYPE FROM JBM_MSG
   INSERT_MESSAGE=INSERT INTO JBM_MSG (MESSAGE_ID, RELIABLE, EXPIRATION, TIMESTAMP, PRIORITY, TYPE, INS_TIME, HEADERS, PAYLOAD) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
   INSERT_MESSAGE_CONDITIONAL=INSERT INTO JBM_MSG (MESSAGE_ID, RELIABLE, EXPIRATION, TIMESTAMP, PRIORITY, TYPE, INST_TIME) SELECT ?, ?, ?, ?, ?, ?, ? FROM JBM_DUAL WHERE NOT EXISTS (SELECT MESSAGE_ID FROM JBM_MSG WHERE MESSAGE_ID = ?)
   UPDATE_MESSAGE_4CONDITIONAL=UPDATE JBM_MSG SET HEADERS=?, PAYLOAD=? WHERE MESSAGE_ID=?
   INSERT_MESSAGE_CONDITIONAL_FULL=INSERT INTO JBM_MSG (MESSAGE_ID, RELIABLE, EXPIRATION, TIMESTAMP, PRIORITY, TYPE, INS_TIME, HEADERS, PAYLOAD) SELECT ?, ?, ?, ?, ?, ?, ?, ?, ? FROM JBM_DUAL WHERE NOT EXISTS (SELECT MESSAGE_ID FROM JBM_MSG WHERE MESSAGE_ID = ?)   
   MESSAGE_ID_COLUMN=MESSAGE_ID
   REAP_MESSAGES=DELETE FROM JBM_MSG WHERE INS_TIME < ? AND NOT EXISTS (SELECT * FROM JBM_MSG_REF WHERE JBM_MSG_REF.MESSAGE_ID = JBM_MSG.MESSAGE_ID)
   DELETE_MESSAGE=DELETE FROM JBM_MSG WHERE MESSAGE_ID = ? AND NOT EXISTS (SELECT * FROM JBM_MSG_REF WHERE JBM_MSG_REF.MESSAGE_ID = ?)      
   INSERT_TRANSACTION=INSERT INTO JBM_TX (NODE_ID, TRANSACTION_ID, BRANCH_QUAL, FORMAT_ID, GLOBAL_TXID) VALUES(?, ?, ?, ?, ?)
   DELETE_TRANSACTION=DELETE FROM JBM_TX WHERE NODE_ID = ? AND TRANSACTION_ID = ?
   SELECT_PREPARED_TRANSACTIONS=SELECT TRANSACTION_ID, BRANCH_QUAL, FORMAT_ID, GLOBAL_TXID FROM JBM_TX WHERE NODE_ID = ?
   SELECT_MESSAGE_ID_FOR_REF=SELECT MESSAGE_ID, CHANNEL_ID FROM JBM_MSG_REF WHERE TRANSACTION_ID = ? AND STATE = '+' ORDER BY ORD
   SELECT_MESSAGE_ID_FOR_ACK=SELECT MESSAGE_ID, CHANNEL_ID FROM JBM_MSG_REF WHERE TRANSACTION_ID = ? AND STATE = '-' ORDER BY ORD
   UPDATE_COUNTER=UPDATE JBM_COUNTER SET NEXT_ID = ? WHERE NAME=?
   SELECT_COUNTER=SELECT NEXT_ID FROM JBM_COUNTER WHERE NAME=? FOR UPDATE
   INSERT_COUNTER=INSERT INTO JBM_COUNTER (NAME, NEXT_ID) VALUES (?, ?)
   SELECT_ALL_CHANNELS=SELECT DISTINCT(CHANNEL_ID) FROM JBM_MSG_REF
   UPDATE_TX=UPDATE JBM_TX SET NODE_ID=? WHERE NODE_ID=?
      ]]></attribute>
      
      <!-- The maximum number of parameters to include in a prepared statement -->
                  
      <attribute name="MaxParams">500</attribute>
         
   </mbean>
	  
	   

The JMS user manager handles the mapping of pre-configured client IDs to users and also managers the user and role tables which may or may not be used depending on which login module you have configured

Here is an example JMSUserManager configuration

   <mbean code="org.jboss.jms.server.plugin.JDBCJMSUserManagerService"
      name="jboss.messaging:service=JMSUserManager"
      xmbean-dd="xmdesc/JMSUserManager-xmbean.xml">
      <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
      <depends optional-attribute-name="TransactionManager">
               jboss:service=TransactionManager
      </depends>
      <attribute name="DataSource">java:/DefaultDS</attribute>
      <attribute name="CreateTablesOnStartup">true</attribute>
      <attribute name="SqlProperties"><![CDATA[
               CREATE_USER_TABLE=CREATE TABLE JBM_USER (USER_ID VARCHAR(32) NOT NULL,
               PASSWD VARCHAR(32) NOT NULL, CLIENTID VARCHAR(128),
               PRIMARY KEY(USER_ID)) ENGINE = INNODB
               CREATE_ROLE_TABLE=CREATE TABLE JBM_ROLE (ROLE_ID VARCHAR(32) NOT NULL,
               USER_ID VARCHAR(32) NOT NULL, PRIMARY KEY(USER_ID, ROLE_ID))
               ENGINE = INNODB
               SELECT_PRECONF_CLIENTID=SELECT CLIENTID FROM JBM_USER WHERE USER_ID=?
               POPULATE.TABLES.1=INSERT INTO JBM_USER (USER_ID,PASSWD,CLIENTID)
               VALUES ('dilbert','dogbert','dilbert-id')
      ]]></attribute>
   </mbean>
           

With the default configuration JBoss Messaging binds two connection factories in JNDI at start-up.

The first connection factory is the default non-clustered connection factory and is bound into the following JNDI contexts: /ConnectionFactory, /XAConnectionFactory, java:/ConnectionFactory, java:/XAConnectionFactory. This connection factory is provided to maintain compatibility with applications originally written against JBoss MQ which has no automatic failover or load balancing. This connection factory should be used if you do not require client side automatic failover or load balancing.

The second connection factory is the default clustered connection factory and is bound into the following JNDI contexts /ClusteredConnectionFactory, /ClusteredXAConnectionFactory, java:/ClusteredConnectionFactory, java:/ClusteredXAConnectionFactory.

You may want to configure additional connection factories, for instance if you want to provide a default client id for a connection factory, or if you want to bind it in different places in JNDI, if you want different connection factories to use different transports, or if you want to selective enable or disable load-balancing and/or automatic failover for a particular connection factory. Deploying a new connection factory is equivalent with adding a new ConnectionFactory MBean configuration to connection-factories-service.xml.

It is also possible to create an entirely new service deployment descriptor xxx-service.xml altogether and deploy it in $JBOSS_HOME/server/messaging/deploy.

Connection factories can support automatic failover and/or load-balancing by setting the corresponding attributes

An example connection factory configuration is presented below:

<mbean code="org.jboss.jms.server.connectionfactory.ConnectionFactory"
      name="jboss.messaging.connectionfactory:service=MyConnectionFactory"
      xmbean-dd="xmdesc/ConnectionFactory-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                 jboss.messaging:service=ServerPeer
      </depends>
      <depends optional-attribute-name="Connector">
                 jboss.messaging:service=Connector,transport=bisocket
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>

      <attribute name="JNDIBindings">
         <bindings>
            <binding>/MyConnectionFactory</binding>
            <binding>/factories/cf</binding>
         </bindings>
      </attribute>
      
      <attribute name="ClientID">myClientID</attribute>

      <attribute name="SupportsFailover">true</attribute>
      
      <attribute name="SupportsLoadBalancing">false</attribute>  
      
      <attribute name="LoadBalancingFactory">org.acme.MyLoadBalancingFactory</attribute>
          
      <attribute name="PrefetchSize">1000</attribute> 

      <attribute name="SlowConsumers">false</attribute>
      
      <attribute name="StrictTck">true</attribute>

      <attribute name="DefaultTempQueueFullSize">50000</attribute>
      
      <attribute name="DefaultTempQueuePageSize">1000</attribute> 
            
      <attribute name="DefaultTempQueueDownCacheSize">1000</attribute> 
      
      <attribute name="DupsOKBatchSize">10000</attribute> 
   </mbean>
   

             

The above example would create a connection factory with pre-configured client ID myClientID and bind the connection factory in two places in the JNDI tree: /MyConnectionFactory and /factories/cf. The connection factory overrides the default values for PreFetchSize, DefaultTempQueueFullSize, DefaultTempQueuePageSize, DefaultTempQueueDownCacheSize and DupsOKBatchSize, SupportsFailover, SupportsLoadBalancing and LoadBalancingFactory. The connection factory will use the default remoting connector. To use a different remoting connector with the connection factory change the Connector attribute to specify the service name of the connector you wish to use.

JBoss Messaging uses JBoss Remoting for all client to server communication. For full details of what JBoss Remoting is capable of and how it is configured please consult the JBoss Remoting documentation.

The default configuration includes a single remoting connector which is used by the single default connection factory. Each connection factory can be configured to use its own connector.

The default connector is configured to use the remoting bisocket transport. The bisocket transport is a TCP socket based transport which only listens and accepts connections on the server side. I.e. connections are always initiated from the client side. This means it works well in typical firewall scenarios where only inbound connections are allowed on the server. Or where onlu outbound connections are allowed from the client.

The bisocket transport can be configured to use SSL where a higher level of security is required.

The other supported transport is the HTTP transport. This uses the HTTP protocol to communicate between client and server. Data is received on the client by the client periodically polling the server for messages. This transport is well suited to situations where there is a firewall between client and server which only allows incoming HTTP traffic on the server. Please note this transport will not be as performant as the bisocket transport due to the nature of polling and the HTTP protocl. Also please note it is not designed for high load situations.

No other remoting transports are currently supported by JBoss Messaging

You can look at remoting configuration under:

<JBoss>/server/<YourMessagingServer>/deploy/jboss-messaging.sar/remoting-bisocket-service.xml

Here is an example bisocket remoting configuration:

         <config>
            <invoker transport="bisocket">
            
               <!-- There should be no reason to change these parameters - warning!
                    Changing them may stop JBoss Messaging working correctly -->            
               <attribute name="marshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
               <attribute name="unmarshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
               <attribute name="dataType" isParam="true">jms</attribute>
               <attribute name="socket.check_connection" isParam="true">false</attribute>
               <attribute name="timeout" isParam="true">0</attribute>
               <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
               <attribute name="serverBindPort">4457</attribute>
               <attribute name="clientSocketClass" isParam="true">org.jboss.jms.client.remoting.ClientSocketWrapper</attribute>
               <attribute name="serverSocketClass" isParam="true">org.jboss.jms.server.remoting.ServerSocketWrapper</attribute>
               <attribute name="numberOfCallRetries" isParam="true">1</attribute>
               <attribute name="pingFrequency" isParam="true">214748364</attribute>
               <attribute name="pingWindowFactor" isParam="true">10</attribute>
               <attribute name="onewayThreadPool">org.jboss.jms.server.remoting.DirectThreadPool</attribute>
               
               <!-- Periodicity of client pings. Server window by default is twice this figure -->                               
               <attribute name="clientLeasePeriod" isParam="true">10000</attribute>

               <!-- Number of seconds to wait for a connection in the client pool to become free -->
               <attribute name="numberOfRetries" isParam="true">10</attribute>

               <!-- Max Number of connections in client pool. This should be significantly higher than
                    the max number of sessions/consumers you expect -->
               <attribute name="clientMaxPoolSize" isParam="true">200</attribute>
               
               <!-- Use these parameters to specify values for binding and connecting control connections to 
                    work with your firewall/NAT configuration
               <attribute name="secondaryBindPort">xyz</attribute>                           
               <attribute name="secondaryConnectPort">abc</attribute>               
               -->
                              
            </invoker>
            <handlers>
               <handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>
            </handlers>
         </config>
      

Please note that some of the attributes should not be changed unless you know exactly what you are doing. We will discuss the attributes that you may have a good reason to change:

By default JBoss Messaging binds to ${jboss.bind.address} which can be defined by: ./run.sh -c <yourconfig> -b yourIP.

You can change remoting-bisocket-service.xml if you want for example use a different communication port.

If you are using the JBoss AS ServiceBindingManager to provide different servers with different port ranges, then you must make sure that the JBoss Messaging remoting configuration specified in the JBoss Messaging section of the ServiceBindingManager xml file exactly matches that in remoting-bisocket-service.xml.

If you are using a newer version of JBM in an older version of JBAS then the example bindings in the AS distribution may well be out of date. It is therefore imperative that the relevant sections are overwritten with the remoting configuration from the JBM distribution.

See the chapter on installation for a description of how to set-up the service binding manager for JBoss Messaging

JBoss Messaging includes a fully functional message bridge.

The function of the bridge is to consume messages from a source queue or topic, and send them to a target queue or topic, typically on a different server.

The source and target servers do not have to be in the same cluster which makes bridging suitable for reliably sending messages from one cluster to another, for instance across a WAN, and where the connection may be unreliable.

A bridge is deployed inside a JBoss AS instance. The instance can be the same instance as either the source or target server. Or could be on a third, separate JBoss AS instance.

A bridge is deployed as an MBean inside JBoss AS. Deployment is trivial - just drop the MBean descriptor into the deploy directory of a JBoss configuration which contains JBoss Messaging.

An example in docs/example/bridge demonstrates a simple bridge being deployed in JBoss AS, and moving messages from the source to the target destination

The bridge can also be used to bridge messages from other non JBoss Messaging JMS servers, as long as they are JMS 1.1 compliant.

The bridge has built in resilience to failure so if the source or target server connetion is lost, e.g. due to network failure, the bridge will retry connecting to the source and/or target until they come back online. When it comes back online it will resume operation as normal.

The bridge can be configured with an optional JMS selector, so it will only consume messages matching that JMS selector

It can be configured to consume from a queue or a topic. When it consumes from a topic it can be configured to consume using a non durable or durable subscription

The bridge can be configured to bridge messages with one of three levels of quality of service, they are:

A message bridge is easily deployed by dropping the MBean descriptor in the deploy directory of your JBoss AS installation which contains JBoss Messaging

In this section we describe how to configure the message bridge

Here is an example of a message bridge configuration, with all the attributes shown. Note that some are commented out for this configuration, since it is not appropriate to specify them all at once. Which ones are specified depends on the configuration you want.

   <mbean code="org.jboss.jms.server.bridge.BridgeService"
          name="jboss.messaging:service=Bridge,name=TestBridge"
          xmbean-dd="xmdesc/Bridge-xmbean.xml">
          
      <!-- The JMS provider loader that is used to lookup the source destination -->   
      <depends optional-attribute-name="SourceProviderLoader">
          jboss.messaging:service=JMSProviderLoader,name=JMSProvider</depends>
      
      <!-- The JMS provider loader that is used to lookup the target destination -->
      <depends optional-attribute-name="TargetProviderLoader">
          jboss.messaging:service=JMSProviderLoader,name=JMSProvider</depends>    
      
      <!-- The JNDI lookup for the source destination -->
      <attribute name="SourceDestinationLookup">/queue/A</attribute> 
      
      <!-- The JNDI lookup for the target destination -->
      <attribute name="TargetDestinationLookup">/queue/B</attribute>
      
      <!-- The username to use for the source connection 
      <attribute name="SourceUsername">bob</attribute>
      -->
      
      <!-- The password to use for the source connection
      <attribute name="SourcePassword">cheesecake</attribute>
      -->
      
      <!-- The username to use for the target connection
      <attribute name="TargetUsername">mary</attribute>
      -->
      
      <!-- The password to use for the target connection
      <attribute name="TargetPassword">hotdog</attribute>
      -->
      
      <!-- Optional: The Quality Of Service mode to use, one of:
           QOS_AT_MOST_ONCE = 0;
           QOS_DUPLICATES_OK = 1;
           QOS_ONCE_AND_ONLY_ONCE = 2; -->
      <attribute name="QualityOfServiceMode">0</attribute>
      
      <!-- JMS selector to use for consuming messages from the source
      <attribute name="Selector">specify jms selector here</attribute>
      -->
      
      <!-- The maximum number of messages to consume from the source
          before sending to the target -->
      <attribute name="MaxBatchSize">5</attribute>     
      
      <!-- The maximum time to wait (in ms) before sending a batch to the target
          even if MaxBatchSize is not exceeded.
           -1 means wait forever -->   
      <attribute name="MaxBatchTime">-1</attribute>
      
      <!-- If consuming from a durable subscription this is the subscription name
      <attribute name="SubName">mysub</attribute>
      -->
      
      <!-- If consuming from a durable subscription this is the client ID to use
      <attribute name="ClientID">myClientID</attribute>
      -->
      
      <!-- The number of ms to wait between connection retrues in the event connections
          to source or target fail -->
      <attribute name="FailureRetryInterval">5000</attribute>      
      
      <!-- The maximum number of connection retries to make in case of failure,
          before giving up -1 means try forever-->
      <attribute name="MaxRetries">-1</attribute>

      <!-- If true then the message id of the message before bridging will be added
          as a header to the message so it is available to the receiver. Can then be
          sent as correlation id to correlate in a distributed request-response -->
      <attribute name="AddMessageIDInHeader">false</attribute>
      
    </mbean>
      

We will now discuss each attribute