Configuring and Managing WebLogic JMS

Tuning WebLogic JMS

The following sections explain how to get the most out of your applications by implementing the administrative performance tuning features available with WebLogic JMS:

Defining Quota

In prior releases, there were multiple levels of quotas: destinations had their own quotas and would also have to compete for quota within a JMS server. In this release, there is only one level of quota: destinations can have their own private quota or they can compete with other destinations using a shared quota.

In addition, a destination that defines its own quota no longer also shares space in the JMS server's quota. Although JMS servers still allow the direct configuration of message and byte quotas, these options are only used to provide quota for destinations that do not refer to a quota resource.

Quota Resources

A quota is a named configurable JMS module resource. It defines a maximum number of messages and bytes, and is then associated with one or more destinations and is responsible for enforcing the defined maximums. Multiple destinations referring to the same quota share available quota according to the sharing policy for that quota resource.

Quota resources include the following configuration parameters:

Table 9-1 Quota Parameters

Attribute	Description
Bytes Maximum and Messages Maximum	The Messages Maximum/Bytes Maximum parameters for a quota resource defines the maximum number of messages and/or bytes allowed for that quota resource. No consideration is given to messages that are pending; that is, messages that are in-flight, delayed, or otherwise inhibited from delivery still count against the message and/or bytes quota.
Quota Sharing	The Shared parameter for a quota resource defines whether multiple destinations referring to the same quota resource compete for resources with each other.
Quota Policy	The Policy parameter defines how individual clients compete for quota when no quota is available. It affects the order in which send requests are unblocked when the Send Timeout feature is enabled on the connection factory, as described in Defining a Send Timeout on Connection Factories.

For more information about quota configuration parameters, see QuotaBean in the WebLogic Server MBean Reference. For instructions on configuring a quota resource using the Administration Console, see "Create a quota for destinations" in the Administration Console Online Help.

Destination-Level Quota

Destinations no longer define byte and messages maximums for quota, but can use a quota resource that defines these values, along with quota policies on sharing and competition.

The Quota parameter of a destination defines which quota resource is used to enforce quota for the destination. This value is dynamic, so it can be changed at any time. However, if there are unsatisfied requests for quota when the quota resource is changed, then those requests will fail with a javax.jms.ResourceAllocationException.

Note: Outstanding requests for quota will fail at such time that the quota resource is changed. This does not mean changes to the message and byte attributes for the quota resource, but when a destination switches to a different quota.

JMS Server-Level Quota

In some cases, there will be destinations that do not configure quotas. JMS Server quotas allow JMS servers to limit the resources used by these "quota-less" destinations. All destinations that do not explicitly set a value for the Quota attribute share the quota of the JMS server where they are deployed. The behavior is exactly the same as if there were a special Quota resource defined for each JMS server with the Shared parameter enabled.

The interfaces for the JMS server quota are unchanged from prior releases. The JMS server quota is entirely controlled using methods on the JMSServerMBean. The quota policy for the JMS server quota is set by the Blocking Send Policy parameter on a JMS server, as explained in Specifying a Blocking Send Policy on JMS Servers. It behaves just like the Policy setting of any other quota.

Specifying a Blocking Send Policy on JMS Servers

The Blocking Send policies enable you to define the JMS server's blocking behavior on whether to deliver smaller messages before larger ones when multiple message producers are competing for space on a destination that has exceeded its message quota.

To use the Administration Console to define how a JMS server will block message requests when its destinations are at maximum quota.

Follow the directions for navigating to the JMS Server: Configuration: Thresholds and Quotas page of the Administration Console in "Configure JMS server thresholds and quota" in the Administration Console Online Help.

From the Blocking Send Policy list box, select one of the following options:

FIFO — All send requests for the same destination are queued up one behind the other until space is available. No send request is permitted to complete when there another send request is waiting for space before it.
Preemptive — A send operation can preempt other blocking send operations if space is available. That is, if there is sufficient space for the current request, then that space is used even if there are previous requests waiting for space.

