Chapter 6. Configuration

The JMS API specifies how a messaging client interacts with a messaging server. The exact definition and implementation of messaging services, such as message destinations and connection factories, are specific to JMS providers. JBoss Messaging has its own configuration files to configure services. If you are migrating services from JBossMQ (or other JMS provider) to JBoss Messaging, you will need to understand those configuration files.

In this chapter, we discuss how to configure various services inside JBoss Messaging, which work together to provide JMS API level services to client applications.

The JBoss Messaging service configuration is spread among several configuration files. Depending on the functionality provided by the services it configures, the configuration data is distributed between messaging-service.xml, remoting-bisocket-service.xml, xxx-persistence-service.xml (where xx is the name of your databse) , connection-factories-service.xml and destinations-service.xml.

The AOP client-side and server-side interceptor stacks are configured in aop-messaging-client.xml and aop-messaging-server.xml. Normally you will not want to change them, but some of the interceptors can be removed to give a small performance increase, if you don't need them. Be very careful you have considered the security implications before removing the security interceptor.

6.1. Configuring the ServerPeer

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

     <!-- ServerPeer MBean configuration
          ============================== -->
     <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 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>
      
      <!-- 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>
      
      <attribute name="EnableMessageCounters">false</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>
      <depends optional-attribute-name="SecurityStore" proxy-type="org.jboss.jms.server.SecurityStore">jboss.messaging:service=SecurityStore</depends>
          
   </mbean>

6.1.1. ServerPeer attributes

We now discuss the MBean attributes of the ServerPeer MBean.

6.1.1.1. ServerPeerID

The unique id of the server peer. Every node you deploy MUST have a unique id. This applies whether the different nodes form a cluster, or are only linked via a message bridge. The id must be a valid integer.

6.1.1.2. DefaultQueueJNDIContext

The default JNDI context to use when binding queues. Defaults to /queue.

6.1.1.3. DefaultTopicJNDIContext

The default JNDI context to use when binding topics.wa Defaults to /topic.

6.1.1.4. PostOffice

This is the post office that the ServerPeer uses. You will not normally need to change this attribute. The post office is responsible for routing messages to queues and maintaining the mapping between addresses and queues.

6.1.1.5. DefaultDLQ

This is the name of the default DLQ (Dead Letter Queue) the server peer will use for destinations. The DLQ can be overridden on a per destination basis - see the destination MBean configuration for more details. A DLQ is a special destination where messages are sent when the server has attempted to deliver them unsuccessfully more than a certain number of times. If the DLQ is not specified at all then the message will be removed after the maximum number of delivery attempts. The maximum number of delivery attempts can be specified using the attribute DefaultMaxDeliveryAttempts for a global default or individually on a per destination basis.

6.1.1.6. DefaultMaxDeliveryAttempts

The default for the maximum number of times delivery of a message will be attempted before sending the message to the DLQ, if configured.

The default value is 10.

This value can also be overridden on a per destination basis.

6.1.1.7. DefaultExpiryQueue

This is the name of the default expiry queue the server peer will use for destinations. The expiry can be overridden on a per destination basis - see the destination MBean configuration for more details. An expiry queue is a special destination where messages are sent when they have expired. Message expiry is determined by the value of Message::getJMSExpiration() If the expiry queue is not specified at all then the message will be removed after it is expired.

6.1.1.8. DefaultRedeliveryDelay

When redelivering a message after failure of previous delivery it is often beneficial to introduce a delay perform redelivery in order to prevent thrashing of delivery-failure, delivery-failure etc

The default value is 0 which means there will be no delay.

Change this if your application could benefit with a delay before redelivery. This value can also be overridden on a per destination basis.

6.1.1.9. MessageCounterSamplePeriod

Periodically the server will query each queue to gets its statistics. This is the period.

The default value is 10000 milliseconds.

6.1.1.10. FailoverStartTimeout

The maximum number of milliseconds the client will wait for failover to start on the server side when a problem is detected.

The default value is 60000 (one minute).

6.1.1.11. FailoverCompleteTimeout

The maximum number of milliseconds the client will wait for failover to complete on the server side after it has started.

The default value is 300000 (five minutes).

6.1.1.12. DefaultMessageCounterHistoryDayLimit

JBoss Messaging provides a message counter history which shows the number of messages arriving on each queue of a certain number of days. This attribute represents the maxiumum number of days for which to store message counter history. It can be overridden on a per destination basis.

6.1.1.13. ClusterPullConnectionFactory

The name of the connection factory to use for pulling messages between nodes.

If you wish to turn off message sucking between queues altogether, but retain failover, then you can ommit this attribute altogether

6.1.1.14. DefaultPreserveOrdering

If true, then strict JMS ordering is preserved in the cluster. See the cluster configurations section for more details. Default is false.

6.1.1.15. RecoverDeliveriesTimeout

When failover occurs, already delivered messages will be kept aside, waiting for clients to reconnect. In the case that clients never reconnect (e.g. the client is dead) then eventually these messages will timeout and be added back to the queue. The value is in ms. The default is 5 mins.

6.1.1.16. EnableMessageCounters

Set this to true to enable message counters when the server starts

6.1.1.17. SuckerPassword

JBoss Messaging internally makes connections between nodes in order to redistribute messages between clustered destinations. These connections are made with the user name of a special reserved user. On this parameter you define the password used as these connections are made. After JBossMessaging 1.4.1.GA you will need to define the Sucker Password on the ServerPeer and on the SecurityMetadataStore.

