Table of Contents
This chapter describes the special functions of JEUS MQ, including Message Bridge, Message Sort, Global Order, Message Group, and Message Management.
Message Bridge is a function that connects two different MQs. The two different MQs can be classified into the following cases.
-
Different versions of the same MQ service
Two different versions of JEUS MQs that are not compatible with each other.
-
Different MQ services
JEUS MQ and another vendor's MQ (e.g., WebLogic).
[Note]
It is not recommended to configure a Message Bridge between the same versions of JEUS MQ services.
If using the same versions, it is safer and more efficient to connect a client to a remote destination. If a bridge between the same JEUS MQ service versions must be configured, add the following option to the execution script of the server on which the bridge is configured.
-Djeus.jms.client.use-single-server-entry=false
The following two configurations are required to use a Message Bridge.
-
Configure two Bridge Connections for each end of a Message Bridge.
-
Configure the actual Bridge Entry that connects the two Bridge Connections.
The following example shows how to configure a Message Bridge between WebAdmin MQ and WebLogic 10.3 MQ.
Message Bridge runs independently from JEUS MQ. To set up a Message Bridge, go to [Resources] > [Message Bridge] from the left pane of the screen.
Configure JEUS MQ and WebLogic 10.3 MQ in the Message Connections section of the Message Bridge page, and then configure the connection between two MQs in the Message Entries area.
Click on the name of the Message Connection or Message Entry to configure its properties. When the Connection page or Bridge page appears, configure the required items and click [OK] to save the configuration. To reconfigure the settings, click [Reset].
The following are the Connection and Bridge pages.
-
Configuring a Bridge Connection for JEUS
-
Configuring a Bridge Connection for WebLogic 10.3
-
Configuring a Bridge Entry
If there is a message producer but no consumer in a queue, or if there is a message consumer but the message reception is relatively slow, the messages accumulate in the queue. The message sort function is used to sort the queued messages according to the user defined key values.
Messages can also be accumulated in a durable subscriber which is similar to a queue, and the message sort function can also be used. The key values include the basic JMS property values or user-defined property values (User Property).
Message sorting is configured differently for servers and clients. To enable message sorting, servers are configured using WebAdmin and clients are configured in the message properties.
To configure a server for message sorting, go to [Servers] > [Select a Server] > [Engine] > [Jms Engine] > [Message Sort].
To enable message sorting, a server has to be configured as in the following.
The previous message sorting configuration can be applied for a Destination or Durable Subscriber. For more information, refer to "3.2.1. Configuring Destinations" and "3.2.2. Configuring Durable Subscribers".
The messages that do not correspond to the configured key value are not sorted, and the original order is guaranteed. This means that if there is a mixture of messages that correspond to and do not correspond to a key value in the queue, the former will be sorted in the configured order, and the latter will be kept in their original order.
Global Order ensures that the messages queued at the destination are delivered to a client exactly one at a time.
In general, messages are processed simultaneously by multiple clients and there is no way to control the processing order of the messages. If multiple messages are sent in parallel, they are processed regardless of the order in which they are sent. Although this does not impact system performance, the global order function can be used to ensure the message processing order.
The client can use the Global Order API without additional configurations.
Note
For a single message consumer, Global Order does not change the existing order. Hence, to use Global Order, multiple message consumers have to be configured for the destination.
In the following example, a message sender creates a Producer and casts the message to JeusMessageProducer, and then calls the Global Order API.
JeusMessageProducer producer = (JeusMessageProducer) session.createProducer(queue);
// Set Global Order and assign a name.
producer.startGlobalOrder("GLOBAL-ORDER-NAME");
// If a name is not specified.
//producer.startGlobalOrder();
The GLOBAL-ORDER-NAME identifies the
Global Order. If it is not configured, a random name is assigned.
The Global Order name can be shared by multiple clients.
Note
If this function is used with clustering, the processing order is applied to the entire cluster.
Message Group is a function that sends a group of messages that have the same purpose and are all queued at a destination to a single message consumer. For example, if 10 messages are set in a group, the messages are not delivered to the consumer until all 10 messages are in the queue. This is similar to the transaction mechanism and can be used for similar purposes, and it can also be used with clustering.
This section describes the server configurations required to enable Message Group. A Message Group is set in the Destination page. For more information about the destination page, refer to "3.2.1. Configuring Destinations".
Note
If the Expiration Time is not configured, the Message Groups that have not yet been delivered remain on the server indefinitely. To avoid memory leaks, the Expiration Time must be set with care.
In the client configuration, the Message Producer and Message Consumer settings must be configured.
-
Configuring the Message Producer
To configure the Message Producer, use the message's User Property.
Message msg = session.createMessage(); // Set the Message Group name. The name identifies the Group. msg.setStringProperty("JMS_JEUS_MSG_GROUP_NAME", "
MESSAGE-GROUP-NAME"); // Set the order of the messages in the Group. The messages are delivered to the destination in this order. msg.setIntProperty("JMS_JEUS_MSG_GROUP_NUMBERING", 1); producer.send(msg); msg = session.createMessage(); msg.setStringProperty("JMS_JEUS_MSG_GROUP_NAME", "MESSAGE-GROUP-NAME"); msg.setIntProperty("JMS_JEUS_MSG_GROUP_NUMBERING", 2); producer.send(msg); . . . msg = session.createMessage(); msg.setStringProperty("JMS_JEUS_MSG_GROUP_NAME", "MESSAGE-GROUP-NAME"); msg.setIntProperty("JMS_JEUS_MSG_GROUP_NUMBERING", 10); // Set the last message of the Group. msg.setBooleanProperty("JMS_JEUS_MSG_GROUP_END", true); producer.send(msg); -
Configuring the Message Consumer
The Message Consumer receives the Message Group as an ObjectMessage that contains the messages.
// The message group is a ObjectMessage that is a list of the messages. ObjectMessage result = (ObjectMessage) receiver.receive(TIME_OUT); List list = (List) result.getObject(); int cnt = 1; // Each message can be retrieved from the list one at a time. for(Object obj : list) { // Messages are processed in the order specified by the message producer. TextMessage msg = (TextMessage) obj; . . . }
Message Management function is used to check, move, and delete the messages at the destination while using the JEUS MQ messaging services. The Message Management features can be grouped into the following three categories.
-
Message Monitoring
Monitors messages in a destination.
-
Message Control
Controls messages by moving, deleting, exporting, and importing them.
-
Destination Control
Controls destinations for flexible message monitoring and control.
Message monitoring and control are supported for the messages in a queue or durable subscriber. Destination control is provided for the messages in the queues and topics.
Monitors messages in a Queue or Durable Subscriber.
-
Message List Search
Searches the list of the messages in a Queue or Durable Subscriber.
-
Detailed Message Information Search
Retrieves the detailed information about each message.
Searching the Message List
The messages in a Queue or Durable Subscriber are monitored by using its ID, type, creation time, etc. A message can be selected from the list to perform various monitoring functions such as search, delete, move, export, etc.
Note
Since JMS messages are created and consumed quickly, if the messages are searched without enabling the Consumption Suspended setting in the Destination page, the search result may contain a message that has already been consumed.
Following are the steps for searching the message list.
-
Different menus are used depending on where the message is.
-
Messages in a Queue
Go to [Monitoring] > [JMS] > [Destinations] > [Server], and select a server from the drop-down list. The list of destinations in the server appears.
-
Messages in a Durable Subscriber
Go to [Monitoring] > [JMS] > [Durable Subscriptions] > [Server], and select a server from the drop-down list. The list of Durable Subscriptions of the server appears.
-
-
When [browse] on the Queue or Durable Subscription is clicked, the Message List window in which the list of messages can be retrieved appears.
A message list can be searched by using the message ID, type, or creation type, or the message selector can be used to select a specific message. To retrieve all messages in the Queue or Durable Subscription, click [OK] without selecting any items in the Message List window.
-
The following shows the list of messages at the destination. A message can be checked to delete, move, or export. Detailed information about each message is provided by clicking on the ID in the Message ID column.
Retrieving Detailed Message Information
The detailed information about messages in the Queues or Durable Subscribers can be retrieved. It is possible to check the header information defined in JMS specification, message information, and configured properties.
Note
Since JMS messages are created and consumed quickly, if the messages are searched without enabling the Consumption Suspended setting in the Destination page, the search result may contain a message that has already been consumed. Unless the consumption is suspended while modifying the message information, the modified result cannot be guaranteed.
The following are the steps for retrieving detailed information about messages.
-
The detailed information about each message can be retrieved by clicking on a specific Message ID from the list of searched messages.
-
The following screen shows the retrieved message information.
Message contents and properties can be modified when the message type is set to 'Text'. To change the message information, click [OK]. Click [Reset] to reset the modified information.
The following message control functions are provided in WebAdmin.
-
Moving Messages
Moves messages to another destination on a server or cluster.
-
Deleting Messages
Deletes messages from the Queue or Durable Subscriber.
-
Exporting Messages
Exports certain messages on a server or cluster to another server or cluster.
-
Importing Messages
Imports the exported messages to a specific destination on a server or cluster.
Moving Messages
Messages can be moved to another destination on a server or cluster. This function is useful for handling errors such as sending messages to a wrong destination.
Note
1. Since JMS messages are created and consumed quickly, if the messages are searched without enabling the Consumption Suspended setting in the Destination page, the search result may contain a message that has already been consumed.
2. Messages can be moved to another destination. If there is a message at the destination that has the same ID as the new message, the new message overwrites the existing one.
If the old message is already sent to the client while attempting to overwrite it, a client-server data synchronization error will occur. It is recommended to enable the Consumption Suspended setting before moving a message.
The following example shows how to move a message.
-
Select the message to move from the list of messages, and then click [move].
-
Select a destination from the Target drop-down list in the Move Message page. When All is checked, all messages in the Queue or Durable Subscriber will be moved to the destination. Specify the required properties and click [OK]. The selected messages will be moved to the destination.
Deleting Messages
Messages are deleted when they are no longer needed.
Note
Since JMS messages are created and consumed quickly, if the messages are deleted without enabling the Consumption Suspended setting in the Destination page, the search result may contain a message that has already been consumed. It is recommended to enable the Consumption Suspended setting before deleting a message.
The following example shows how to delete a message.
-
Select the message to delete from the list of messages, and then click [remove].
-
To delete a message from the server, click [OK] in the Remove Message window. When All is checked, all messages at the destination are removed.
Exporting Messages
The messages in a Queue or Durable Subscriber can be exported to another server or cluster.
Note
Since JMS messages are created and consumed quickly, if the messages are exported without enabling the Consumption Suspended setting in the Destination page, the search result may contain a message that has already been consumed. It is recommended to enable the Consumption Suspended setting before exporting a message.
The following example shows how to export a message.
-
Select the message to export from the list of messages, and then click [export].
-
When All is checked in the Message Export window, all messages at the Destination or Durable Subscription can be exported. Click [OK] to export the message(s) and then download the "message.xml" file through the browser.
Importing Messages
Messages can be imported to a destination as XML formatted data. An imported message is treated as a new message. Therefore, a new message ID is assigned to the message when it is imported to a destination.
Note
If the 'Overwrite' checkbox is checked when importing messages, some messages that are overwritten may already have been delivered to the clients. In this case, messages are imported successfully but incorrectly overwritten. Hence, it is recommended to enable the Consumption Suspended setting before importing a message.
The following example shows how to import a message.
-
Go to [Monitoring] > [JMS] > [Destinations] > [Server] in WebAdmin. Click [import] of the destination to import messages to.
-
Enter the required properties in the Message Import page, and then click [OK] to import the messages. When Overwrite is checked, the message IDs of the messages being imported are used. If the same message ID already exists at the destination, the new message overwrites the existing one.
Message production and consumption can be suspended or resumed at each destination.
-
Suspending or Resuming Message Production at a destination.
-
Suspending or Resuming Message Consumption at a destination.
Suspending or Resuming Message Production at a Destination
Message production at a destination can be suspended or resumed. When message production is suspended at a destination, messages cannot be created at the Destination.
Go to [Monitoring] > [JMS] > [Destinations] > [Server] in WebAdmin. A list of destinations on the server appears.
The Production Suspended setting enables users to check the current state of message production at the destination. The destination state can be changed using the true or false button.
| Configuration Value | Description |
|---|---|
| true | Message production at the destination is currently suspended. |
| false | Messages are being normally produced at the destination. |
Note
When messages are sent to a destination where message production has been suspended ("Production Suspended" is set to true), the server waits for a given time and then a jeus.jms.common.destination.InvalidDestinationStateException is raised through the ExceptionListener.
Suspending or Resuming Message Consumption at a Destination
Message consumption at a destination can be suspended or resumed. When message consumption is suspended at a destination, messages cannot be consumed from the Destination.
Go to [Monitoring] > [JMS] > [Destinations] > [Server] in WebAdmin. A list of destinations on the server appears.
The Consumption Suspended setting enables the users to check the current state of message consumption at the destination. The destination state can be changed using the true or false button.
| Configuration Value | Description |
|---|---|
| true | Message consumption from the destination is currently suspended. |
| false | Messages are being normally consumed from the Destination. |
Note
When trying to consume messages from a Destination for which message consumption has been suspended ("Consumption Suspended" is set to true), the server will operate as if there are no messages at the destination.
When a message is sent using JEUS MQ, using the Persistent Store ensures reliable messaging even in case of a failure. This only guarantees reliable message delivery between the JEUS MQ server and message recipient, but not when a message is sent to the server and the server or the client fails.
To compensate for this, JEUS MQ provides a function to increase the reliability between the sender and the JEUS MQ server using the Local Persistent Queue that is similar to the persistence store. The Local Persistent Queue(hereafter LPQ) saves data in the local storage and ensures that the stored data is processed normally. JEUS MQ saves messages using LPQ before they are sent and attempts to send the messages until they are successfully sent to the server. This helps to increase the reliability of the message transmission between the sender and the server.
Reliable message transmission using LPQ has the following characteristics.
-
Retransmitting messages until it succeeds regardless of the server status
-
Recovery of messages that failed to be sent due to abnormal client status
-
Asynchronous messaging
Note
When the JMS client is sending a message, if the client is a Java EE application that is deployed on the JMS server, which is the message recipient, the message is not sent over the network to improve performance. In this case, the LPQ configuration is ignored.
To use reliable messaging through LPQ, LPQ must be activated first. This requires the creation of a storage for storing, a queue for processing, and an object for managing the messages.
Note
To execute a standalone client that uses LPQ, LPQ and storage libraries are additionally needed. The libraries are jeus-lpq-spi.jar, jeus-lpq.jar, jms-extentsion.jar, and jeus-store.jar, which are in the JEUS_HOME/lib/system folder.
There are three ways to activate LPQ.
-
Using the JVM option
When a JEUS MQ client is executed, the JVM option is applied to activate LPQ as in the following. This option activates LPQ when JMS creates a connection in the client.
-Djeus.jms.client.send-by-lpq-only=true
-
Using the LPQ configuration file
When a JEUS MQ client is executed, LPQ is activated as it is configured by reading the file if the LPQ configuration file can be found in the designated path. For detailed information about the LPQ configuration file path and how to configure it, refer to "6.6.4. LPQ Configuration".
-
Using the API for JEUS
LPQ can be activated in the client source code by using the following API of JeusSession, a JEUS session object.
public void startLPQ();
Note
1. The LPQ operation can be configured through the configuration file or system property when the JVM option or JEUS API is used. The default value is applied for unconfigured items. For detailed information about LPQ configuration, refer to "6.6.4. LPQ Configuration".
2. If JEUS API is not used, when LPQ will be activated is not specified. In this case, LPQ is activated when the JVM creates the first connection. LPQ terminates when the last connection is closed. However, if LPQ still has messages, it does not terminate until they have been processed.
Once LPQ is activated, a message can be sent more reliably by using LPQ. There are three configuration units for sending messages through LPQ.
-
JVM Unit Configuration
Used when LPQ is activated by using the JVM option. All messages from the JVM are sent through LPQ.
-
ConnectionFactory Unit Configuration
When the Connection Factory names to use LPQ are added to the JVM option, all the messages that are sent from the connections created by the Connection Factory are sent through LPQ. Connection factory names are separately by a commas (,).
jeus.jms.client.connection-factory-for-lpq=<ConnectionFactoryName1,ConnectionFactoryName2,..>Note
JMS specifications do not have naming limits for connection factories. However, if a commas is used, the above option cannot be normally applied and the LPQ function cannot be used.
-
Session Unit Configuration
Used to specify whether to send messages to each session by using LPQ. The following API of the JEUS message sender object can be used to send all messages that will be sent to the session by using LPQ.
public void setLPQOnly(boolean lpqOnly);
-
Message Unit Configuration
Used to specify whether to send each message through LPQ. Either use the following APIs of the JEUS message sender object, or configure the User Property of the message.
// JEUS APIs public void sendWithLPQ(Message message); public void sendWithLPQ(Message message, int deliveryMode, int priority, timeToLive); public void sendWithLPQ(Destination destination, Message message); public void sendWithLPQ(Destination destination, Message message, int deliveryMode, int priority, timeToLive); // User Property of JMS message Message msg = session.createMessage(); msg.setBooleanProperty("JMS_JEUS_USE_LPQ",true);Note
LPQ activation by using JEUS API only enables LPQ to be used in the corresponding session. LPQ configuration for messages that are sent using other sessions is ignored.
When LPQ is used to send messages, the messages are processed asynchronously. Therefore, the client does not know whether a message has been sent or not. LPQ provides a listener to be able to get the message transmission time and result.
The following jeus.jms.LPQMessageListener interface is provided to get the message transmission result through the listener.
package jeus.jms;
public interface LPQForwardListener {
/**
* Event that is triggered when message transmission is complete
* @param message = A transmitted message
*/
public void onComplete(Message message);
/**
* Event that is triggered when an Exception occurs while a message is being transmitted
* @param message = A message to transmit
* @param e = An exception that occurred
*/
public void onException(Message message, Exception e);
/**
* Event that is triggered when the message transmission fails
*
* @param message = A message that failed to be transmitted
* @param cause = A cause for the failed transmission
*/
public void onFailure(Message message, Throwable cause);
}
The message transmission result can be obtained by setting the implemented LPQMessageListener to the JeusSession object by using the following API.
public void setLPQMessageListener(jeus.jms.LPQMessageListener lpqMessageListener);
When using JEUS object to activate LPQ, the following API can be used to both activate LPQ and set the listener.
public void startLPQ(jeus.jms.LPQMessageListener lpqMessageListener);
LPQ Configurations include items for processing failed transmissions, operation during disconnection, and the storage size or location.
-
LPQ Configuration Items
-
Common Items
Item Type Description jeus.lpq.name String LPQ name. (Default: JEUS_LPQ) jeus.lpq.max-message-count int Maximum number of messages that LPQ can process at a time. (Default: 819200) jeus.lpq.time-to-live long How long a message can remain in LPQ. (Default: 43200000ms (12hours)) -
Transmission-Related Items
Item Type Description jeus.lpq.retry-limit int Number of attempts to resend a a failed message. If set to 0 or less, retries are attempted indefinitely.
(Default: -1)
jeus.lpq.retry-interval long Transmission interval for resending a message. (Default: 1000ms) jeus.lpq.retry-interval-increment long Increment to increase the retry interval every time a message is resent. (Default: 0ms) -
Reconnection-related Items
Item Type Description jeus.lpq.reconnect-retry-interval long Interval for reconnecting when the connection is lost.
(Default: 5000ms)
-
Storage-related Items
Item Type Description jeus.lpq.store.store-mode int Storage type. Set to 1 to use the journal store and 2 to use the memory storage. (Default: 1) jeus.lpq.store.journal.store-base- dir String Name of the directory to create the Store in. The name must be unique per LPQ configuration and two or more concurrent connections are not allowed.
If set to a relative path, it is set to a path under the directory where the configuration file exists or JVM is running.
(Default: JEUS_LPQ_STORE)
jeus.lpq.store.journal.initial-log- file-count int Number of log files to create initially when creating the Journal Store. (Default: 2) jeus.lpq.store.journal.max-log-file- count int Maximum number of log files to create.
(Default: 10)
jeus.lpq.store.journal.log-file-size String Log file size. (Default: 64M)
Append one of the following text after an integer value or number.
-
'K'(KiloBytes)
-
'M'(MegaBytes)
-
'G'(GigaBytes)
-
-
-
How to Configure LPQ
-
Configuration File
When LPQ configuration file exists in the specified location, the configurations in the file are applied when LPQ is activated. Find the configuration file in order of 'APP_HOME/WEB-INF/', 'APP_HOME/META-INF/', and 'APP_HOME/'. The default value of the detailed configuration file path is 'jeus-lpq.properties' and can be changed using the following option.
-Djeus.jms.client.lpq-configuration-path=jeus-lpq.properties
The following is an example of the LPQ configuration file. The name of this example file is 'jeus-lpq.properties', and the file exists in 'JEUS_HOME/templates/lpq/'.
#JEUS Local-Persistent-Queue Configuration #[commons] jeus.lpq.name=JEUS_LPQ jeus.lpq.max-message-count=819200 jeus.lpq.time-to-live=43200000 #[forward] jeus.lpq.retry-limit=-1 jeus.lpq.retry-interval=1000 jeus.lpq.retry-interval-increment=0 #[reconnect] jeus.lpq.reconnect-retry-interval=5000 #[store] jeus.lpq.store.store-mode=1 #[journal-store] jeus.lpq.store.journal.store-base-dir=JEUS_LPQ jeus.lpq.store.journal.max-log-file-count=10 jeus.lpq.store.journal.initial-log-file-count=2 jeus.lpq.store.journal.log-file-size=64M
-
System Property
The previous configuration items can be set as system properties by using each item name as the key. For instance, if the LPQ name is configured, the JVM option can be configured when a JEUS MQ client is executed as in the following.
-Djeus.lpq.name=<jeus lpq name>Runtime Configurations can be modified by changing the client source code.
System.setProperty("jeus.lpq.name",<jeus lpq name>);
Note
The order of configuration is runtime property configuration > configuration file > JVM option.
-