For more information about the Blocking Send Policy field, see "JMS Server: Configuration: Thresholds and Quota" in the Administration Console Online Help.

Click Save.

Defining a Send Timeout on Connection Factories

The Send Timeout feature provides more control over message send operations by giving message produces the option of waiting a specified length of time until space becomes available on a destination. For example, if a producer makes a request and there is insufficient space, then the producer is blocked until space becomes available, or the operation times out.

To use the Administration Console to define how long a JMS connection factory will block message requests when a destination exceeds its maximum quota.

Follow the directions for navigating to the JMS Connection Factory: Configuration: Flow Control page in "Configure message flow control" in the Administration Console Online Help.

In the Send Timeout field, enter the amount of time, in milliseconds, a sender will block messages when there is insufficient space on the message destination. Once the specified waiting period ends, one of the following results will occur:

If sufficient space becomes available before the timeout period ends, the operation continues.
If sufficient space does not become available before the timeout period ends, you receive a "resource allocation" exception.

If you choose not to enable the blocking send policy by setting this value to 0, then you will receive a "resource allocation" exception whenever sufficient space is not available on the destination.
For more information about the Send Timeout field, see "JMS Connection Factory: Configuration: Flow Control" in the Administration Console Online Help.

Click Save.

Compressing Messages

To improve the performance of sending messages traveling across JVM boundaries and help conserve disk space, you can specify the automatic compression of any messages that exceed a user-specified threshold size. Message compression can help reduce network bottlenecks by automatically reducing the size of messages sent across network wires. Compressing messages can also conserve disk space when storing persistent messages in file stores or databases.

Note: Compressed messages may actually inadvertently affect destination quotas since some message types actually grow larger when compressed.

A message compression threshold can be set programmatically using a JMS API extension to the WLMessageProducer interface, or administratively by either specifying a Default Compression Threshold value on a connection factory or on a JMS SAF remote context.

For instructions on configuring default compression thresholds using the Administration Console, see:

Connection factories — "Configure default delivery parameters" in the Administration Console Online Help.
Store-and-Forward (SAF) remote contexts — "Configure SAF remote contexts" in the Administration Console Online Help.

Once configured, message compression is triggered on producers for client sends, on connection factories for message receives and message browsing, or through SAF forwarding. Messages are compressed using GZIP. Compression only occurs when message producers and consumers are located on separate server instances where messages must cross a JVM boundary, typically across a network connection when WebLogic domains reside on different machines. Decompression automatically occurs on the client side and only when the message content is accessed, except for the following situations:

Using message selectors on compressed XML messages can cause decompression, since the message body must be accessed in order to filter them. For more information on defining XML message selectors, see "Filtering Messages" in Programming WebLogic JMS.
Interoperating with earlier versions of WebLogic Server can cause decompression. For example, when using the Messaging Bridge, messages are decompressed when sent from the current release of WebLogic Server to a receiving side that is an earlier version of WebLogic Server.

On the server side, messages always remains compressed, even when they are written to disk.

Paging Out Messages To Free Up Memory

With the message paging feature, JMS servers automatically attempt to free up virtual memory during peak message load periods. This feature can greatly benefit applications with large message spaces. Message paging is always enabled on JMS servers, and so a message paging directory is automatically created without having to configure one. You can, however, specify a directory using the Paging Directory option, then paged-out messages are written to files in this directory.