Warning

This must be specified at install time, or the default password will be used. Any one who then knows the default password will be able to gain access to any destinations on the server. This value MUST be changed at install time.

6.1.1.18. SuckerConnectionRetryTimes

Maximum times for a sucker's connection to retry in case of failure. Default is -1 (retry forever)

6.1.1.19. SuckerConnectionRetryInterval

The interval in milliseconds between each retry of the failed sucker's connection. Default is 5000.

6.1.1.20. StrictTCK

Set to true if you want strict JMS TCK semantiocs

6.1.1.21. Destinations

Returns a list of the destinations (queues and topics) currently deployed.

6.1.1.22. MessageCounters

JBoss Messaging provides a message counter for each queue.

6.1.1.23. MessageStatistics

JBoss Messaging provides statistics for each message counter for each queue.

6.1.1.24. SupportsFailover

Set to false to prevent server side failover occurring in a cluster when a node crashes.

6.1.1.25. PersistenceManager

This is the persistence manager that the ServerPeer uses. You will not normally need to change this attribute.

6.1.1.26. JMSUserManager

This is the JMS user manager that the ServerPeer uses. You will not normally need to change this attribute.

6.1.1.27. SecurityStore

This is the pluggable SecurityStore. If you redefine this SecurityStore, notice it will need to authenticate the MessageSucker user ("JBM.SUCKER") with all the special permissions required by clustering.

6.1.1.28. We now discuss the MBean operations of the ServerPeer MBean.

6.1.1.28.1. DeployQueue

This operation lets you programmatically deploy a queue.

There are two overloaded versions of this operation

If the queue already exists but is undeployed it is deployed. Otherwise it is created and deployed.

The name parameter represents the name of the destination to deploy.

The jndiName parameter (optional) represents the full jndi name where to bind the destination. If this is not specified then the destination will be bound in <DefaultQueueJNDIContext>/<name>.

The first version of this operation deploys the destination with the default paging parameters. The second overloaded version deploys the destination with the specified paging parameters. See the section on configuring destinations for a discussion of what the paging parameters mean.

6.1.1.28.2. UndeployQueue

This operation lets you programmatically undeploy a queue.

The queue is undeployed but is NOT removed from persistent storage.

This operation returns true if the queue was successfull undeployed. otherwise it returns false.

6.1.1.28.3. DestroyQueue

This operation lets you programmatically destroy a queue.

The queue is undeployed and then all its data is destroyed from the database.

Warning

Be careful when using this method since it will delete all data for the queue.

This operation returns true if the queue was successfully destroyed. otherwise it returns false.

6.1.1.28.4. DeployTopic

This operation lets you programmatically deploy a topic.

There are two overloaded versions of this operation.

If the topic already exists but is undeployed it is deployed. Otherwise it is created and deployed.

The name parameter represents the name of the destination to deploy.

The jndiName parameter (optional) represents the full jndi name where to bind the destination. If this is not specified then the destination will be bound in <DefaultTopicJNDIContext>/<name>.

The first version of this operation deploys the destination with the default paging parameters. The second overloaded version deploys the destination with the specified paging parameters. See the section on configuring destinations for a discussion of what the paging parameters mean.

6.1.1.28.5. UndeployTopic

This operation lets you programmatically undeploy a topic.

The queue is undeployed but is NOT removed from persistent storage.

This operation returns true if the topic was successfully undeployed. otherwise it returns false.

6.1.1.28.6. DestroyTopic

This operation lets you programmatically destroy a topic.

The topic is undeployed and then all its data is destroyed from the database.

Warning

Be careful when using this method since it will delete all data for the topic.

This operation returns true if the topic was successfully destroyed. otherwise it returns false.

6.1.1.28.7. ListMessageCountersHTML

This operation returns message counters in an easy to display HTML format.

6.1.1.28.8. ResetAllMesageCounters

This operation resets all message counters to zero.

6.1.1.28.9. ResetAllMesageCounters

This operation resets all message counter histories to zero.

6.1.1.28.10. EnableMessageCounters

This operation enables all message counters for all destinations. Message counters are disabled by default.

6.1.1.28.11. DisableMessageCounters

This operation disables all message counters for all destinations. Message counters are disabled by default.

6.1.1.28.12. RetrievePreparedTransactions

Retrieves a list of the Xids for all transactions currently in a prepared state on the node.

6.1.1.28.13. ShowPreparedTransactions

Retrieves a list of the Xids for all transactions currently in a prepared state on the node in an easy to display HTML format.

6.2. Changing the Database

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.

6.3. Configuring the Post office

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>
      
      
      <!-- If true then we will automatically detect and reject duplicate messages sent during failover -->
      
      <attribute name="DetectDuplicates">true</attribute>
      
      <!-- The size of the id cache to use when detecting duplicate messages -->
      
      <attribute name="IDCacheSize">500</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>
      
      <!-- Set this to true if you want failover of connections to occur when a node is shut down -->
      
      <attribute name="FailoverOnNodeLeave">false</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>
      

6.3.1. The post office has the following attributes

6.3.1.1. DataSource

The datasource the postoffice should use for persisting its mapping data.

6.3.1.2. SQLProperties

This is where the DDL and DML for the particular database is specified. If a particular DDL or DML statement is not overridden, the default Hypersonic configuration will be used for that statement.

