Chapter 6. JEUS MQ Special Functions

6.1. JEUS MQ Message Bridge

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

6.1.1. Server Configuration

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.

[Figure 6.1] Message Bridge Configuration

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

[Figure 6.2] Configuring a Bridge Connection for JEUS
Configuring a Bridge Connection for WebLogic 10.3

[Figure 6.3] Configuring a Bridge Connection for WebLogic 10.3
Configuring a Bridge Entry

[Figure 6.4] Configuring a Bridge Entry to Connect the 2 Bridge Connections

6.2. JEUS MQ Message Sort

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.

6.2.1. Server Configuration

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.

[Figure 6.5] Message Sort Configuration

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".

[Figure 6.6] Applying Message Sorting for a Destination

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.

6.2.2. Client Configuration

A client can configure a key value that defines the Message Sorting property.

In the following example, the message sort key property is set to "TEST_KEY" that is used to sort messages.

Message msg = session.createTextMessage("Test");
                msg.setIntProperty("TEST_KEY", 1);

6.3. JEUS MQ Global 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.

6.3.1. Client Setting

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.

6.4. JEUS MQ Message Group

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.

6.4.1. Server Setting

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".

[Figure 6.7] Message Group Configuration

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.

6.4.2. Client Configuration

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;
    . . .   
}

6.5. JEUS MQ Message Management

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.

6.5.1. Message Monitoring

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.

[Figure 6.8] Searching for Messages by Destination

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.

[Figure 6.9] Searching for Messages by Durable Subscription
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.

[Figure 6.10] Searching for Messages
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.

[Figure 6.11] Search Results

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.

[Figure 6.12] Retrieving Detailed Message Information
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.

[Figure 6.13] Detailed Message Information

6.5.2. Message Control

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].

[Figure 6.14] Moving a Message
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.

[Figure 6.15] Moving a Message

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].

[Figure 6.16] Deleting a Message
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.

[Figure 6.17] Deleting a Message

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].

[Figure 6.18] Exporting Messages
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.

[Figure 6.19] Exporting Messages

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.

[Figure 6.20] Importing Messages
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.

[Figure 6.21] Importing Messages

6.5.3. Destination Control

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.

[Figure 6.22] Controlling Message Production

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.

Production Suspended	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.

[Figure 6.23] Controlling Message Consumption

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.

Consumption Suspended	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.

6.6. Reliable Message Transmission

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.

6.6.1. LPQ Activation

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

LPQ also requires client and storage libraries, jeus-lpq.jar and jeus-store.jar, that 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.

6.6.2. LPQ Configuration

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

Used when LPQ is activated by using the LPQ configuration file. When the Connection Factory names to use LPQ is added to the LPQ configuration, all the messages that are sent from the connections created by the Connection Factory are sent through LPQ.
```
jeus.jms.client.jms-connection-factory-list=<ConnectionFactoryName>
```

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.

6.6.3. LPQ Listener Configuration

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);

6.6.4. LPQ Configuration

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)

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)

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.

Prev		Next
Chapter 5. JEUS MQ Failover	Home	Appendix A. Additional Journal Store Properties