Messaging User Guide
for use with JBoss Enterprise Application Platform 5
Edition 5.2.0
Andy Taylor
Clebert Suconic
Jeff Mesnil
Tim Fox
Howard Gao
Edited by
Eva Kopalova
Edited by
Jared Morgan
Edited by
Laura Bailey
Edited by
Petr Penicka
Edited by
Russell Dickenson
Edited by
Scott Mumford
Abstract
Chapter 1. About JBoss Messaging 1.4
Chapter 2. Introduction
2.1. JBoss Messaging Features
- A strong focus on performance, reliability and scalability with high throughput and low latency.
- A foundation for JBoss ESB for SOA initiatives. (JBoss ESB uses JBoss Messaging as its default JMS provider.)
- publish-subscribe and point-to-point messaging models;
- persistent and non-persistent messages;
- guaranteed message delivery that ensures messages arrive once and only once where required;
- a transactional and reliable interface that supports ACID semantics;
- a customizable JAAS-based security framework;
- complete integration with JBoss Transactions (previously Arjuna JTA) to support full transaction recovery;
- an extensive JMX management interface;
- support for most major databases, including Oracle, DB2, Sybase, Microsoft SQL Server, PostgreSQL and MySQL;
- HTTP transport, for use with firewalls that allow only HTTP traffic;
- servlet transport to allow messaging through a dedicated servlet;
- SSL transport;
- configurable Dead Letter Queues (DLQs) and Expiry Queues;
- message statistics; which provide a rolling historical view of the messages delivered to queues and subscriptions;
- the automatic paging of messages to storage, which lets you use very large queues that would be too large to fit entirely within system memory; and
- strict message ordering which results in messages belonging to a particular message group being delivered according to the order of their arrival at the target queue.
- Fully-clustered queues and topics
Logical queues and topics are distributed across the cluster. You can send or receive a queue or topic to or from any node on the cluster.
- Fully-clustered durable subscriptions
A particular durable subscription can be accessed from any node of the cluster, letting you spread processing load from that subscription across the entire cluster.
- Fully-clustered temporary queues
If a sent message includes the
replyTo
of a temporary queue, it can be returned on any node of the cluster. - Intelligent message redistribution
Messages are automatically moved between nodes of the cluster to take advantage of different consumer speeds on different nodes. This helps to prevent starvation or build-up of messages on a particular node.
- Message order protection
Enable this to ensure that the order of messages produced by a producer is identical to the order of messages consumed by a consumer. This works even if message redistribution is active.
- Completely transparent failover
When a server fails, your sessions continue exception-free on a new node. This is also completely configurable: if you do not want to implement this failover behavior, you can disable it and fall back to exceptions being thrown and manually recreating connections on a new node.
- High availability and seamless failover
If the node fails, you will automatically failover to a different node without losing any persistent messages and can seamlessly continue your session. Once and only once delivery of persistent messages is respected at all times.
- Message bridge
JBoss Messaging contains a message bridge component, which lets you bridge messages between any two JMS 1.1 destinations. This lets you connect geographically separate clusters and form large, globally-distributed logical queues and topics.
2.2. Compatibility with JBoss MQ
Important
2.3. System Properties used by JBoss Messaging
2.3.1. support.bytesId
JBossMessage
object from a foreign message object. Set this property when starting the server via the command line by using the -D
option.
true
, the JBossMessage
constructor will try to extract the native byte[] correlation ID from the foreign message headers. If set to false
, it will use the normal string type JMSCorrelationID
. This property will default to true
if not set or when set to something other than true
or false
.
2.3.2. retain.oldxabehaviour
prepare()
method is called after the connection is broken. Set this property when starting the server via the command line by using the -D
option.
XAException
with an XA_RBCOMMFAIL
error code will be thrown. Otherwise an XAException
with an XA_RETRY
error code will be thrown. It should be noted that JBoss Messaging does not define this property by default.
Chapter 3. JBoss Messaging Installation
Chapter 4. Examples
Task: Download JBoss Messaging Examples Zip
Prerequisites
- You have the correct entitlements for JBoss Enterprise Application Platform on access.redhat.com
- Log in to the Red Hat Customer Portal.
- Select Downloads → JBoss Enterprise Middleware → Downloads
- On the Software Downloads page, select Application Platform from the Product drop-down menu.The Version drop-down menu defaults to the latest release.
- Locate the Application Platform [version] Documentation entry, and click Download.
- The documentation bundle begins to download.
Related Information
Task: Unpack and Deploy Examples
- A running JBoss Enterprise Application Server instance with default settings.
- Open the zip archive using an archive utility appropriate for your operating system.
- In the zip archive manager, navigate to jboss-eap-5.1 → doc.
- Extract the examples directory to
$JBOSS_HOME/docs/examples
. - Open
$JBOSS_HOME/docs/examples/jboss-messaging-examples/destinations/
in a file browser. - Copy
jbm-examples-destinations-service.xml
to$JBOSS_HOME/server/default/deploy
to deploy the destinations configuration directives required by the examples.
Related Information
Unclustered Examples
Important
All
and Production
profiles are not supported.
readme.html
for each example provides the setup details, expected output, and simple troubleshooting.
- queue
- This example shows a simple send and receive to a remote queue using a JMS client
- topic
- This example shows a simple send and receive to a remote topic using a JMS client
- mdb
- This example demonstrates usage of an EJB2.1 MDB with JBoss Messaging
- ejb3mdb
- This example demonstrates usage of an EJB3 MDB with JBoss Messaging
- stateless
- This example demonstrates an EJB2.1 stateless session bean interacting with JBoss Messaging
- mdb-failure
- This example demonstrates rollback and redelivery occurring with an EJB2.1 MDB
- secure-socket
- This example demonstrates a JMS client interacting with a JBoss Messaging server using SSL encrypted transport
- http
- This example demonstrates a JMS client interacting with a JBoss Messaging server tunneling traffic over the HTTP protocol
- web-service
- This example demonstrates JBoss web-service interacting with JBoss Messaging
- stateless-clustered
- This example demonstrates a JMS client interacting with clustered EJB2.1 stateless session bean, which in turn interacts with JBoss Messaging. The example uses HAJNDI to look up the connection factory
- bridge
- This example demonstrates using a message bridge. It deploys a message bridge in EAP which then proceeds to move messages from a source to a target queue
- servlet
- This example demonstrates how to use servlet transport with JBoss Messaging. It deploys a servlet and a ConnectionFactory that uses the servlet transport.
- ordering-group
- This example demonstrates using strict message ordering with JBoss Messaging. It uses JBoss Messaging ordering group API to deliver strictly ordered messages, regardless of their priorities.
Clustered Examples
Important
All
and Production
server profiles.
readme.html
for each example provides the setup details, expected output, and simple troubleshooting.
- distributed-topic
- This example demonstrates a JMS client interacting with a JBoss Messaging distributed topic - it requires two EAP instances to be running
- distributed-queue
- This example demonstrates a JMS client interacting with a JBoss Messaging distributed queue - it requires two EAP instances to be running
- queue-failover
- This example demonstrates the transparent failover of a JMS consumer.
Chapter 5. Configuration
messaging-service.xml
, remoting-bisocket-service.xml
, <your database type>-persistence-service.xml
, connection-factories-service.xml
and destinations-service.xml
. These files can all be found in the $JBOSS_HOME/server/$PROFILE/deploy/messaging
directory.
aop-messaging-client.xml
(for client-side behavior) and aop-messaging-server.xml
(for server-side behavior). There is usually no need to change these files, but some interceptors can be removed to improve performance if they are not required. Ensure that you have considered the security implications before removing the security interceptor.
5.1. Configuring the ServerPeer
ServerPeer
is the heart of the JBoss Messaging JMS facade. You can configure its behavior by altering $JBOSS_HOME/server/$PROFILE/deploy/messaging/messaging-service.xml
.
ServerPeer
.
<!-- 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"> ${jboss.messaging.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 destination 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> <attribute name="StrictTck">false</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> <!-- Set to true to enable message counters that can be viewed via JMX --> <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> --> <!-- The name of the server aspects configuration resource <attribute name="ServerAopConfig">aop/jboss-aop-messaging-server.xml</attribute> --> <!-- The name of the client aspects configuration resource <attribute name="ClientAopConfig">aop/jboss-aop-messaging-client.xml</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>
5.2. ServerPeer attributes
ServerPeer
managed bean attributes.
- StopServerPeerOnDBFailure
- When set to
true
, the server will stop if a database error occurs - e.g. database connection is lost - allowing other nodes to continue work. The default value isfalse
. - ServerPeerID
- The unique identifier of the
ServerPeer
. Each node deployed must have a unique identifier, whether the nodes form a cluster or are linked by a message bridge. The identifier must be a valid integer. - DefaultQueueJNDIContext
- The default JNDI context to be used when binding queues. The default value is
/queue
. - DefaultTopicJNDIContext
- The default JNDI context to be used when binding topics. The default value is
/topic
. - PostOffice
- The post office used by the
ServerPeer
. You will not normally need to edit this attribute. The post office routes messages to queues and maintains the mapping between queues and addresses. - DefaultDLQ
- The default DLQ (Dead Letter Queue) that the server uses for destinations. You can override the DLQ on a per-destination basis. For more information about destinations, refer to Section 5.9, “Configuring Destinations”. A DLQ is a destination for messages that the server has failed to deliver more than a certain number of times. If the DLQ is not specified, the message will be removed after the maximum number of delivery attempts. You can specify a global default for the maximum number of delivery attempts with the
DefaultMaxDeliveryAttempts
attribute, or set the maximum individually on a per-destination basis. - DefaultMaxDeliveryAttempts
- The global default for the maximum number of times delivery will be attempted for a message before the message is removed or sent to the DLQ, if configured. The default value is
10
. You can override this value on a per-destination basis. - DefaultExpiryQueue
- The default expiry queue that the
ServerPeer
will use for destinations. You can override this value on a per-destination basis, as seen in the section on destination managed bean configuration. An expiry queue holds messages that have expired. Message expiry is determined by the value ofMessage::getJMSExpiration()
. If the expiry queue is not specified, the message will be deleted when it expires. - DefaultRedeliveryDelay
- This attribute lets you delay a redelivery attempt, which helps to prevent thrashing delivery-failure. The default value is
0
(that is, no delay). You can override this value on a per-destination basis. - MessageCounterSamplePeriod
- This attribute defines the period of time between the server's queries to the queue for queue statistics. The default value is
5000
milliseconds. - FailoverStartTimeout
- The longest period (in milliseconds) that the client will wait for failover to begin on the server side when a problem is detected. The default value is
60000
(one minute). - FailoverCompleteTimeout
- The longest period (in milliseconds) that the client will wait for failover to complete on the server side once failover has been initiated. The default value is
300000
(five minutes). - DefaultMessageCounterHistoryDayLimit
- JBoss Messaging provides a message counter history, which shows the number of messages arriving on each queue over a certain number of days. This attribute represents the maximum number of days for which to store message counter history. You can override this value on a per-destination.
- ClusterPullConnectionFactoryName
- The connection factory used to pull, or suck, messages between queues. You can omit this attribute to disable message sucking while retaining failover.
- DefaultPreserveOrdering
- When
true
, JMS ordering is preserved in the cluster. See Chapter 6, Clustering Notes for more detail. The default value isfalse
. - RecoverDeliveriesTimeout
- When failover occurs, messages that have been delivered will be stored while the clients reconnect. If the clients do not reconnect (for example, if the client is dead), these messages will eventually time out and be added to the queue. This attribute sets the period before timeout in milliseconds. The default value is
300000
(five minutes). - EnableMessageCounters
- When set to
true
, enables message counters upon server start. - SuckerPassword
- JBoss Messaging internally creates connections between nodes to redistribute messages between clustered destinations. These connections are created with a special, reserved username. This attribute defines the password to use when creating these connections.For versions of JBoss Messaging later than 1.4.1.GA, you must define the
SuckerPassword
on theSecurityMetadataStore
.Warning
TheSuckerPassword
must be changed at install time, or the default password will be used, giving any user who knows the default password access to any destination on the server. - SuckerConnectionRetryTimes
- This is the maximum number of times a sucker's connection is permitted to retry in the event of a failure. The default value is
-1
which represents "retry indefinitely". - SuckerConnectionRetryInterval
- This is the interval in milliseconds between each retry of the failed sucker's connection. The default value is
5000
. - StrictTck
- To enable strict JMS Technology Compatibility Kit (TCK) semantics, set this attribute to
true
. - Destinations
- Returns a list of the destinations (queues and topics) currently deployed.
- MessageCounters
- A message counter for a particular queue.
- MessageStatistics
- Statistics about each message counter for each queue.
- SupportsFailover
- When this attribute is
false
, server-side failover does not occur when a node crashes in a cluster. - PersistenceManager
- The persistence manager used by the
ServerPeer
. (You will not normally need to change this attribute.) - JMSUserManager
- The JMS user manager used by the
ServerPeer
. (You will not normally need to change this attribute.) - SecurityStore
- The pluggable
SecurityStore
. If you redefine this attribute, remember that you will need to authenticate theMessageSucker
user (JBM.SUCKER
) with all special permissions required by clustering. - SupportsTxAge
- Specifies whether the transaction creation time is stored in the transaction record. If set to
true
, the transaction record is stored. The default isfalse
.
5.3. ServerPeer methods
- deployQueue
- Used to programmatically deploy a queue. If the queue exists but is undeployed, it will be deployed. Otherwise, it is created and deployed.The
name
parameter matches a destination to deploy.The optionaljndiName
parameter represents the full JNDI name of the location to which a destination will be bound. If this is not specified, the destination will be bound in<DefaultQueueJNDIContext>/<name>
.There are two overloaded versions of this operation. The first deploys the destination with default paging parameters. The second deploys the destination with the paging parameters specified. For more information about paging parameters, refer to Section 5.9, “Configuring Destinations”. - undeployQueue
- Used to programmatically undeploy a queue. Queues are not removed from persistent storage. This operation returns
true
if the queue is successfully undeployed. Otherwise, it returnsfalse
. - destroyQueue
- Used to programmatically destroy a queue. Queues are undeployed and all of their data is removed from the database and destroyed.
Warning
Exercise caution when using this method, since it will delete all data for the queue.This operation returnstrue
if the queue was destroyed successfully. Otherwise, it returnsfalse
. - deployTopic
- Used to programmatically deploy a topic. There are two overloaded versions of this operation. The first deploys already existing topics with the default paging parameters. The second creates and deploys topics with specified paging parameters. For more information about destinations, refer to Section 5.9, “Configuring Destinations”.The
name
parameter represents the name of the destination to deploy.ThejndiName
represents the full JNDI name of the location to which the destination will be bound. If this is not specified, the destination will be bound in<DefaultTopicJNDIContext>/<name>
. - undeployTopic
- Used to programmatically undeploy a topic. Topics are undeployed, but not removed from persistent storage. This operation returns
true
if the topic is undeployed successfully. Otherwise,false
is returned. - destroyTopic
- Used to programmatically destroy a topic. Topics are undeployed and all data is removed from the database and destroyed. This operation returns
true
if the topic is successfully destroyed. Otherwise, it returnsfalse
.Warning
Exercise caution when using this method: it will delete all data for the topic. - listMessageCountersHTML
- Returns message counters in a simply-displayed HTML format.
- resetAllMesageCounters
- Resets all message counters to zero.
- enableMessageCounters
- Enables all message counters for all destinations. Message counters are disabled by default.
- disableMessageCounters
- Disables all message counters for all destinations. Message counters are disabled by default.
- retrievePreparedTransactions
- Retrieves a list of the XIDs for all transactions currently in a prepared state on the node.
- showPreparedTransactions
- Retrieves a list of the XIDs for all transactions currently in a prepared state on the node in an easily-displayed HTML format.
- listAllPreparedTransactions
- Displays the details of all prepared transactions.
- listPreparedTransactions
- Displays the details of all prepared transactions where the transaction ages are equal to or older than a specified time.
- showMessageDetails
- Displays the details of a message. The message ID is used to specify the message to display.
- commitPreparedTransaction
- Manually commit a prepared transaction. The transaction ID is used to specify the transaction to commit.
- rollbackPreparedTransaction
- Manually roll-back a prepared transaction. The transaction ID is used to specify the transaction to roll-back.
5.4. Changing the Database
jboss-as/server/$PROFILE/deploy/messaging/<DATABASE_TYPE>-persistence-service.xml
as a persistence storage. The default persistence storage type is Hypersonic (HSQLDB) defined in hsqldb-persistence-service.xml
. Note that the configuration is defined for a clustered environment (<attribute name="Clustered">true</attribute>
).
Warning
- no transaction isolation
- thread and socket leaks (
connection.close()
does not tidy up resources) - persistence quality (logs commonly become corrupted after a failure, preventing automatic recovery)
- database corruption
- stability under load (database processes cease when dealing with too much data)
- not viable in clustered environments
<your database type>-persistence-service.xml
file.
$JBOSS_HOME/docs/examples/jms
directory of the release bundle.
$JBOSS_HOME/server/$PROFILE/deploy/messaging/hsqldb-persistence-service.xml
configuration file with the configuration file for your database type. Restart the server to apply the new persistence configuration.
true
in <your database type>-persistence-service.xml
(the default setting is <attribute name="Clustered">false</attribute>).
Note
java:/DefaultDS
for the data source. To deploy a data source with a different JNDI name, you must update all DataSource
attributes in the persistence configuration file. Example data source configurations are included in the distribution.
5.5. Configuring the Post Office
<database type>-persistence-service.xml
file. For example:
<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"> 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 do not 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>
5.5.1. MessagingPostOffice Attributes
MessagingPostOffice
Service Attributes are described in the following list.
- DataSource
- The datasource the postoffice should use for persisting its mapping data.
- 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.
- 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 aSQLException
will be thrown by the JDBC driver and ignored by the Persistence Manager, allowing it to continue.By default the value ofCreateTablesOnStartup
attribute is set totrue
- 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 ofDetectDuplicates
attribute is set totrue
- IDCacheSize
- If duplicate detection is enabled. (See
DetectDuplicates
), then the server will remember the lastn
message ids sent, to prevent duplicate messages sent after failover has occurred. The value ofn
is determined by this attribute.By default the value ofIDCacheSize
attribute is set to500
- PostOfficeName
- The name of the post office.
- NodeIDView
- This returns set containing the node ids of all the nodes in the cluster.
- 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.
- 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.
- 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. - CastTimeout
- The maximum time to wait for a reply casting message synchronously.The default value is
5000
milliseconds. - FailoverOnNodeLeave
- Specifies how messages stored on a node are redistributed when a node is cleanly shutdown. The default value is
false
. Iftrue
, when a server node is shut down cleanly (using Ctrl+C in the terminal) all messages stored on the node are moved to another node in the cluster.Important
Clients originally connected to the cleanly shutdown node are not automatically reconnected to the failover node in the cluster. Clients return an exception upon message failover. - 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
- 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 clusterThe details of the JGroups configuration will not 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.
- 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 will not 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.
- RetryOnConnectionFailure
- Specifies whether the MBean should attempt to reconnect to the database. The default is
false
. - MaxRetry
- Specifies the maximum limit for DataSource connection failures. The default is
25
. Set the parameter to-1
to activate "retry forever" mode. This parameter is valid whenRetryOnConnectionFailure
is set totrue
.Important
Clients that consume messages from a clustered destination can become unresponsive when closed. This happens if the node has the valueMaxRetry
set to-1
, and loses the connection to the database. To avoid the problem, set the node parameterMaxRetry
to a value greater than-1
. You can set the attribute value in the MBeansPersistenceManager
,PostOffice
, andJMSUserManager
in the file[database]-persistence-service.xml
- RetryInterval
- Specifies the retry interval between two consecutive retries. The default is 1000 (milliseconds). This parameter is valid when
RetryOnConnectionFailure
is set totrue
.
Important
- KeepOldFailoverMode
- Specifies whether the timestamp table failover mode should be used. The default is
true
(disable new failover behavior). - NodeStateRefreshInterval
- Specifies the maximum duration (in milliseconds) a cluster will wait for a node to refresh its timestamp before the cluster marks the node as disabled. The default is 30000 (30 seconds).
5.6. Configure the MessagingClusterHealthMBean
MessagingPostOffice
uses the KeepOldFailoverMode
and NodeStateRefreshInterval
parameters to control the interval during which a node must update timestamps to remain part of a cluster. These parameters do not control how a node responds to losing connection to the database.
MessagePostOffice
. Even though the node may still be healthy, the cluster has no way of determining the actual state of the node. As a result, the cluster assumes the node has failed and duplicate message delivery can occur.
MessagingClusterHealthMBean
MBean is responsible for monitoring the node state, and stopping and starting a node when it loses connection to the database. When a node is shunned from the cluster and subsequently loses database connectivity, the MBean shuts down the node immediately. The MBean monitors the JGroups status and database status while the node is unavailable, and will restart the node when it detects JGroups and the database connection is restored to normal operation.
MessagingClusterHealthMBean
MBean in the ServerPeer
MBean as an optional-attribute-name
attribute of the <depends>
directive.
<!-- ServerPeer MBean configuration --> <mbean code="org.jboss.jms.server.ServerPeer" name="jboss.messaging:service=ServerPeer" xmbean-dd="xmdesc/ServerPeer-xmbean.xml"> <!-- Unique integer ID of the server peer - each cluster node MUST have a unique value --> <attribute name="ServerPeerID">0</attribute> <!-- The default JNDI context that queues use when deployed without specifying one --> <attribute name="DefaultQueueJNDIContext">/queue</attribute> <!-- The default JNDI context that topics use when deployed without specifying one --> <attribute name="DefaultTopicJNDIContext">/topic</attribute> <!-- XML CONFIG REMOVED FOR READABILITY --> <depends optional-attribute-name="PersistenceManager"> jboss.messaging:service=PersistenceManager </depends> <!-- XML CONFIG REMOVED FOR READABILITY --> <depends optional-attribute-name="MessagingClusterHealthMBean"> jboss.messaging:service=MessagingClusterHealthMBean </depends> </mbean>
MessagingClusterHealthMBean
MBean in the ServerPeer
MBean, you need to add the MessagingClusterHealthMBean
MBean's configuration.
<!-- MessagingClusterHealthMBean MBean configuration --> <mbean code="org.jboss.jms.server.MessagingClusterHealthMBean" name="jboss.messaging:service=MessagingClusterHealthMBean" xmbean-dd="xmdesc/MessagingClusterHealthMBean-xmbean.xml"> <!-- The service name of Server Peer --> <attribute name="ServerPeer">jboss.messaging:service=ServerPeer</attribute> <!-- The service name of Post Office --> <attribute name="PostOffice">jboss.messaging:service=PostOffice</attribute> <!-- The service name of Persistence Manager --> <attribute name="PersistenceManager">jboss.messaging:service=PersistenceManager</attribute> </mbean>
5.7. Configuring the Persistence Manager
<database type>-persistence-service.xml
. JBoss Messaging ships with the hsqldb-persistence-service.xml
file by default, which configures the Messaging server to use the Hypersonic database instance included by default with any JBoss Enterprise Application Server instance.
Warning
mysql-persistence-service.xml
and ndb-persistence-service.xml
) are available from the jboss-as/docs/examples/jms
directory of the release bundle.
<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">false</attribute> <!-- The maximum number of parameters to include in a prepared statement --> <attribute name="MaxParams">500</attribute> </mbean>
Important
2 kilobytes
by default. Any message that exceeds this limit is truncated, without any information or warning. Set the @@TEXTSIZE
database parameter to a higher value to prevent potential truncation.
@@TEXTSIZE
value is set to a lesser value than the default value. For further information, refer to https://issues.jboss.org/browse/SOA-554, and the Special Notes on Sybase section in the Administration and Configuration Guide.
Important
ShrinkDatabase
and UpdateUsage
for guidance reclaiming the unused space. For further information about this issue, refer to https://issues.jboss.org/browse/SOA-629
5.7.1. JDBCPersistenceManager MBean Attributes
- 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 aSQLException
will be thrown by the JDBC driver and ignored by the Persistence Manager, allowing it to continue.By default the value ofCreateTablesOnStartup
attribute is set totrue
. - 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 ofUsingBatchUpdates
attribute is set tofalse
- 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 ofUsingBinaryStream
attribute is set totrue
- 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 ofUsingTrailingByte
attribute is set tofalse
- 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 totrue
- 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.
- 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 to100
- 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 tofalse
- RetryOnConnectionFailure
- Specifies whether the MBean should attempt to reconnect to the database. The default is
false
. - MaxRetry
- Specifies the maximum limit for DataSource connection failures. The default is
25
. Set the parameter to-1
to activate "retry forever" mode. This parameter is valid whenRetryOnConnectionFailure
is set totrue
.Important
Clients that consume messages from a clustered destination can become unresponsive when closed. This happens if the node has the valueMaxRetry
set to-1
, and loses the connection to the database. To avoid the problem, set the node parameterMaxRetry
to a value greater than-1
. You can set the attribute value in the MBeansPersistenceManager
,PostOffice
, andJMSUserManager
in the file[database]-persistence-service.xml
- RetryInterval
- Specifies the retry interval between two consecutive retries. The default is 1000 (milliseconds). This parameter is valid when
RetryOnConnectionFailure
is set totrue
. - CreateTablesOnStartup
- Specifies whether tables and index creation is attempted when the Persistence Manager is started. When set to
true
(default), the persistence manager will attempt to create tables (and indexes) on start up. If tables or indexes already exist, aSQLException
will be thrown by the JDBC driver and ignored by the persistence manager, allowing it to continue unhindered. - UsingBatchUpdates
- Specifies whether multiple database updates are grouped in batches to improve performance. Set this value to
true
if your database supports JDBC batch updates.. The default value isfalse
. - UsingBinaryStream
- Specifies whether messages are stored and read with a JDBC binary stream, instead of via
getBytes()
andsetBytes()
. Set this value tofalse
if your database must usegetBytes()
andsetBytes()
. The default value istrue
. - UsingTrailingByte
- Specifies how Sybase database BLOBs containing trailing zeroes are handled. When set to
true
, a trailing non-zero byte is added to each BLOB before persistence, and removed from the BLOB following persistence, preventing truncation by the database. The default value isfalse
Note
Certain versions of Sybase truncate a BLOB with trailing zeros. This attribute is only required if you are running a Sybase database. - SupportsBlobOnSelect
- Specifies how BLOBs are inserted into certain database types. When set to
false
, two-stage insertion will be used. The default value istrue
.Note
Certain databases, specifically Oracle, do not allow BLOB insertion via anINSERT INTO ... SELECT FROM
statement, and require two-stage conditional message insertion. Set this attribute tofalse
if you are running an Oracle database, or other database with this requirement. - SQLProperties
- Specifies the DDL and DML for a particular database. If a particular DDL or DML statement is not overridden, the default Hypersonic configuration will be used for that statement.
- UseNDBFailoverStrategy
- Specifies whether a SQL statement is re-executed in the event a database transaction commit fails in a clustered environment. If set to
true
, the SQL statement is re-executed in the event that the commit fails. If a further error occurs, the persistence manager assumes the error is due to the previous transaction having committed successfully, and ignores the error. By default, this attribute is set tofalse
.Note
When some databases, such as MySQL, run in clustered environments, they can fail during database transaction commits. If this occurs, the final transaction state is unknown. - MaxParams
- Specifies the maximum number of parameters allowed per prepared statement while loading messages. The default value is
500
.
5.8. Configuring the JMS user manager
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"> 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 ('jdoe','jdoepw','jdoe-id') </attribute> </mbean>
5.8.1. JMSUserManager MBean Attributes
- 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 aSQLException
will be thrown by the JDBC driver and ignored by the Persistence Manager, allowing it to continue.By default the value ofCreateTablesOnStartup
attribute is set totrue
- 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 ofUsingBatchUpdates
attribute is set tofalse
- 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.
- RetryOnConnectionFailure
- Specifies whether the MBean should attempt to reconnect to the database. The default is
false
. - MaxRetry
- Specifies the maximum limit for DataSource connection failures. The default is
25
. Set the parameter to-1
to activate "retry forever" mode. This parameter is valid whenRetryOnConnectionFailure
is set totrue
.Important
Clients that consume messages from a clustered destination can become unresponsive when closed. This happens if the node has the valueMaxRetry
set to-1
, and loses the connection to the database. To avoid the problem, set the node parameterMaxRetry
to a value greater than-1
. You can set the attribute value in the MBeansPersistenceManager
,PostOffice
, andJMSUserManager
in the file[database]-persistence-service.xml
- RetryInterval
- Specifies the retry interval between two consecutive retries. The default is 1000 (milliseconds). This parameter is valid when
RetryOnConnectionFailure
is set totrue
.
5.9. Configuring Destinations
5.9.1. Pre-configured destinations
destinations-service.xml
:
<!-- 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> <!-- The Default Expiry Queue --> <mbean code="org.jboss.jms.server.destination.QueueService" name="jboss.messaging.destination:service=Queue,name=ExpiryQueue" xmbean-dd="xmdesc/Queue-xmbean.xml"> <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends> <depends>jboss.messaging:service=PostOffice</depends> </mbean>
5.9.2. Configuring Queues
5.9.2.1. Queue MBean Attributes
- Name
- Defines the queue name.
- JNDIName
- Defines the JNDI name that binds the queue.
- DLQ
- Defines the DLQ (Dead Letter Queue) for this queue and overrides any value set in the Server Peer configuration file.
- ExpiryQueue
- Defines the expiry queue and overrides any value set in the Server Peer configuration file.
- RedeliveryDelay
- Defines the redelivery delay to be applied to this queue and overrides any value set in the Server Peer configuration file.
- MaxDeliveryAttempts
- Defines the maximum number of times message delivery is attempted before the message is sent to the DLQ, if configured. The default value,
-1
, means that the value from the Server Peer configuration file is used. Any other setting will override the value set in the Server Peer configuration file. - CreatedProgrammatically
- Returns
true
if the queue was created programmatically. - MessageCount
- Returns the total number of messages in the queue. That is, the number of messages being scheduled plus the number being delivered, plus the number not being delivered.
- 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 lets you specify the earliest time at which a particular message will be delivered. For example, you can send a message now, and specify that it will not be delivered for two hours. To do so, set the following in the message header:
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);
- MaxSize
- Specifies the maximum number of messages that can be held in a queue. Any excess messages will be dropped. The default value is
-1
, which is unbounded. - Clustered
- This attribute must be set to
true
if the destination is clustered. - MessageCounter
- Each queue maintains a message counter.
- MessageCounterStatistics
- The statistics for the message counter.
- MessageCounterHistoryDayLimit
- The maximum number of days for which to hold message counter history. Overrides any value set in the Server Peer configuration file.
- ConsumerCount
- The number of consumers currently consuming from the queue.
- DropOldMessageOnRedeploy
- Specifies how queue services with clustered attributes that differ from previously deployed attributes are handled. If set to
true
, all remaining messages in the queue are deleted after the queue service re-deployment if the queue service attribute contains a different clustered attribute. If set tofalse
(default), all messages are reserved.
Warning
true
, and add the queue service configuration to each node.
false
in one of the queue configurations and delete all other queues in the cluster.
5.9.2.1.1. Destination Security Configuration
<SecurityConfig> <security> <role read="true" write="true" create="true"/> </security> <SecurityConfig>
- read
- Specifies the role can create consumers, receive messages, and browse the destination.
- write
- Specifies the role can create producers, or send messages to the destination.
- create
- Specifies the role can create durable subscriptions on this destination.
Note
SecurityConfig
element is not specified, then the default security configuration from the Server Peer will be used instead.
5.9.2.1.2. Destination paging parameters
- FullSize
- Specifies the maximum number of messages held by the queue or topic subscription in memory at any one time. The actual queue can hold more messages, but these are paged to and from storage as messages are added or consumed. If no value is specified, the default is
75000
. - PageSize
- Specifies the maximum number of messages that are pre-loaded per operation when loading messages from the queue or subscription. If no value is specified, the default is
2000
. - DownCacheSize
- Specifies the maximum number of messages the Down Cache holds before the messages are flushed to storage. The default value is
2000
messages.When messages are paged to storage from the queue, they enter a Down Cache before being written to storage. This enables the write to occur as a single operation, which aids performance.Note
Paging parameters for temporary queues must be specified on the appropriate connection factory. Refer to Section 5.10, “Configuring Connection Factories” for detailed information about the different connection factories available.
5.9.2.1.3. Queue Managed Bean Operations
- RemoveAllMessages
- Removes (and deletes) all messages from the queue.
Important
This will permanently delete all messages from the queue; use this operation with caution. - ListAllMessages
- Lists all messages currently in the queue. Using a JMS selector as an argument in this operation lets you retrieve a subset of the messages in the queue that match the given criteria.
- ListDurableMessages
- Lists all durable messages in the queue. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.
- ListNonDurableMessages
- Lists all non-durable messages in a queue. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.
- ResetMessageCounter
- Resets the message counter to zero.
- ResetMessageCounterHistory
- Resets the message counter history.
- ListMessageCounterAsHTML
- Lists the message counter in HTML format.
- ListMessageCounterHistoryAsHTML
- Lists the message counter history in HTML format.
5.9.3. Configuring Topics
5.9.3.1. Topic Managed Bean Attributes
- Name
- Defines the name of the topic.
- JNDIName
- Defines the JNDI location where the topic is bound.
- DLQ
- Defines the Dead Letter Queue (DLQ) used for this topic and overrides any value set in the Server Peer configuration file.
- ExpiryQueue
- Defines the expiry queue used for this topic and overrides any value set in the Server Peer configuration file.
- RedeliveryDelay
- Defines the delay period between redelivery attempts for this topic and overrides any value set in the Server Peer configuration file.
- MaxDeliveryAttempts
- Defines the maximum number of times message delivery will be attempted before the message is sent to the DLQ, if configured. The default value is
-1
, which specifies that the value from the Server Peer configuration file be used. Any other setting overrides the Server Peer value. - CreatedProgrammatically
- Returns
true
if the topic was created programmatically. - MaxSize
- Specifies the maximum number of messages that can be held in a topic subscription. Any excess messages will be dropped from the topic. The default value is
-1
, which applies no size restriction. - Clustered
- Set this to
true
if your destination is clustered. - MessageCounterHistoryDayLimit
- Defines the maximum number of days to retain message counter history, and overrides any value set in the Server Peer configuration file.
- MessageCounters
- Returns a list of message counters for the topic's subscriptions.
- AllMessageCount
- Returns the total number of messages in all subscriptions belonging to the topic.
- DurableMessageCount
- Returns the total number of durable messages in all subscriptions belonging to this topic.
- NonDurableMessageCount
- Returns the total number of non-durable messages in all subscriptions belonging to this topic.
- DropOldMessageOnRedeploy
- Specifies how queue services with clustered attributes that differ from previously deployed attributes are handled. If set to
true
, all remaining messages in the queue are deleted after the queue service re-deployment if the queue service attribute contains a different clustered attribute. If set tofalse
(default), all messages are reserved.Warning
When you re-deploy a destination, you must shut down all the nodes in the cluster, make proper configuration changes, and then restart the nodes.Redeploying from a non-clustered to a clustered queue requires you set the clustered attribute totrue
, and add the queue service configuration to each node.Redeploying from a clustered to a non-clustered queue requires you set the clustered attribute tofalse
in one of the queue configurations and delete all other queues in the cluster. - AllSubscriptionsCount
- Returns a count of all subscriptions belonging to this topic.
- DurableSubscriptionsCount
- Returns a count of all durable subscriptions belonging to this topic.
- NonDurableSubscriptionsCount
- Returns a count of all non-durable subscriptions belonging to this topic.
5.9.3.1.1. Destination Security Configuration
- read
- Specifies the role can create consumers, receive messages, and browse the destination.
- write
- Specifies the role can create producers, or send messages to the destination.
- create
- Specifies the role can create durable subscriptions on this destination.
Note
SecurityConfig
element is not specified, then the default security configuration from the Server Peer will be used instead.
5.9.3.1.2. Destination paging parameters
- FullSize
- Specifies the maximum number of messages held by the queue or topic subscription in memory at any one time. The actual queue can hold more messages, but these are paged to and from storage as messages are added or consumed. If no value is specified, the default is
75000
. - PageSize
- Specifies the maximum number of messages that are pre-loaded per operation when loading messages from the queue or subscription. If no value is specified, the default is
2000
. - DownCacheSize
- Specifies the maximum number of messages the Down Cache holds before the messages are flushed to storage. The default value is
2000
messages.When messages are paged to storage from the queue, they enter a Down Cache before being written to storage. This enables the write to occur as a single operation, which aids performance.Note
Paging parameters for temporary queues must be specified on the appropriate connection factory. See the section on Connection Factory Configuration for details.
5.9.3.2. Topic Managed Bean Operations
- RemoveAllMessages
- Removes (and deletes) all messages from subscriptions that belong to this topic.
Important
This will permanently delete all messages from the topic; use this operation with caution. - ListAllMessages
- Lists all messages belonging to a specified subscription. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.
- ListDurableMessages
- Lists all durable messages belonging to the specified subscription. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.
- ResetMessageCounter
- Resets the message counter to zero.
- ResetMessageCounterHistory
- Resets the message counter history.
- ListAllSubscriptionsAsHTML
- Lists all subscriptions belonging to this topic in HTML format.
- ListDurableSubscriptionsAsHTML
- Lists all durable subscriptions belonging to this topic in HTML format.
- ListNonDurableSubscriptions
- Lists all non-durable messages belonging to the specified subscription. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.
- ListNonDurableSubscriptionsAsHTML
- Lists all non-durable subscriptions belonging to this topic in HTML format.
5.10. Configuring Connection Factories
/ConnectionFactory
/XAConnectionFactory
java:/ConnectionFactory
java:/XAConnectionFactory
.
/ClusteredConnectionFactory
/ClusteredXAConnectionFactory
java:/ClusteredConnectionFactory
java:/ClusteredXAConnectionFactory
ConnectionFactory
managed bean in connection-factories-service.xml
.
<name>-service.xml
, and deploy it in $JBOSS_HOME/server/messaging/deploy
.
Example 5.1. Connection Factory
myClientID
, which is bound to two locations in the JNDI tree: /MyConnectionFactory
and /factories/cf
.
PreFetchSize
DefaultTempQueueFullSize
DefaultTempQueuePageSize
DefaultTempQueueDownCacheSize
DupsOKBatchSize
SupportsFailover
SupportsLoadBalancing
LoadBalancingFactory
Connector
attribute to specify the service name of the connector you wish to use.
<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>
5.10.1. ConnectionFactory Managed Bean Attributes
- ClientID
- You can preconfigure a connection factory with a client ID. Any connection created via this connection factory will obtain this client ID.
- JNDIBindings
- Lists available JNDI bindings for this connection factory.
- PrefetchSize
- Specifies how many messages the window holds at once, 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.Transmission Control Protocol (TCP) implements its own additional flow control. Message consumption can also be blocked if the TCP window size is smaller than the
PrefetchSize
parameter. - SlowConsumers
- Specifies whether the allowable buffer size for slow consumers is reduced. Reducing the buffer size for slow consumers results in minimized to increase the potential for messages to be consumed by faster consumers. It is not possible to totally disable buffering, however, setting the
SlowConsumers
attribute totrue
will reduce the buffer size. Setting this attribute totrue
is equivalent to settingPrefetchSize
to1
which is the lowest possible value available. - StrictTck
- Enables strict JMS behavior if the attribute is set to
true
. Strict JMS behavior is required by the Technology Compatibility Kit (TCK). - SendAcksAsync
- Specifies acknowledgments are sent asynchronously if the attribute is set to
true
. This can improve performance, particularly ifauto_acknowledge
mode is active. - DefaultTempQueueFullSize
- Optional attribute that specifies the paging parameters for temporary full size queue destinations, which are scoped to connections created with this connection factory. The default value is
200000
. For more information about these attributes, refer to Section 5.9.3.1.2, “Destination paging parameters”. - DefaultTempQueuePageSize
- Optional attribute that specifies the paging parameters for temporary page size destinations, which are scoped to connections created with this connection factory. The default value is
2000
. For more information about these attributes, refer to Section 5.9.3.1.2, “Destination paging parameters”. - DefaultTempQueueDownCacheSize
- Optional attribute that specifies the paging parameters for temporary down cache size destinations, which are scoped to connections created with this connection factory. The default value is
2000
. For more information about these attributes, refer to Section 5.9.3.1.2, “Destination paging parameters”. - DupsOKBatchSize
- Specifies the number of
DUPS_OK_ACKNOWLEDGE
acknowledgments that are buffered locally before they are sent. The default value is2000
. - SupportsLoadBalancing
- Specifies whether client-side load balancing is enabled for the connection factory on clustered installations. If load balancing is enabled, any connection created by that connection factory will be load-balanced across the nodes of a cluster. A connection created on a particular node remains on that node. The default value is
false
. - SupportsFailover
- Specifies whether client-side automatic failover is enabled for the connection factory on clustered installations. If automatic failover is enabled, JBoss Messaging will automatically and transparently failover to another node in the cluster when a connection problem is detected. The default value is
false
.Note
When automatic failover is disabled, the user code is responsible for catching connection exceptions in synchronous JMS operations, and a JMSExceptionListener
must be installed to catch exceptions asynchronously. When an exception is caught, the client-side code must look up a new connection factory via HAJNDI and recreate the connection. - DisableRemotingChecks
- Specifies whether the connection factory checks that the corresponding JBoss Remoting Connector uses sensible values. JBoss Messaging is very sensitive to these values, and there is rarely any need to change them. To disable this sanity checking, set
DisableRemotingChecks
tofalse
. The default value istrue
.Warning
Do not disable the remoting checks; system instability. - LoadBalancingFactory
- Specifies the client-side load balancing factory implementation used by the connection factory. The value must correspond to the name of a class that implements the interface
org.jboss.jms.client.plugin.LoadBalancingFactory
.The default value isorg.jboss.jms.client.plugin.RoundRobinLoadBalancingFactory
, which load-balances connections across the cluster in a round-robin fashion. - Connector
- Specifies the remoting connector used by the connection factory. Different connection factories can use different connectors, so you can deploy one connection factory that uses the HTTP transport to communicate with the server, and another that uses the bisocket transport to communicate.
- EnableOrderingGroup
- Specifies whether strict message ordering is enabled on the
ConnectionFactory
. If set totrue
, any messages sent from producers which are created from the enabled connection factory become ordering group messages. The default value for this parameter isfalse
. - DefaultOrderingGroupName
- Specifies the default name for the message ordering group. The specified name will take effect once the
EnableOrderingGroup
parameter is set totrue
. If this attribute is missing, the group name will be generated automatically.
5.11. Configuring the Remoting Connector
$JBOSS_HOME/server/$SERVER/deploy/messaging/remoting-bisocket-service.xml
. The following code is an example of a bisocket remoting configuration:
Example 5.2. Bisocket Remoting Configuration
<?xml version="1.0" encoding="UTF-8"?> <!-- Standard bisocket-based Remoting service deployment descriptor. $Id: remoting-bisocket-service.xml 3981 2008-03-28 18:00:41Z timfox $ --> <server> <!-- Standard bisocket connector - the bisocket transport only opens connection from client->server so can be used with firewalls where only outgoing connections are allowed. For examples of HTTP and SSL transports see docs/examples --> <mbean code="org.jboss.remoting.transport.Connector" name="jboss.messaging:service=Connector,transport=bisocket" display-name="Bisocket Transport Connector"> <attribute name="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="serverBindAddress">${jboss.bind.address}</attribute> <attribute name="serverBindPort">${jboss.messaging.connector.bisocket.port:4457} </attribute> <attribute name="clientSocketClass" isParam="true"> org.jboss.jms.client.remoting.ClientSocketWrapper </attribute> <attribute name="serverSocketClass">org.jboss.jms.server.remoting.ServerSocketWrapper </attribute> <attribute name="onewayThreadPool">org.jboss.jms.server.remoting.DirectThreadPool </attribute> <!-- the following parameters are useful when there is a firewall between client and server. Uncomment them if so. --> <!-- <attribute name="numberOfCallRetries" isParam="true">1</attribute> <attribute name="pingFrequency" isParam="true">214748364</attribute> <attribute name="pingWindowFactor" isParam="true">10</attribute> <attribute name="generalizeSocketException" isParam="true">true</attribute> --> <!-- Now remoting supports socket write timeout configuration. Uncomment this if you need it. --> <!-- <attribute name="writeTimeout" isParam="true">30000</attribute> --> <!-- End immutable parameters --> <attribute name="stopLeaseOnFailure" isParam="true">true</attribute> <!-- Periodicity of client pings. Server window by default is twice this figure --> <attribute name="clientLeasePeriod" isParam="true">10000</attribute> <attribute name="validatorPingPeriod" isParam="true">10000</attribute> <attribute name="validatorPingTimeout" isParam="true">5000</attribute> <attribute name="failureDisconnectTimeout" isParam="true">0</attribute> <attribute name="callbackErrorsAllowed">1</attribute> <attribute name="registerCallbackListener">false</attribute> <attribute name="useClientConnectionIdentity" isParam="true">true</attribute> <attribute name="timeout" isParam="true">0</attribute> <!-- Max Number of connections in client pool. This should be significantly higher than the max number of sessions/consumers you expect --> <attribute name="JBM_clientMaxPoolSize" isParam="true">200</attribute> <!-- The maximum time to wait before timing out on trying to write a message to socket for delivery --> <attribute name="callbackTimeout">10000</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> </attribute> </mbean> </server>
- clientLeasePeriod
- Clients periodically return heartbeats to the server to confirm that they are still active. If the server does not receive a heartbeat after a certain period of time, it will close down the connection and remove all resources that correspond to the client's session. The
clientLeasePeriod
determines the period of time between heartbeats, in milliseconds. The default value is10000
.By default, the server closes a client if it does not receive a heartbeat within double theclientLeasePeriod
. In reality, the period is automatically resized according to system load. - numberOfRetries
- The number of seconds JBoss Remoting blocks on the client pool while waiting for a connection to become available. If you have a very large number of sessions concurrently accessing the server from a client and cannot obtain connections from the pool, you may want to increase this value.
- clientMaxPoolSize
- JBoss Remoting maintains a client-side pool of TCP connections on which to service requests. If you have a large number of sessions concurrently accessing the server from a client and cannot obtain connections from the pool, you may want to increase this value.
- secondaryBindPort
- The bisocket transport uses control connections to pass control messages between server and client. This attribute defines the address to which the secondary
ServerSocket
is bound. Its value is random by default. To work behind a firewall, you need to set it to a particular value and create a rule for it in the firewall configuration. The recommended value is4458
because the primary port is4457
. - secondaryConnectPort
- The port that the client uses to connect. Specify this to let your client work with NAT routers.
- maxPoolSize
- The number of threads used on the server side to service requests.
${jboss.bind.address}
, which can be defined by running the ./run.sh -c [yourconfig] -b [yourIP]
command.
remoting-bisocket-service.xml
to use a different communication port.
Warning
5.12. ServiceBindingManager
SeviceBindingManager
provides multiple application server instances running on the same IP using different port ranges, which is useful during development. There are other ways to do this, but the ServiceBindingManager
removes much hassle.
5.13. Message Driven Beans
- Using a descriptor
<enterprise-beans> <message-driven> <ejb-name>MDBExample</ejb-name> <destination-jndi-name>queue/@QUEUE_NAME@</destination-jndi-name> </message-driven> </enterprise-beans>
- Using an annotation
@MessageDriven(mappedName="jms/Queue") public class SimpleMessageBean implements MessageListener { @Resource private MessageDrivenContext mdc; ...
Important
Table 5.1. MDB Properties Provided by the JCA Specification
Name | Type | Default value | Remarks |
---|---|---|---|
destination | java.lang.String | none |
This property is Mandatory
The JNDI name of the Queue or Topic.
|
destinationType | java.lang.String | none |
The type of destination valid values are javax.jms.Queue or javax.jms.Topic
|
messageSelector | java.lang.String | none |
The message selector of the subscription
|
acknowledgeMode | int | AUTO_ ACKNOWLEDGE |
The type of acknowledgement when not using transacted jms - valid values AUTO_ ACKNOWLEDGE or DUPS_OK_ ACKNOWLEDGE
|
clientID | java.lang.String |
The client id of the connection
| |
subscriptionDurability | String | NonDurable |
Whether topic subscriptions are durable. Valid values are Durable or NonDurable
|
subscriptionName | String | none |
The subscription name of the topic subscription
|
Important
Table 5.2. MDB Properties Provided as JBoss Extensions
Name | Type | Default value | Remarks |
---|---|---|---|
isTopic | boolean | false |
Sets the destinationType
|
providerAdapterJNDI | java.lang.String | DefaultJMSProvider | The JNDI name of the JMS provider. |
user | java.lang.String | none | The user ID used to connect to the JMS server |
pass | java.lang.String | none | The password of the user |
maxMessages | int | 1 |
Read this number of messages before delivering messages to the MDB.
Each message is delivered individually on the same thread in an attempt to avoid context excessive context switching
|
minSession | int | 1 | The minimum number of JMS sessions that are available to concurrently deliver messages to this mdb |
maxSession | int | 15 | The maximum number of JMS sessions that are available to concurrently deliver messages to this mdb |
reconnectInterval | long | 10 seconds | The length of time in seconds between attempts to (re-)connect to the JMS provider |
keepAlive | long | 60 seconds | The length of time in milliseconds that sessions over the minimum are kept alive |
sessionTransacted | boolean | true | Whether the sessions are transacted |
useDLQ | boolean | true | Whether to use a Dead Letter Queue (DLQ) handler. |
dLQJNDIName | java.lang.String | queue/DLQ | The JNDI name of the DLQ |
dLQHandler | java.lang.String |
org.jboss.resource. adapter.jms.inflow.dlq. GenericDLQHandler
| The org.jboss.resource. adapter.jms.inflow. DLQHandler implementation class name. |
dLQUser | java.lang.String | none | The user id used to make the dlq connection to the JMS server |
dLQPassword | java.lang.String | none | The password of the dLQUser |
dLQClientID | java.lang.String | none | The client id of the DLQ connection |
dLQMaxResent | int | 5 | The maximum number of times a message is redelivered before it is sent to the DLQ. |
redeliverUnspecified | boolean | true | Whether to attempt to redeliver a message in an unspecified transaction context |
transactionTimeout | int | Default is the timeout set for the resource manager | Time in seconds for the transaction timeout |
DeliveryActive | boolean | true | Whether the MDB should make the subscription at initial deployment or wait for start() or stopDelivery() on the corresponding MBean. You can set this to false if you want to prevent messages from being delivered to the MDB (which is still starting) during server start up. |
You can configure MDBs to have default properties using the @org.jboss.ejb3.annotation.DefaultActivationSpecs
annotations.
Chapter 6. Clustering Notes
6.1. Unique Server Peer ID
ServerPeerID
attribute is used to set this information. Refer to Section 5.2, “ServerPeer attributes” for further information.
6.2. Clustered Destinations
clustered
attribute is used to set this functionality. Refer to Section 5.5.1, “MessagingPostOffice Attributes” for further information.
ClusterPullConnectionFactoryName
attribute on the Server Peer. Refer to Section 5.2, “ServerPeer attributes” for full details about this attribute.
6.3. Clustered Durable Subscriptions
Clustered
attribute in Section 5.5.1, “MessagingPostOffice Attributes”
6.4. Clustered Temporary Destinations
Clustered
attribute in Section 5.5.1, “MessagingPostOffice Attributes”.
6.5. Non-clustered Servers
PostOffice
clustered attribute to false
if you do not want all nodes to participate in a cluster, or if you do not want the server to be clustered.
6.6. Message Ordering in the Cluster
DefaultPreserveOrdering
Server Peer attribute to true
. While set to true
, messages cannot be distributed as freely around the cluster. The default value is false
.
6.7. Idempotent Operations
6.8. Clustered Connection Factories
supportsLoadBalancing
is set to true
in the connection factory, consecutive attempts to create connections will round-robin between available servers. The first node is chosen randomly.
supportsFailover
is set to true
, failover will occur transparently and automatically whenever any connection error is detected.
Chapter 7. JBoss Messaging XA Recovery Configuration
$JBOSS_HOME/server/$PROFILE/conf/jbossts-properties.xml
. The following code snippet includes the line required:
<properties depends="arjuna" name="jta"> <!-- Support subtransactions in the JTA layer? Default is NO. --> <property name="com.arjuna.ats.jta.supportSubtransactions" value="NO"/> <property name="com.arjuna.ats.jta.jtaTMImplementation" value="com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple"/> <property name="com.arjuna.ats.jta.jtaUTImplementation" value="com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple"/> <!-- *** Add this line to enable recovery for JMS resources using DefaultJMSProvider *** --> <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING1" value="org.jboss.jms.server.recovery.MessagingXAResourceRecovery;java:/DefaultJMSProvider"/> </properties>
DefaultJMSProvider
.
DefaultJMSProvider
ships with JBoss Enterprise Application Platform. It is defined in $JBOSS_HOME/server/$PROFILE/conf/jms-ds.xml
(or, in a clustered environment, hajndi-jms-ds.xml
). To perform recovery with a different JMS provider loader (for example, one that corresponds with a remote JMS Provider), add another line to the properties file and specify your remote provider instead of DefaultJMSProvider
. Your provider's name should be listed in its managed bean configuration file.
com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING1
, com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING2
, etc.
XAResource.recover()
).
hajndi-jms-ds.xml
for every node of the cluster.
Chapter 8. JBoss Messaging Message Bridge Configuration
8.1. Message Bridge Overview
deploy
directory of an Enterprise Application Platform configuration that contains JBoss Messaging.
$JBOSS_HOME/docs/examples/jboss-messaging-examples/bridge/
demonstrates a simple bridge deployed in JBoss Enterprise Application Platform and moving messages from the source to the target destination.
Bridge QoS Levels
-
QOS_AT_MOST_ONCE
- This mode specifies that messages will arrive at the destination once at the most. Messages are consumed from the source and acknowledged before they are sent to the destination. Messages can be lost if failure occurs between the message leaving the source and arriving at the destination. Messages will therefore be delivered once at most.This mode is available for both persistent and non-persistent messages.
-
QOS_DUPLICATES_OK
- This mode specifies that messages are consumed from the source and acknowledged after they have been successfully sent to the destination. If failure occurs between a message arriving, and being acknowledged by the destination, that message is sent a second time when the system recovers.This mode is available for both persistent and non-persistent messages.
-
QOS_ONCE_AND_ONLY_ONCE
- This mode specifies that messages will arrive exactly once. When the message source and destination are on the same JBoss Messaging server instance, the message can be sent and received in the same local transaction.If the source and destination are on different servers, you can implement message high durability by using a JTA transaction controlled by JBoss Transactions JTA implementation. If JTA is required, both connection factories must be
XAConnectionFactory
implementations.This mode is only available for persistent messages.This mode requires logging on both the transaction manager and the resource side to support recovery. If you require this level of QOS, you must enable XA Recovery with JBoss Transactions.
Note
QOS_ONCE_AND_ONLY_ONCE
. Set QOS_DUPLICATES_OK
mode, and then check for and discard duplicate messages at the destination.
QOS_ONCE_AND_ONLY_ONCE
behavior at the application level by maintaining a cache of received message IDs on disk and comparing received messages to this cache. Because the cache would only be valid for a certain period of time, this approach is not infallible, but can be a useful alternative depending on your application.
8.2. Bridge deployment
deploy
directory of the JBoss Enterprise Application Platform installation that contains JBoss Messaging.
8.3. Bridge Configuration
Example 8.1. Message Bridge Configuration
<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">BobSecur3</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">MaryS3cur3</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>
Message Bridge Configuration Attributes
- SourceProviderLoader, TargetProvider Loader
- The
JMSProviderLoader
managed bean is used by the bridge to look up the source connection factory and source destination. By default, JBoss Enterprise Application Platform ships with oneJMSProviderLoader
, which is deployed in the$JBOSS_HOME/server/$PROFILE/deploy/messaging/jms-ds.xml
file, and serves as the default localJMSProviderLoader
. For a clustered configuration,hajndi-jms-ds.xml
performs the same role.If your source or target destination is on a different server, or corresponds to a non-JBoss JMS Provider, you can deploy anotherJMSProviderLoader
managed bean instance that the bridge can use to contact the destination on the remote JMS Provider.To useQOS_ONCE_AND_ONLY_ONCE
delivery with a remote non-JBoss Messaging source or target, the remote JMS Provider must provide a fully-functional JMS XA resource implementation that works remotely from the server. - SourceDestinationLookup
- The full JNDI lookup for the source destination, via the
SourceProviderLoader
, such as/queue/mySourceQueue
. - TargetDestinationLookup
- The full JNDI lookup for the target destination, via the
TargetProviderLocator
, such as/topic/myTargetTopic
. - SourceUsername
- An optional attribute that specifies the username used when creating the source connection.
- SourcePassword
- An optional attribute that specifies the password used when creating the source connection.
- TargetUsername
- An optional attribute that specifies the username used when creating the target connection.
- TargetPassword
- An optional attribute that specifies the password used when creating the target connection.
- QualityOfServiceMode
- An integer representing the desired quality of service mode. The possible values are:
0
to representQOS_AT_MOST_ONCE
1
to representQOS_DUPLICATES_OK
2
to representQOS_ONCE_AND_ONLY_ONCE
See Section 8.1, “Message Bridge Overview” for a complete explanation of these modes. - Selector
- An optional attribute that lets you provide a JMS selector expression when consuming messages from a source destination. Only messages that match the selector expression are bridged from the source to the target destination. The selector expression must follow the JMS selector syntax, specified here: http://java.sun.com/j2ee/1.4/docs/api/javax/jms/Message.html.For optimal performance, apply source topic subscription selectors to source queue consumers.
- MaxBatchSize
- Specifies the maximum number of messages to consume from the source destination before sending a message batch to the target destination. Its value must be greater than or equal to
1
. - MaxBatchTime
- Specifies the longest period (in milliseconds) to wait before sending a message batch to the target, even if the
MaxBatchSize
has not been reached. Its value must be either-1
(wait forever) or greater than or equal to1
to specify a time. - SubName
- Represents the name of the durable subscription that will consume from the source destination topic.
- ClientID
- Represents the JMS client ID to use when creating or looking up the durable subscription that will consume from the source destination topic.
- FailureRetryInterval
- The period of time (in milliseconds) to wait between attempting to recreate the connection to the source or target server after failure is detected.
- MaxRetries
- The number of times to attempt to recreate the connection to the source or target server after failure is detected. The bridge will then stop attempting to recreate the connection. A value of
-1
means that the bridge will continue to attempt to reconnect forever. - AddMessageIDInHeader
- When
true
, the original message ID is added to theJBossMessage.JBOSS_MESSAGING_BRIDGE_MESSAGE_ID_LIST
header of the message being sent to the destination. If the message is bridged multiple times, each message ID is added to the header. This enables a distributed request-response pattern.
Chapter 9. Enabling JBoss Messaging Ordering Group
In the case of the transactional receipt of messages, the next message is not delivered until the transaction has been committed which includes the acknowledgment of the receipt of the current message. If the transaction is rolled back, the message is canceled, sent back to the JMS server, and made available for the next delivery.
9.1. Acknowledge Mechanism
- In the
CLIENT_ACKNOWLEDGE
mode, the completion state is signalized by theMessage.acknowledge()
method. - In the
AUTO_ACKNOWLEDGE
andDUPS_OK_ACKNOWLEDGE
modes, the completion is signalized by either of the following:- a successful return from one of the
MessageConsumer
.receive()
methods, or - a successful return from the
onMessage()
call of theMessageListener()
.
Note
*_ACKNOWLEDGE
was called prior to the closure of the consumer.
9.2. How to Enable Message Ordering Group
- If you define the ordering group on a connection factory, all producers on the connection factory use the same ordering group (refer to Section 9.2.1, “Enabling Ordering Group on Producer”).
- If you define the ordering group on a producer (note that the producer is defined on a connection factory), the producer uses the defined ordering group. If the connection factory of the producer defines an ordering group as well, the producer ordering group overrides the setting and uses its own ordering group (refer to Section 9.2.2, “Enabling Ordering Group on Connection Factory”).
9.2.1. Enabling Ordering Group on Producer
- Add a
JBossMessageProducer
to your session:JBossMessageProducer producer=(JBossMessageProducer)session.createProducer(queue);
- Add the enableOrderingGroup method to set an ordering group:
producer.enableOrderingGroup(String ogrpName) throws JMSException
The method creates an ordering group; when the method is called, JBossMessageProducer sends messages on behalf of the ordering group. If you providenull
as the method parameter, the ordering group is generated automatically. A new call to this method overrides the previous call. - Optionally, you can add the
disableOrderingGroup()
method to disable the ordering group:public void disableOrderingGroup() throws JMSException
When the method is called, JBossMessageProducer stops sending ordering group messages and resumes its default behavior.
$EAPHOME/doc/examples/jboss-messaging-examples/ordering-group/
in the class OrderingGroupExample.java
(src/org/jboss/example/jms/ordering/OrderingGroupExample.java
). Note that the example is delivered as part of the jboss-eap-docs
archive.
9.2.2. Enabling Ordering Group on Connection Factory
- EnableOrderingGroup
- enables the ordering group feature if set to
true
(the default value isfalse
). - DefaultOrderingGroupName
- sets the default name of the message ordering group. The group name is generated automatically if the attribute is not defined.
Note
<mbean code="org.jboss.jms.server.connectionfactory.ConnectionFactory"; name="jboss.messaging.connectionfactory:service=ConnectionFactory"; 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>/XAConnectionFactory</binding> <binding>java:/MyConnectionFactory</binding> <binding>java:/XAConnectionFactory</binding> </bindings> </attribute> <!-- The two OrderingGroup properties --> <attribute name="EnableOrderingGroup">true</attribute> <attribute name="DefaultOrderingGroupName">MyOrderingGroup</attribute> </mbean>
9.3. Notes and Limitations
- Queues must be used with the ordering group feature. The feature will not work with topics.
- The ordering group feature should not be used in conjunction with message selectors and scheduled delivery.
- A message is considered completed, and the next message will be available for delivery, if the original message is dead or has expired. A dead message is moved to the
DLQ
whereas an expired message is moved to theExpiryQueue
. - When using a
ConnectionConsumer
, the ordering of the messages will be observed. However, theConnectionConsumer
does not control which session will receive the next message. - The ordering group feature does not work with clustered queues. However, if the user deploys the clustered queue as HASingleton, which means at a time only one queue of a clustered queue is active, ordering groups work as expected.
Chapter 10. Security Configuration
suckerPassword
in the messaging and server configuration files.
jboss-as/server/$PROFILE/deploy/messaging/messaging-jboss-beans.xml
file and the messaging-service.xml
file. These files contain directives that specify the encrypted suckerPassword
.
Changing the Password in messaging-jboss-beans.xml
messaging-jboss-beans.xml
.
Procedure 10.1. Setting suckerPassword for JBoss Messaging
- Navigate to the
<JBOSS_HOME>/server/<PROFILE>/deploy/messaging/
directory. - Open the
messaging-jboss-beans.xml
file in your preferred text editor. - Change the
suckerPassword
placeholder value from"CHANGE ME!!"
to a plain text password:<property name="suckerPassword">CHANGE ME!!</property>
Make note of the new password; it will be used in the next task. - Save the file.
Creating the encrypted JBoss Messaging suckerPassword
- In a terminal, change to
<JBOSS_HOME>/server/<PROFILE>/deploy/messaging/
. - Run the following command:
/path/to/java/executable -cp JBOSS_HOME/client/jboss-messaging-client.jar org.jboss.messaging.util.SecurityUtil PLAIN_TEXT_PASSWORD
- PLAIN_TEXT_PASSWORD is the password you set in
messaging-jboss-beans.xml
in the previous task.As an example:Example 10.1. Test Encrypted Password
Running the following command (from theJBOSS_HOME/jboss-as/server/$PROFILE/deploy/messaging/
directory) .../usr/bin/java -cp ../../../../client/jboss-messaging-client.jar org.jboss.messaging.util.SecurityUtil test
...produced the following encrypted password:key len: 14 length max: 2147483647 Encoded password: 5e2c1ae5a618317
- Make note of the encrypted password output; it will be used in the next task.
Specifying an encrypted suckerPassword for JBoss Messaging
Prerequisites
- You have a terminal open at the
<JBOSS_HOME>/server/<PROFILE>/deploy/messaging/
directory.
- In a text editor, open the
messaging-service.xml
file. - Paste the encrypted password from the previous procedure into the
SuckerPassword
attribute:<attribute name="SuckerPassword">ENCRYPTED_PASSWORD</attribute>
- Save the
messaging-service.xml
file.
Appendix A. Revision History
Revision History | |||
---|---|---|---|
Revision 5.2.0-100.400 | 2013-10-31 | Rüdiger Landmann | |
| |||
Revision 5.2.0-100 | Wed 23 Jan 2013 | Russell Dickenson | |
| |||
Revision 5.1.2-100 | Thu 8 December 2011 | Russell Dickenson | |
|