6.3.1.3. CreateTablesOnStartup

Set this to true if you wish the post office to attempt to create the tables (and indexes) when it starts. If the tables (or indexes) already exist a SQLException will be thrown by the JDBC driver and ignored by the Persistence Manager, allowing it to continue.

By default the value of CreateTablesOnStartup attribute is set to true

6.3.1.4. DetectDuplicates

Set this to true if you wish the post office detect duplicate messages that may sent when a send is retried on a different node after server failure.

By default the value of DetectDuplicates attribute is set to true

6.3.1.5. IDCacheSize

If duplicate detection is enabled. (See DetectDuplicates), then the server will rememeber the last n message ids sent, to prevent duplicate messages sent after failover has occurred. The value of n is determined by this attribute.

By default the value of IDCacheSize attribute is set to 500

6.3.1.6. PostOfficeName

The name of the post office.

6.3.1.7. NodeIDView

This returns set containing the node ids of all the nodes in the cluster.

6.3.1.8. GroupName

All post offices in the cluster with the same group name will form a cluster together. Make sure the group name matches with all the nodes in the cluster you want to form a cluster with.

6.3.1.9. Clustered

If true the post office will take part in a cluster to form distributed queues and topics. If false then it will not participate in the cluster. If false, then all the cluster related attributes will be ignored.

6.3.1.10. StateTimeout

The maximum time to wait when waiting for the group state to arrive when a node joins a pre-existing cluster.

The default value is 5000 milliseconds.

6.3.1.11. CastTimeout

The maximum time to wait for a reply casting message synchronously.

The default value is 5000 milliseconds.

6.3.1.12. FailoverOnNodeLeave

If this attribute is true then if a server node is shut down cleanly, then this will cause any connections on the shutting down node to failover onto another node.

The default value for this is attribute is false

6.3.1.13. MaxConcurrentReplications

The maximum number of concurrent replication requests to make before blocking for replies to come back. This prevents us overwhelming JGroups. This is rarely a good reason to change this.

The default value is 50

6.3.1.14. ControlChannelConfig

JBoss Messaging uses JGroups for all group management. This contains the JGroups stack configuration for the control channel.

The control channel is used for sending request/receiving responses from other nodes in the cluster

The details of the JGroups configuration won't be discussed here since it is standard JGroups configuration. Detailed information on JGroups can be found in JGroups release documentation or on-line at http://www.jgroups.org or http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups.

6.3.1.15. DataChannelConfig

JBoss Messaging uses JGroups for all group management. This contains the JGroups stack configuration for the data channel.

The data channel is used for sending sending/receiving messages from other nodes in the cluster and for replicating session data.

The details of the JGroups configuration won't be discussed here since it is standard JGroups configuration. Detailed information on JGroups can be found in JGroups release documentation or on-line at http://www.jgroups.org or http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups.

6.4. Configuring the Persistence Manager

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.

Warning

The default Persistence Manager configuration works out of the box with Hypersonic, however it must be stressed that Hypersonic should not be used in a production environment mainly due to its limited support for transaction isolation and its propensity to behave erratically under high load.

The Critique of Hypersonic wiki page outlines some of the well-known issues occuring when using this database.

JBoss Messaging also ships with pre-made Persistence Manager configurations for MySQL, Oracle, PostgreSQL, Sybase, MS SQL Server and DB2. The example mysql-persistence-service.xml, ndb-persistence-service.xml, oracle-persistence-service.xml, postgres-persistence-service.xml, sybase-persistence-service.xml, mssql-persistence-service.xml and db2-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.

JBoss Messaging also ships with a Null Persistence Manager config - this can be used when you don't want any persistence at all.

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, 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, 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, HEADERS, PAYLOAD) SELECT ?, ?, ?, ?, ?, ?, ?, ? FROM JBM_DUAL WHERE NOT EXISTS (SELECT MESSAGE_ID FROM JBM_MSG WHERE MESSAGE_ID = ?)   
   MESSAGE_ID_COLUMN=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>

      <attribute name="UseNDBFailoverStrategy">true</attribute>
         
   </mbean>
	  
	   

6.4.1. Important notes for Sybase and Microsoft SQL Server users

Note

When a database is created in Sybase the maximum size of text and image datatypes is set to the default page size of 2 KB. Any longer message payload is truncated without any information or warning. The database parameters have to be updated to set the @@TEXTSIZE parameter to a higher value. The truncation behaviour may also be observed in MSSQL Server if @@TEXTSIZE is changed from its default value to a smaller one. Further information: http://jira.jboss.com/jira/browse/SOA-554.

Note

Sybase database may fail to insert a row if the total size of the row exceeds the page size allocated for the database. A command line option passed to the dataserver command used to start the database can be used to change the page size. Further information: http://jira.jboss.com/jira/browse/SOA-553

Note

Microsoft SQL Server does not automatically de-allocate the hard-drive space occupied by data in a database when that data is deleted. If used as a data-store for services that temporarily store many records, such as a messaging service, the disk space used will grow to be much greater than the amount of data actually being stored. Your database administrator should implement database maintenance plans to ensure that unused space is reclaimed. Please refer to your Microsoft SQL Server documentation for the DBCC commands ShrinkDatabase and UpdateUsage for guidance. https://jira.jboss.org/jira/browse/SOA-629