JMS message paging saves memory for persistent messages, as even persistent messages cache their data in memory. If a JMS server is associated with a file store (either user-defined or the server's default store), paged persistent messages are generally written to that file store, while non-persistent messages are always written to the JMS server's paging directory. If a JMS server is associated with a JDBC store, then both paged persistent and non-persistent messages are always written to the JMS server's paging directory.

However, a paged-out message does not free all of the memory that it consumes, since the message header -- with the exception of any user properties, which are paged out along with the message body -- remains in memory for use with searching, sorting, and filtering.

Note: Messages that have been received by a consumer, but which have not been acknowledged, are only eligible for paging after the session is committed. Prior to that, the message will only be held in memory. Therefore, the heap size of the Java Virtual Machine (JVM) should be appropriately tuned to accommodate the projected peak amount of client load from all active sessions until they are committed.

Specifying a Message Paging Directory

If a paging directory is not specified, then paged-out message bodies are written to the default \tmp directory inside the servername subdirectory of a domain's root directory. For example, if no directory name is specified for the default paging directory, it defaults to:

bea_home\user_projects\domains\domainname\servers\servername\tmp

where domainname is the root directory of your domain, typically c:\bea\user_projects\domains\domainname, which is parallel to the directory in which WebLogic Server program files are stored, typically c:\bea\weblogic90.

Tuning the Message Buffer Size Option

The Message Buffer Size option specifies the amount of memory that will be used to store message bodies in memory before they are paged out to disk. The default value of Message Buffer Size is approximately one-third of the maximum heap size for the JVM, or a maximum of 512 megabytes. The larger this parameter is set, the more memory JMS will consume when many messages are waiting on queues or topics. Once this threshold is crossed, JMS may write message bodies to the directory specified by the Paging Directory option in an effort to reduce memory usage below this threshold.

It is important to note that this parameter is not a quota. If the number of messages on the server passes the threshold, the server will write messages to disk and evict them from memory as fast as it can to reduce memory usage, but it will not stop accepting new messages. It is still possible to run out of memory if messages are arriving faster than they can be paged out. Users with high messaging loads who wish to support the highest possible availability should consider setting a quota, or setting a threshold and enabling flow control to reduce memory usage on the server.

Controlling the Flow of Messages on JMS Servers and Destinations

With the Flow Control feature, you can direct a JMS server or destination to slow down message producers when it determines that it is becoming overloaded.

The following sections describe how flow control feature works and how to configure flow control on a connection factory.

How Flow Control Works

Specifically, when either a JMS server or it's destinations exceeds its specified byte or message threshold, it becomes armed and instructs producers to limit their message flow (messages per second).

Producers will limit their production rate based on a set of flow control attributes configured for producers via the JMS connection factory. Starting at a specified flow maximum number of messages, a producer evaluates whether the server/destination is still armed at prescribed intervals (for example, every 10 seconds for 60 seconds). If at each interval, the server/destination is still armed, then the producer continues to move its rate down to its prescribed flow minimum amount.

As producers slow themselves down, the threshold condition gradually corrects itself until the server/destination is unarmed. At this point, a producer is allowed to increase its production rate, but not necessarily to the maximum possible rate. In fact, its message flow continues to be controlled (even though the server/destination is no longer armed) until it reaches its prescribed flow maximum, at which point it is no longer flow controlled.

Configuring Flow Control

Producers receive a set of flow control attributes from their session, which receives the attributes from the connection, and which receives the attributes from the connection factory. These attributes allow the producer to adjust its message flow.

Specifically, the producer receives attributes that limit its flow within a minimum and maximum range. As conditions worsen, the producer moves toward the minimum; as conditions improve; the producer moves toward the maximum. Movement toward the minimum and maximum are defined by two additional attributes that specify the rate of movement toward the minimum and maximum. Also, the need for movement toward the minimum and maximum is evaluated at a configured interval.

Flow Control options are described in following table:

Table 9-2 Flow Control Parameters

Attribute	Description
Flow Control Enabled	Determines whether a producer can be flow controlled by the JMS server.
Flow Maximum	The maximum number of messages per second for a producer that is experiencing a threshold condition. If a producer is not currently limiting its flow when a threshold condition is reached, the initial flow limit for that producer is set to Flow Maximum. If a producer is already limiting its flow when a threshold condition is reached (the flow limit is less than Flow Maximum), then the producer will continue at its current flow limit until the next time the flow is evaluated. Once a threshold condition has subsided, the producer is not permitted to ignore its flow limit. If its flow limit is less than the Flow Maximum, then the producer must gradually increase its flow to the Flow Maximum each time the flow is evaluated. When the producer finally reaches the Flow Maximum, it can then ignore its flow limit and send without limiting its flow.
Flow Minimum	The minimum number of messages per second for a producer that is experiencing a threshold condition. This is the lower boundary of a producer's flow limit. That is, WebLogic JMS will not further slow down a producer whose message flow limit is at its Flow Minimum.
Flow Interval	An adjustment period of time, defined in seconds, when a producer adjusts its flow from the Flow Maximum number of messages to the Flow Minimum amount, or vice versa.
Flow Steps	The number of steps used when a producer is adjusting its flow from the Flow Minimum amount of messages to the Flow Maximum amount, or vice versa. Specifically, the Flow Interval adjustment period is divided into the number of Flow Steps (for example, 60 seconds divided by 6 steps is 10 seconds per step). Also, the movement (that is, the rate of adjustment) is calculated by dividing the difference between the Flow Maximum and the Flow Minimum into steps. At each Flow Step, the flow is adjusted upward or downward, as necessary, based on the current conditions, as follows: The downward movement (the decay) is geometric over the specified period of time (Flow Interval) and according to the specified number of Flow Steps. (For example, 100, 50, 25, 12.5). The movement upward is linear. The difference is simply divided by the number of Flow Steps.

For more information about the flow control fields, and the valid and default values for them, see "JMS Connection Factory: Configuration: Flow Control" in the Administration Console Online Help.

Flow Control Thresholds

The attributes used for configuring bytes/messages thresholds are defined as part of the JMS server and/or its destination. Table 9-3 defines how the upper and lower thresholds start and stop flow control on a JMS server and/or JMS destination.

Table 9-3 Flow Control Threshold Parameters

Attribute	Description
Bytes/Messages Threshold High	When the number of bytes/messages exceeds this threshold, the JMS server/destination becomes armed and instructs producers to limit their message flow.
Bytes/Messages Threshold Low	When the number of bytes/messages falls below this threshold, the JMS server/destination becomes unarmed and instructs producers to begin increasing their message flow. Flow control is still in effect for producers that are below their message flow maximum. Producers can move their rate upward until they reach their flow maximum, at which point they are no longer flow controlled.

Attribute

Description

Bytes/Messages Threshold High

When the number of bytes/messages exceeds this threshold, the JMS server/destination becomes armed and instructs producers to limit their message flow.

Bytes/Messages Threshold Low

When the number of bytes/messages falls below this threshold, the JMS server/destination becomes unarmed and instructs producers to begin increasing their message flow.

Flow control is still in effect for producers that are below their message flow maximum. Producers can move their rate upward until they reach their flow maximum, at which point they are no longer flow controlled.

For detailed information about other JMS server and destination threshold and quota fields, and the valid and default values for them, see the following pages in the Administration Console Online Help:

JMS Server: Configuration: Thresholds and Quotas
JMS Queue: Configuration: Thresholds and Quotas
JMS Topic: Configuration: Thresholds and Quotas

Handling Expired Messages

The following sections describe two message expiration features, the message Expiration Policy and the Active Expiration of message, which provide more control over how the system searches for expired messages and how it handles them when they are encountered.

Active message expiration ensures that expired messages are cleaned up immediately. Moreover, expired message auditing gives you the option of tracking expired messages, either by logging when a message expires or by redirecting expired messages to a defined "error" destination.

Defining a Message Expiration Policy

Use the message Expiration Policy feature to define an alternate action to take when messages expire. Using the Expiration Policy attribute on the Destinations node, an expiration policy can be set on a per destination basis. The Expiration Policy attribute defines the action that a destination should take when an expired message is encountered: discard the message, discard the message and log its removal, or redirect the message to an error destination.

Also, if you use JMS templates to configure multiple destinations, you can use the Expiration Policy field to quickly configure an expiration policy on all your destinations. To override a template's expiration policy for specific destinations, you can modify the expiration policy on any destination.

For instructions on configuring the Expiration Policy, click one of the following links:

Configuring an Expiration Policy on Topics

Follow these directions if you are configuring an expiration policy on topics without using a JMS template. Expiration policies that are set on specific topics will override the settings defined on a JMS template.

Follow the directions for navigating to the JMS Topic: Configuration: Delivery Failure page in "Configure message delivery failure options" in the Administration Console Online Help.

From the Expiration Policy list box, select an expiration policy option.

Discard — Expired messages are removed from the system. The removal is not logged and the message is not redirected to another location.
Log — Removes expired messages and writes an entry to the server log file indicating that the messages were removed from the system. You define the actual information that will be logged in the Expiration Logging Policy field in next step.
Redirect — Moves expired messages from their current location into the Error Destination defined for the topic.

For more information about the Expiration Policy options for a topic, see "JMS Topic: Configuration: Delivery Failure" in the Administration Console Online Help.

If you selected the Log expiration policy in previous step, use the Expiration Logging Policy field to define what information about the message is logged.

For more information about valid Expiration Logging Policy values, see Defining an Expiration Logging Policy.

Click Save.

Configuring an Expiration Policy on Queues

Follow these directions if you are configuring an expiration policy on queues without using a JMS template. Expiration policies that are set on specific queues will override the settings defined on a JMS template.

Follow the directions for navigating to the JMS Queue: Configuration: Delivery Failure page in "Configure message delivery failure options" in the Administration Console Online Help.

From the Expiration Policy list box, select an expiration policy option.

Discard — Expired messages are removed from the system. The removal is not logged and the message is not redirected to another location.
Log — Removes expired messages from the queue and writes an entry to the server log file indicating that the messages were removed from the system. You define the actual information that will be logged in the Expiration Logging Policy field described in the next step.
Redirect — Moves expired messages from the queue and into the Error Destination defined for the queue.

For more information about the Expiration Policy options for a queue, see "Configure queue message delivery failure options" in the Administration Console Online Help.

If you selected the Log expiration policy in the previous step, use the Expiration Logging Policy field to define what information about the message is logged.

For more information about valid Expiration Logging Policy values, see Defining an Expiration Logging Policy.

Click Save

Repeat steps 3-7 to configure an expiration policy for additional queues.

Configuring an Expiration Policy on Templates

Since JMS templates provide an efficient way to define multiple destinations (topics or queues) with similar attribute settings, you can configure a message expiration policy on an existing template (or templates) for your destinations.

Follow the directions for navigating to the JMS Template: Configuration: Delivery Failure page in "Configure message delivery failure options" in the Administration Console Online Help.

In the Expiration Policy list box, select an expiration policy option.

Discard — Expired messages are removed from the messaging system. The removal is not logged and the message is not redirected to another location.
Log — Removes expired messages and writes an entry to the server log file indicating that the messages were removed from the system. The actual information that is logged is defined by the Expiration Logging Policy field described in the next step.
Redirect — Moves expired messages from their current location into the Error Destination defined for the destination.

For more information about the Expiration Policy options for a template, see "JMS Template: Configuration: Delivery Failure" in the Administration Console Online Help.

If you selected the Log expiration policy in Step 4, use the Expiration Logging Policy field to define what information about the message is logged.

For more information about valid Expiration Logging Policy values, see Defining an Expiration Logging Policy.

Click Save.

Repeat steps 2-6 to configure an expiration policy for additional JMS templates.

Defining an Expiration Logging Policy

Note: The Expiration Logging Policy parameter has been deprecated in this release of WebLogic Server. In its place, BEA recommends using the Message Life Cycle Logging feature, which provide a more comprehensive view of the basic events that JMS messages will traverse through once they are accepted by a JMS server, including detailed message expiration data. For more information about message life cycle logging options, see Message Life Cycle Logging.

When the Expiration Policy is set to Log, the Expiration Logging Policy defines what information about the message is logged. Valid values for Expiration Logging Policy properties include%header%, %properties%, JMS header properties as defined in the JMS specification, the WebLogic JMS-specific extended header fields JMSDeliveryTime and JMSRedeliveryLimit, and any user-defined property. Each property must be separated by a comma.

The %header% value indicates that all header fields should be logged. The %properties% value indicates that all user properties should be logged. Neither values are case sensitive. However, the enumeration of individual JMS header fields and user properties are case sensitive.

For example, you could specify one of the following values:

JMSPriority, Name, Address, City, State, Zip
%header%, Name, Address, City, State, Zip
JMSCorrelationID, %properties%

The JMSMessageID field is always logged and cannot be turned off. Therefore, if the Expiration Policy is not defined (that is, none) or is defined as an empty string, then the output to the log file contains only the JMSMessageID of the message.

Expiration Log Output Format

When an expired message is logged, the text portion of the message (not including timestamps, severity, thread information, security identity, etc.) conforms to the following format:

<ExpiredJMSMessage JMSMessageId='$MESSAGEID' >
    <HeaderFields Field1='Value1' [Field2='Value2']  ] />
    <UserProperties Property1='Value1' [Property='Value2']  ] />