6.4.2. We now discuss the MBean attributes of the PersistenceManager MBean

6.4.2.1. CreateTablesOnStartup

Set this to true if you wish the Persistence Manager to attempt to create the tables (and indexes) when it starts. If the tables (or indexes) already exist a SQLException will be thrown by the JDBC driver and ignored by the Persistence Manager, allowing it to continue.

By default the value of CreateTablesOnStartup attribute is set to true

6.4.2.2. UsingBatchUpdates

Set this to true if the database supports JDBC batch updates. The JDBC Persistence Manager will then group multiple database updates in batches to aid performance.

By default the value of UsingBatchUpdates attribute is set to false

6.4.2.3. UsingBinaryStream

Set this to true if you want messages to be store and read using a JDBC binary stream rather than using getBytes(), setBytes(). Some database has limits on the maximum number of bytes that can be get/set using getBytes()/setBytes().

By default the value of UsingBinaryStream attribute is set to true

6.4.2.4. UsingTrailingByte

Certain version of Sybase are known to truncate blobs if they have trailing zeros. To prevent this if this attribute is set to true then a trailing non zero byte will be added and removed to each blob before and after persistence to prevent the database from truncating it. Currently this is only known to be necessary for Sybase.

By default the value of UsingTrailingByte attribute is set to false

6.4.2.5. SupportsBlobOnSelect

Oracle (and possibly other databases) is known to not allow BLOBs to be inserted using a INSERT INTO ... SELECT FROM statement, and requires a two stage conditional insert of messages. If this value is false then such a two stage insert will be used.

By default the value of SupportsBlobOnSelect attribute is set to true

6.4.2.6. SQLProperties

This is where the DDL and DML for the particular database is specified. If a particular DDL or DML statement is not overridden, the default Hypersonic configuration will be used for that statement.

6.4.2.7. MaxParams

When loading messages the persistence manager will generate prepared statements with many parameters. This value tells the persistence manager what the absolute maximum number of parameters are allowable per prepared statement.

By default the value of MaxParams attribute is set to 100

6.4.2.8. UseNDBFailoverStrategy

When running in a clustered database environment it is possible that some databases, MySQL for instance, can fail during the commit of a database transaction. This can happen if the database node dies whilst committing meaning that the final state of the transaction is unknown. If this attribute is set to true and the above happens then the SQL statement will be re-executed, however if there is a further error an assumption is made that this is because the previous transaction committed successfully and the error is ignored.

By default the value of UseNDBFailoverStrategy attribute is set to false

6.5. Configuring the JMS user manager

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>
           

6.5.1. We now discuss the MBean attributes of the JMSUserManager MBean

6.5.1.1. CreateTablesOnStartup

Set this to true if you wish the JMS user manager to attempt to create the tables (and indexes) when it starts. If the tables (or indexes) already exist a SQLException will be thrown by the JDBC driver and ignored by the Persistence Manager, allowing it to continue.

By default the value of CreateTablesOnStartup attribute is set to true

6.5.1.2. UsingBatchUpdates

Set this to true if the database supports JDBC batch updates. The JDBC Persistence Manager will then group multiple database updates in batches to aid performance.

By default the value of UsingBatchUpdates attribute is set to false

6.5.1.3. SQLProperties

This is where the DDL and DML for the particular database is specified. If a particular DDL or DML statement is not overridden, the default Hypersonic configuration will be used for that statement.

Default user and role data can also be specified here. Any data to be inserted must be specified with property names starting with POPULATE.TABLES as in the above example.

6.6. Configuring Destinations

6.6.1. Pre-configured destinations

JBoss Messaging ships with a default set of pre-configured destinations that will be deployed during the server start up. The file that contains configuration for these destinations is destinations-service.xml. A section of this file is listed below:

   <!--
      The Default Dead Letter Queue. This destination is a dependency of an EJB MDB container.
   -->

   <mbean code="org.jboss.jms.server.destination.QueueService"
      name="jboss.messaging.destination:service=Queue,name=DLQ"
      xmbean-dd="xmdesc/Queue-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                  jboss.messaging:service=ServerPeer
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>
   </mbean>


   <mbean code="org.jboss.jms.server.destination.TopicService"
      name="jboss.messaging.destination:service=Topic,name=testTopic"
      xmbean-dd="xmdesc/Topic-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                  jboss.messaging:service=ServerPeer
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>
      <attribute name="SecurityConfig">
         <security>
            <role name="guest" read="true" write="true"/>
            <role name="publisher" read="true" write="true" create="false"/>
            <role name="durpublisher" read="true" write="true" create="true"/>
         </security>
      </attribute>
   </mbean>

   <mbean code="org.jboss.jms.server.destination.TopicService"
      name="jboss.messaging.destination:service=Topic,name=securedTopic"
      xmbean-dd="xmdesc/Topic-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                  jboss.messaging:service=ServerPeer
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>
      <attribute name="SecurityConfig">
         <security>
            <role name="publisher" read="true" write="true" create="false"/>
         </security>
      </attribute>
   </mbean>


   <mbean code="org.jboss.jms.server.destination.QueueService"
      name="jboss.messaging.destination:service=Queue,name=testQueue"
      xmbean-dd="xmdesc/Queue-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                  jboss.messaging:service=ServerPeer
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>
      <attribute name="SecurityConfig">
         <security>
            <role name="guest" read="true" write="true"/>
            <role name="publisher" read="true" write="true" create="false"/>
            <role name="noacc" read="false" write="false" create="false"/>
         </security>
      </attribute>
   </mbean>

   <mbean code="org.jboss.jms.server.destination.QueueService"
      name="jboss.messaging.destination:service=Queue,name=A"
      xmbean-dd="xmdesc/Queue-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                  jboss.messaging:service=ServerPeer
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>
   </mbean>


   <!-- It's possible for indiviual queues and topics to use a specific queue for
   an expiry or DLQ -->

   <mbean code="org.jboss.jms.server.destination.QueueService"
      name="jboss.messaging.destination:service=Queue,name=PrivateDLQ"
      xmbean-dd="xmdesc/Queue-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                  jboss.messaging:service=ServerPeer
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>
   </mbean>

   <mbean code="org.jboss.jms.server.destination.QueueService"
      name="jboss.messaging.destination:service=Queue,name=PrivateExpiryQueue"
      xmbean-dd="xmdesc/Queue-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                  jboss.messaging:service=ServerPeer
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>
   </mbean>

   <mbean code="org.jboss.jms.server.destination.QueueService"
      name="jboss.messaging.destination:service=Queue,name=QueueWithOwnDLQAndExpiryQueue"
      xmbean-dd="xmdesc/Queue-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                  jboss.messaging:service=ServerPeer
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>
      <attribute name="DLQ">
                  jboss.messaging.destination:service=Queue,name=PrivateDLQ
      </attribute>
      <attribute name="ExpiryQueue">
                  jboss.messaging.destination:service=Queue,name=PrivateExpiryQueue
      </attribute>
   </mbean>

   <mbean code="org.jboss.jms.server.destination.TopicService"
      name="jboss.messaging.destination:service=Topic,name=TopicWithOwnDLQAndExpiryQueue"
      xmbean-dd="xmdesc/Topic-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                  jboss.messaging:service=ServerPeer
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>
      <attribute name="DLQ">
                  jboss.messaging.destination:service=Queue,name=PrivateDLQ
      </attribute>
      <attribute name="ExpiryQueue">
                  jboss.messaging.destination:service=Queue,name=PrivateExpiryQueue
      </attribute>
   </mbean>


   <mbean code="org.jboss.jms.server.destination.TopicService"
      name="jboss.messaging.destination:service=Topic,name=TopicWithOwnRedeliveryDelay"
      xmbean-dd="xmdesc/Topic-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                  jboss.messaging:service=ServerPeer
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>
      <attribute name="RedeliveryDelay">5000</attribute>
   </mbean>


   <mbean code="org.jboss.jms.server.destination.TopicService"
      name="jboss.messaging.destination:service=Topic,name=testDistributedTopic"
      xmbean-dd="xmdesc/Topic-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">
                  jboss.messaging:service=ServerPeer
      </depends>
      <depends>jboss.messaging:service=PostOffice</depends>
      <attribute name="Clustered">true</attribute>
   </mbean>
....
              

6.6.2. Configuring queues

6.6.2.1. We now discuss the attributes of the Queue MBean

6.6.2.1.1. Name

The name of the queue

6.6.2.1.2. JNDIName

The JNDI name where the queue is bound

6.6.2.1.3. DLQ

The DLQ used for this queue. Overrides any value set on the ServerPeer config

6.6.2.1.4. ExpiryQueue

The Expiry queue used for this queue. Overrides any value set on the ServerPeer config

6.6.2.1.5. RedeliveryDelay

The redelivery delay to be used for this queue. Overrides any value set on the ServerPeer config

6.6.2.1.6. MaxDeliveryAttempts

The maximum number of times delivery of a message will be attempted before sending the message to the DLQ, if configured. If set to -1 (the default), the value from the ServerPeer config is used. Any other setting overrides the value set on the ServerPeer config.

6.6.2.1.7. Destination Security Configuration

SecurityConfig - allows you to determine which roles are allowed to read, write and create on the destination. It has exactly the same syntax and semantics as the security configuration in JBossMQ destinations.

The SecurityConfig element should contain one <security> element. The <security> element can contain multiple <role> elements. Each <role> element defines the access for that particular role.

If the read attribute is true then that role will be able to read (create consumers, receive messaages or browse) this destination.

If the write attribute is true then that role will be able to write (create producers or send messages) to this destination.

If the create attribute is true then that role will be able to create durable subscriptions on this destination.

Note that the security configuration for a destination is optional. If a SecurityConfig element is not specifed then the default security configuration from the Server Peer will be used.

6.6.2.1.8. Destination paging parameters

'Pageable Channels' are a sophisticated new feature available in JBoss Messaging.

If your application needs to support very large queues or subscriptions containing potentially millions of messages, then it's not possible to store them all in memory at once.

JBoss Messaging solves this problem but letting you specify the maximum number of messages that can be stored in memory at any one time, on a queue-by-queue, or topic-by-topic basis. JBoss Messaging then pages messages to and from storage transparently in blocks, allowing queues and subscriptions to grow to very large sizes without any performance degradation as channel size increases.

This has been tested with in excess of 10 million 2K messages on very basic hardware and has the potential to scale to much larger number of messages.

The individual parameters are:

FullSize - this is the maximum number of messages held by the queue or topic subscriptions in memory at any one time. The actual queue or subscription can hold many more messages than this but these are paged to and from storage as necessary as messages are added or consumed.