</ExpiredJMSMessage>

where $MESSAGEID is the exact string returned by Message.getJMSMessageID().

For example:

<ExpiredJMSMessage JMSMessageID='ID:P<851839.1022176920343.0' >
    <HeaderFields JMSPriority='7' JMSRedelivered='false' />
    <UserProperties Make='Honda' Model='Civic' Color='White'
     Weight='2680' />
</ExpiredJMSMessage>

If no header fields are displayed, the line for header fields is not be displayed. If no user properties are displayed, that line is not be displayed. If there are no header fields and no properties, the closing </ExpiredJMSMessage> tag is not necessary as the opening tag can be terminated with a closing bracket (/>).

For example:

<ExpiredJMSMessage JMSMessageID='ID:N<223476.1022177121567.1' />

All values are delimited with double quotes. All string values are limited to 32 characters in length. Requested fields and/or properties that do not exist are not displayed. Requested fields and/or properties that exist but have no value (a null value) are displayed as null (without single quotes). Requested fields and/or properties that are empty strings are displayed as a pair of single quotes with no space between them.

For example:

<ExpiredJMSMessage JMSMessageID='ID:N<851839.1022176920344.0' >
    <UserProperties  First='Any string longer than 32 char ...'
     Second=null Third='' />
</ExpiredJMSMessage>

Enabling Active Message Expiration

Use the Active Expiration feature to define the timeliness in which expired messages are removed from the destination to which they were sent or published. Messages are not necessarily removed from the system at their expiration time, but they are removed within a user-defined number of seconds. The smaller the window, the closer the message removal is to the actual expiration time.

Configuring a JMS Server to Actively Scan Destinations for Expired Messages

Follow these directions to define how often a JMS server will actively scan its destinations for expired messages. The default value is 30 seconds, which means the JMS server waits 30 seconds between each scan interval.

Follow the directions for navigating to the JMS Server: Configuration: General page of the Administration Console in "Configure general JMS server properties" in the Administration Console Online Help.

In the Scan Expiration Interval field, enter the amount of time, in seconds, that you want the JMS server to pause between its cycles of scanning its destinations for expired messages to process.

To disable active scanning, enter a value of 0 seconds. Expired messages are passively removed from the system as they are discovered.
For more information about the Expiration Scan Interval attribute, see "JMS Server: Configuration: General" in the Administration Console Online Help.

Click Save.