PageSize - When loading messages from the queue or subscrition this is the maximum number of messages to pre-load in one operation.

DownCacheSize - When paging messages to storage from the queue they first go into a "Down Cache" before being written to storage. This enables the write to occur as a single operation thus aiding performance. This setting determines the max number of messages that the Down Cache will hold before they are flushed to storage.

If no values for FullSize, PageSize, or DownCacheSize are specified they will default to values 75000, 2000, 2000 respectively.

If you want to specify the paging parameters used for temporary queues then you need to specify them on the appropriate connection factory. See connection factory configuration for details.

6.6.2.1.9. CreatedProgrammatically

Returns true if the queue was created programmatically

6.6.2.1.10. MessageCount

Returns the total number of messages in the queue = number not being delivered + number being delivered + number being scheduled

6.6.2.1.11. ScheduledMessageCount

Returns the number of scheduled messages in the queue. This is the number of messages scheduled to be delivered at a later date.

Scheduled delivery is a feature of JBoss Messaging where you can send a message and specify the earliest time at which it will be delivered. E.g. you can send a message now, but the message won't actually be delivered until 2 hours time.

To do this, you just need to set the following header in the message before sending:

              
              long now = System.currentTimeMillis();
         
              Message msg = sess.createMessage();  
                  
              msg.setLongProperty(JBossMessage.JMS_JBOSS_SCHEDULED_DELIVERY_PROP_NAME,
                     now + 1000 * 60 * 60 * 2);
              
              prod.send(msg);
                            
                 
6.6.2.1.12. MaxSize

A maximum size (in number of messages) can be specified for a queue. Any messages that arrive beyond this point will be dropped. The default is -1 which is unbounded.

6.6.2.1.13. Clustered

Clustered destinations must have this set to true.

6.6.2.1.14. MessageCounter

Each queue maintains a message counter.

6.6.2.1.15. MessageCounterStatistics

The statistics for the message counter

6.6.2.1.16. MessageCounterHistoryDayLimit

The maximum number of days to hold message counter history for. Overrides any value set on the ServerPeer.

6.6.2.1.17. ConsumerCount

The number of consumers currently consuming from the queue.

6.6.2.2. We now discuss the MBean operations of the Queue MBean

6.6.2.2.1. RemoveAllMessages

Remove (and delete) all messages from the queue.

Warning

Use this with caution. It will permanently delete all messages from the queue

.

6.6.2.2.2. ListAllMessages

List all messages currently in the queue

There are two overloaded versions of this operation: One takes a JMS selector as an argument, the other does not. By using the selector you can retrieve a subset of the messages in the queue that match the criteria

6.6.2.2.3. ListDurableMessages

As listAllMessages but only lists the durable messages

There are two overloaded versions of this operation: One takes a JMS selector as an argument, the other does not. By using the selector you can retrieve a subset of the messages in the queue that match the criteria

6.6.2.2.4. ListNonDurableMessages

As listAllMessages but only lists the non durable messages

There are two overloaded versions of this operation: One takes a JMS selector as an argument, the other does not. By using the selector you can retrieve a subset of the messages in the queue that match the criteria

6.6.2.2.5. ResetMessageCounter

Resets the message counter to zero.

6.6.2.2.6. ResetMessageCounterHistory

Resets the message counter history.

6.6.2.2.7. ListMessageCounterAsHTML

Lists the message counter in an easy to display HTML format

6.6.2.2.8. ListMessageCounterHistoryAsHTML

Lists the message counter history in an easy to display HTML format

6.6.3. Configuring topics

6.6.3.1. We now discuss the MBean attributes of the Topic MBean

6.6.3.1.1. Name

The name of the topic

6.6.3.1.2. JNDIName

The JNDI name where the topic is bound

6.6.3.1.3. DLQ

The DLQ used for this topic. Overrides any value set on the ServerPeer config

6.6.3.1.4. ExpiryQueue

The Expiry queue used for this topic. Overrides any value set on the ServerPeer config

6.6.3.1.5. RedeliveryDelay

The redelivery delay to be used for this topic. Overrides any value set on the ServerPeer config

6.6.3.1.6. MaxDeliveryAttempts

The maximum number of times delivery of a message will be attempted before sending the message to the DLQ, if configured. If set to -1 (the default), the value from the ServerPeer config is used. Any other setting overrides the value set on the ServerPeer config.

6.6.3.1.7. Destination Security Configuration

SecurityConfig - allows you to determine which roles are allowed to read, write and create on the destination. It has exactly the same syntax and semantics as the security configuration in JBossMQ destinations.

The SecurityConfig element should contain one <security> element. The <security> element can contain multiple <role> elements. Each <role> element defines the access for that particular role.

If the read attribute is true then that role will be able to read (create consumers, receive messaages or browse) this destination.

If the write attribute is true then that role will be able to write (create producers or send messages) to this destination.

If the create attribute is true then that role will be able to create durable subscriptions on this destination.

Note that the security configuration for a destination is optional. If a SecurityConfig element is not specifed then the default security configuration from the Server Peer will be used.

6.6.3.1.8. Destination paging parameters

'Pageable Channels' are a sophisticated new feature available in JBoss Messaging.

If your application needs to support very large queues or subscriptions containing potentially millions of messages, then it's not possible to store them all in memory at once.

JBoss Messaging solves this problem but letting you specify the maximum number of messages that can be stored in memory at any one time, on a queue-by-queue, or topic-by-topic basis. JBoss Messaging then pages messages to and from storage transparently in blocks, allowing queues and subscriptions to grow to very large sizes without any performance degradation as channel size increases.

This has been tested with in excess of 10 million 2K messages on very basic hardware and has the potential to scale to much larger number of messages.

The individual parameters are:

FullSize - this is the maximum number of messages held by the queue or topic subscriptions in memory at any one time. The actual queue or subscription can hold many more messages than this but these are paged to and from storage as necessary as messages are added or consumed.

PageSize - When loading messages from the queue or subscrition this is the maximum number of messages to pre-load in one operation.

DownCacheSize - When paging messages to storage from the queue they first go into a "Down Cache" before being written to storage. This enables the write to occur as a single operation thus aiding performance. This setting determines the max number of messages that the Down Cache will hold before they are flushed to storage.

If no values for FullSize, PageSize, or DownCacheSize are specified they will default to values 75000, 2000, 2000 respectively.

If you want to specify the paging parameters used for temporary queues then you need to specify them on the appropriate connection factory. See connection factory configuration for details.

6.6.3.1.9. CreatedProgrammatically

Returns true if the topic was created programmatically

6.6.3.1.10. MaxSize

A maximum size (in number of messages) can be specified for a topic subscription. Any messages that arrive beyond this point will be dropped. The default is -1 which is unbounded.

6.6.3.1.11. Clustered

Clustered destinations must have this set to true

6.6.3.1.12. MessageCounterHistoryDayLimit

The maximum number of days to hold message counter history for. Overrides any value set on the ServerPeer.

6.6.3.1.13. MessageCounters

Return a list of the message counters for the subscriptions of this topic.

6.6.3.1.14. AllMessageCount

Return the total number of messages in all subscriptions of this topic.

6.6.3.1.15. DurableMessageCount

Return the total number of durable messages in all subscriptions of this topic.

6.6.3.1.16. NonDurableMessageCount

Return the total number of non durable messages in all subscriptions of this topic.

6.6.3.1.17. AllSubscriptionsCount

The count of all subscriptions on this topic

6.6.3.1.18. DurableSubscriptionsCount

The count of all durable subscriptions on this topic

6.6.3.1.19. NonDurableSubscriptionsCount

The count of all non durable subscriptions on this topic

6.6.3.2. We now discuss the MBean operations of the Topic MBean

6.6.3.2.1. RemoveAllMessages

Remove (and delete) all messages from the subscriptions of this topic.

Warning

Use this with caution. It will permanently delete all messages from the topic
6.6.3.2.2. ListAllSubscriptions

List all subscriptions of this topic

6.6.3.2.3. ListDurableSubscriptions

List all durable subscriptions of this topic

6.6.3.2.4. ListNonDurableSubscriptions

List all non durable subscriptions of this topic

6.6.3.2.5. ListAllSubscriptionsAsHTML

List all subscriptions of this topic in an easy to display HTML format

6.6.3.2.6. ListDurableSubscriptionsAsHTML

List all durable subscriptions of this topic in an easy to display HTML format

6.6.3.2.7. ListNonDurableSubscriptionsAsHTML

List all non durable subscriptions of this topic in an easy to display HTML format

6.6.3.2.8. ListAllMessages

Lists all messages for the specified subscription.

There are two overloaded versions of this operation. One that takes a selector and one that does not. By specifyingthe selector you can limit the messages returned.

6.6.3.2.9. ListNonDurableMessages

Lists all non durable messages for the specified subscription.

There are two overloaded versions of this operation. One that takes a selector and one that does not. By specifyingthe selector you can limit the messages returned.

6.6.3.2.10. ListDurableMessages

Lists all durable messages for the specified subscription.

There are two overloaded versions of this operation. One that takes a selector and one that does not. By specifyingthe selector you can limit the messages returned.

6.7. Configuring Connection Factories

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="SendAcksAsync">false</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.

6.7.1. We now discuss the MBean attributes of the ConnectionFactory MBean

6.7.1.1. ClientID

Connection factories can be pre-configured with a client id. Any connections created using this connection factory will obtain this client id

6.7.1.2. JNDIBindings

The list of the JNDI bindings for this connection factory

6.7.1.3. PrefetchSize

This parameter specifies the window size in numbers of messages, for consumer flow control. The window size determines the number of messages a server can send to a consumer without blocking. Each consumer maintains a buffer of messages from which it consumes. Please note that TCP also implements its own flow control, so if you set this to too large a number, then the TCP window size may be hit before the prefetchSize, which can cause writes to block.

6.7.1.4. SlowConsumers

If you have very slow consumers, then you probably want to reduce the number of messages they buffer so that unnecessary buffering does not prevent the messages from being consumed by faster consumers. It is not possible to completely disable buffering. The lowest PrefetchSize allowed is 1. Setting this to true is equivalent to setting PrefetchSize to 1

6.7.1.5. StrictTck

Set this to true if you want strict JMS behaviour as required by the TCK.

6.7.1.6. SendAcksAsync

Set this to true if you want acknowledgements to be sent asynchronously. This can speed up performance especially if you are using auto_acknowledge mode

6.7.1.7. Temporary queue paging parameters

DefaultTempQueueFullSize, DefaultTempQueuePageSize, DefaultTempQueueDownCacheSize are optional attributes that determine the default paging parameters to be used for any temporary destinations scoped to connections created using this connection factory. See the section on paging channels for more information on what these values mean. They will default to values of 200000, 2000 and 2000 respectively if ommitted.

6.7.1.8. DupsOKBatchSize

When using a session with acknowledge mode of DUPS_OK_ACKNOWLEDGE this setting determines how many acknowledgments it will buffer locally before sending. The default value is 2000

6.7.1.9. SupportsLoadBalancing

When using a connection factory with a clustered JBoss Messaging installation you can choose whether to enable client side connection load-balancing. This is determined by setting the attribute supportsLoadBalancing on the connection factory.

If load balancing is enabled on a connection factory then any connections created with that connection factory will be load-balanced across the nodes of the cluster. Once a connection is created on a particular node, it stays on that node.

The exact policy that determines how connections are load balanced is determined by the LoadBalancingFactory attribute

The default value is false

6.7.1.10. SupportsFailover

When using a connection factory with a clustered JBoss Messaging installation you can choose whether to enable client side automatic failover. This is determined by setting the attribute supportsFailover on the connection factory.

If automatic failover is enabled on a connection factory, then if a connection problem is detected with the connection then JBoss Messaging will automatically and transparently failover to another node in the cluster.

The failover is transparent meaning the user can carry on using the sessions, consumers, producers and connection objects as before.

If automatic failover is not required, then this attribute can be set to false. With automatic failover disabled it is up to the user code to catch connection exceptions in synchronous JMS operations and install a JMS ExceptionListener to catch exceptions asynchronously. When a connection is caught, the client side code should lookup a new connection factory using HAJNDI and recreate the connection using that.

The default value is false

6.7.1.11. DisableRemotingChecks

By default, when deploying a connection factory, JBoss Messaging checks that the corresponding JBoss Remoting Connector has "sensible" values. JBoss Messaging is very sensitive to the values and for many of them there's rarely a good reason to change them. To disable such sanity checking set this to false.

Warning

There is rarely a good reason to disable checking. Only do so if you are absolutely sure in what you are doing

The default value is false

6.7.1.12. LoadBalancingFactory

If you are using a connection factory with client side load balancing then you can specify how the load balancing is implemented by overriding this attribute. The value must correspond to the name of a class which implements the interface org.jboss.jms.client.plugin.LoadBalancingFactory

The default value is org.jboss.jms.client.plugin.RoundRobinLoadBalancingFactory, which load balances connetions across the cluster in a round-robin fashion

6.7.1.13. Connector

This specifies which remoting connector this connection factory uses. Different connection factories can use different connectors.

For instance you could deploy one connection factory that creates connections that use the HTTP transport to communicate to the server and another that creates connections that use the bisocket transport to communicate.

6.7.1.14. EnableOrderingGroup

This parameter controls whether the strict message ordering is enabled or not on the ConnectionFactory. If set to 'true', all messages that are sent from any producers created from this connection factory become ordering group messages.

The default value is false.

6.7.1.15. DefaultOrderingGroupName

the default name for the message ordering group. If absent, the group name will be generated automatically.

This attribute takes effect only if the EnableOrderingGroup attribute is true.

6.8. Configuring the remoting connector

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:

  • clientLeasePeriod - Clients periodically send heartbeats to the server to tell the server they are still alive. If the server does not receive a heartbeat after a certain time it will close down the connection and remove all resources on the server corresponding to the client's session. The clientLeasePeriod determines the period of heartbeats. The server will (by default) close a client if it does not receive a heartbeat in 2 * clientLeasePeriod ms. The actual factor gets automatically resized according to system load. The value is in milliseconds. The defaut value is 10000 ms.
  • numberOfRetries - This effectively corresponds to the number of seconds JBoss Remoting will block on the client connection pool waiting for a connection to become free. If you have a very large number of sessions concurrently accessing the server from a client and you are experiencing issues due to not being able to obtain connections from the pool, you may want to consider increasing this value.
  • clientMaxPoolSize - JBoss Remoting maintains a client side pool of TCP connections on which to service requests. If you have a very large number of sessions concurrently accessing the server from a client and you are experiencing issues due to not being able to obtain connections from the pool in a timely manner, you may want to consider increasing this value.
  • secondaryBindPort - The bisocket transport uses control connections to pass control messages between server and client. If you want to work behind a firewall you may want to specify a particular value for this according to your firewall configuration. This is the address the secondary ServerSocket binds to
  • secondaryConnectPort - This is the port the client uses to connect. You may want to specify this to allow clients to work with NAT routers.
  • maxPoolSize - This is the number of threads used on the server side to service requests.

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.

Warning

There is rarely a good reason to change values in the the bisocket or sslbisocket connector configuration apart from clientLeasePeriod, clientMaxPoolSize, maxRetries, numberOfRetries, secondaryBindPort or secondaryConnectPort. Changing them can cause JBoss Messaging to stop functioning correctly.

6.9. ServiceBindingManager

The service binding manager on JBoss is used to provide multiple application servers instances running on the same IP using different port ranges, which is very useful during development. You could have multiple IPs on the same server and bind each server on a different IP if you wanted to deal with OS configs, but case you prefer not dealing with OS configs you have the option of using the ServiceBindingManager.

On JBoss4 you must match the remoting configs accordingly to 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