Skip navigation.
Downloads | Product Documentation | Support

Administration Console Online Help

# JMS: Tuning

[Attributes and Console Screen Reference for 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:

- Overview
- Improving JMS File Store Performance
- Tuning Distributed Destinations
- Paging Out Messages To Free Up Memory
- Controlling the Flow of Messages on JMS Servers and Destinations
- Avoiding Quota Exceptions by Blocking Message Producers
- Handling Expired Messages

You may also want to refer these WebLogic JMS and Messaging Bridge sections:

- JMS: Configuring
- JMS: Monitoring
- Messaging Bridge

# Overview

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

- Improving JMS File Store Performance
- Tuning Distributed Destinations
- Paging Out Messages To Free Up Memory
- Controlling the Flow of Messages on JMS Servers and Destinations
- Avoiding Quota Exceptions by Blocking Message Producers
- Handling Expired Messages

# Improving JMS File Store Performance

By default, WebLogic JMS file stores guarantee up-to-the-message integrity by using synchronous writes to a disk. Disabling the default Synchronous Writes Policy of "Cache-Flush" improves file store performance, often quite dramatically, but at the expense of possibly losing sent messages or generating duplicate received messages (even if messages are transactional) in the event of an operating system crash or a hardware failure. Simply shutting down an operating system does not generate these failures, as an operating system flushes all outstanding writes during a normal shutdown. Instead, these failures can be emulated by shutting the power off to a busy server.

Note: The Synchronous Write Policy is ignored if the file store is used exclusively for paging non-persistent messages to disk.

## Disabling the Default Synchronous Writes Policy

To modify the default Cache-Flush policy:

1. Expand the JMS —> Stores node. The JMS Stores table displays in the right pane showing all the JMS stores.
2. Select the JMS file store that you want to modify. A dialog shows the tabs associated with modifying an existing file store.
3. On the Configuration tab, select a Synchronous Write Policy to determine how this JMS file store writes data to disk.

- Disabled - Transactions are complete as soon as their writes are cached in memory, instead of waiting for the writes to successfully reach the disk. This policy is the fastest, but the least reliable (that is, transactionally safe).
- Cache-Flush - Transactions cannot complete until all of their writes have been flushed down to disk. The default policy, it is reliable and scales well as the number of simultaneous users increases.
- Direct-Write - File store writes are written directly to disk for Solaris and Window operating systems. This policy's speed depends on whether on-disk cache is enabled for operating system.

For more detailed information about the Synchronous Write Policy attributes, see JMS File Store --> Configuration.

4. Click Apply to save your change.

### Disabling the On-Disk Cache For a Disk Drive on Windows 2000

Although the use of the Direct-Write policy is transactionally reliable on Solaris systems, Windows systems may leave transaction data in the on-disk cache without writing it to disk immediately. This is not considered to be transactionally reliable, since a power failure can cause loss of on-disk cache data — possibly resulting in lost and/or duplicate messages. For reliable writes using Direct-Write on Windows, either disable all write caching for the disk (enabled by default), or use a disk with a battery-backed cache. Some file systems, however, do not allow this value to be changed (for example, a RAID system that has a reliable cache).

1. Open the Control Panel -> System Properties dialog box.
2. Select the Hardware tab.
3. Click the Device Manager button.
4. Expand the Disk Drives node on the Device Manager tree.
5. Double-click the drive name that you want to modify.
6. On the Properties dialog box, select the Disk Properties tab.
7. Clear the Write Cache Enabled check box.

## Comparing Synchronous Write Policy Settings

The following tables compare the synchronous write policies with respect to reliability, performance, and scalability. Use the following key to interpret the expected results based on your synchronous write policy settings.

- Disk Cache On/Off: the on-disk write cache is enabled/disabled
- 1-m Perf: very few clients
- m-m Perf: many clients
- M-M Perf: a large amount of concurrent clients
- Reliability Low/High: High reliability is needed for exactly-once (transactional) messaging

Table 52-1 Relative Performance (compare within same column)

Policy | Disk Cache | 1-m Perf | m-m Perf | M-M Perf | Reliability
--- | --- | --- | --- | --- | ---
Disabled | On | `****` | `****` | `****` | Low (depends on OS cache)
Off | `****` | `****` | `****` | Low
Cache-Flush | On | `*` | `**` | `***` | High
Off | `*` | `**` | `***` | High
Direct-Write | On | `**` | `***` | `**` | Medium (High with reliable disk-cache
Off | `**` | `*` | `*` | High

Table 52-2 Relative Scalability (compare within same row)

Policy | Disk Cache | 1-m Perf | m-m Perf | M-M Perf
--- | --- | --- | --- | ---
Disabled | On | `****` | `****` | `****`
Off | `****` | `****` | `****`
Cache-Flush | On | `*` | `**` | `***`
Off | `*` | `**` | `***`
Direct-Write | On | `*` | `**` | `***`
Off | `*` | `*` | `*`

# Tuning Distributed Destinations

The following sections describe how to tune a distributed destination by configuring attributes on a JMS connection factory.

- Configuring Message Load Balancing Across a Distributed Destination
- Configuring Server Affinity For a Distributed Destination

For more information about configuring a distributed destination, see JMS Distributed Destination Tasks.

## Configuring Message Load Balancing Across a Distributed Destination

The Load Balancing Enabled attribute on the JMS Connection Factory —> Configuration —> General tab defines whether non-anonymous producers created through a connection factory are load balanced within a distributed destination on a per-call basis. Applications that use distributed destinations to distribute or balance their producers and consumers across multiple physical destinations, but do not want to make a load balancing decision each time a message is produced, can turn off the Load Balancing Enabled attribute.

To ensure a fair distribution of the messaging load among a distributed destination, the initial physical destination (queue or topic) used by producers is always chosen at random from among the distributed destination members.

To configure load balancing on a connection factory:

1. Expand the JMS node.
2. Click the Connection Factories node. The JMS Connection Factories table displays all the connection factories defined in your domain.
3. Click the connection factory on which you want to establish message load balancing. A dialog displays in the right pane showing the tabs associated with modifying a connection factory.
4. Define the setting of the Load Balancing Enabled attribute on the General tab using the following guidelines:

- `Load Balancing Enabled = True`
  For `Queue.sender.send()` methods, non-anonymous producers are load balanced on every invocation across the distributed queue members.
  For `TopicPublish.publish()` methods, non-anonymous producers are always pinned to the same physical topic for every invocation, irrespective of the Load Balancing Enabled setting.
- `Load Balancing Enabled = False
  `Producers always produce to the same physical destination until they fail. At that point, a new physical destination is chosen.

5. Click Apply to save your changes.

Note: Depending on your implementation, the setting of the Server Affinity Enabled attribute can affect load balancing preferences for distributed destinations. For more information, see "How Distributed Destination Load Balancing Is Affected When Using the Server Affinity Enabled Attribute" in Programming WebLogic JMS.

Anonymous producers (producers that do not designate a destination when created), are load-balanced each time they switch destinations. If they continue to use the same destination, then the rules for non-anonymous producers apply (as stated previously).

For more information about how message load balancing takes place among the members of a distributed destination, see "Load Balancing Messages Across a Distributed Destination" in Programming WebLogic JMS.

## Configuring Server Affinity For a Distributed Destination

The Server Affinity Enabled attribute on the JMS Connection Factory —> Configuration —> General tab defines whether a WebLogic Server that is load balancing consumers or producers across multiple physical destinations in a distributed destination set, will first attempt to load balance across any other physical destinations that are also running on the same WebLogic Server.

Note: The Server Affinity Enabled attribute does not affect queue browsers. Therefore, a queue browser created on a distributed queue can be pinned to a remote distributed queue member even when Server Affinity is enabled.

To disable server affinity on a connection factory:

1. Expand the JMS node.
2. Click the Connection Factories node. The JMS Connection Factories table displays in the right pane showing all the connection factories defined in your domain.
3. Click the connection factory on which you want to disable server affinity. A dialog displays in the right pane showing the tabs associated with modifying a connection factory.
4. Define the Server Affinity Enabled attribute in the General tab.

- If the Server Affinity Enabled check box is selected (True), then a WebLogic Server that is load balancing consumers or producers across multiple physical destinations in a distributed destination set, will first attempt to load balance across any other physical destinations that are also running on the same WebLogic Server.
- If the Server Affinity Enabled check box is not selected (False), then a WebLogic Server will load balance consumers or producers across physical destinations in a distributed destination set and disregard any other physical destinations also running on the same WebLogic Server.

5. Click Apply to save your changes.

For more information about how the Server Affinity Enabled setting affects the load balancing among the members of a distributed destination, see "How Distributed Destination Load Balancing Is Affected When Using the Server Affinity Enabled Attribute" in Programming WebLogic JMS.

# Paging Out Messages To Free Up Memory

With the message paging feature, you can free up virtual memory during peak message load periods. This feature can greatly benefit applications with large message spaces.

JMS message paging saves memory for both persistent and non-persistent messages, as even persistent messages cache their data in memory. Paged persistent messages continue to be written to the regular backing store (file or database); and paged non-persistent messages are written to the JMS server's message paging store, which is configured separately.

A paged-out message does not free all of the memory that it consumes. The message header and message properties remain in memory for use with searching, sorting, and filtering.

Note: Messages sent in a transacted session 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. For more information on tuning your heap size, see "Tuning Java Virtual Machines (JVMs)" in WebLogic Performance and Tuning.

## Configuring Message Paging

Unless paging is configured and enabled, all messages (even persistent ones) are held in memory. You can configure paging for a JMS server and/or specific destinations. Using the paging attributes on the JMS Server node you can specify a paging store for a JMS server, enable bytes and/or messages paging, and configure bytes/messages high and low thresholds to start and stop paging. Similarly, using the paging attributes on the Destinations node, you can configure bytes/messages paging for all topics and queues configured on a JMS server. The destinations use a dedicated paging store that is configured for the JMS server.

Note: Message paging is not enabled by default. However, a message paging store will be automatically created when either bytes paging or messages paging is enabled on the JMS server or it's destinations without preconfiguring a message paging store.

Also, if you use JMS templates to configure multiple destinations, you can use the attributes on the Templates node to configure paging quickly on all your destinations. To override a template's paging configuration for specific destinations, you can enable or disable paging on any destination.

For instructions on configuring a new JMS server, destinations (topics and queues), and templates, see JMS Server Tasks, JMS Queue and Topic Destination Tasks, and JMS Template Tasks.

Note: For performance tuning purposes, you can modify the paging thresholds to any legal value at any time. Once paging is enabled, however, you cannot dynamically disable it by resetting a byte or message threshold back to -1. To prevent paging from occurring, set the byte/message high threshold to a very large number (maximum is 263 -1), so that paging is not triggered.

### Configuring a Message Paging Store for a JMS Server

Each JMS server must have its own paging store, which is used exclusively for paging out non-persistent messages for the JMS server and its destinations. It's best to use a JMS file store rather than a JMS JDBC store, as the JDBC store will perform poorly in comparison without any real benefit.

You can create a message paging store manually, or one will be created automatically when either bytes paging or messages paging is enabled on the JMS server or it's destinations without preconfiguring a message paging store.

To configure a new message paging store:

1. Expand the JMS —> Stores node. The right pane shows all the JMS stores.
2. Click the Create a new JMS File Store text link. The right pane shows the tabs associated with configuring a new JMS file store.
3. On the Configuration tab, define the file store attributes:

- Enter a name for the message paging file store. This name must be unique within the WebLogic Server instance or its cluster.
- When a file store is used exclusively for paging out messages to disk, the Synchronous Write Policy is ignored.
- Enter the pathname to the directory on the file system where the file store is kept. (This directory must exist on your system, so be sure to create it before completing this tab.)

For more information about the JMS file store attributes, see JMS File Store --> Configuration.

4. Click Create to create a JMS file store instance with the name you specified in the Name field. The new instance is added under the JMS Stores node in the left pane.
5. If you have multiple JMS servers in your domain, repeat steps 3-5 for each server instance.

### Configuring Message Paging on a JMS Server

To enable and configure paging on an existing JMS server:

1. Click the JMS Servers node. The right pane shows all the servers defined in your domain.
2. Click the server that you want to configure for paging. The right pane shows the tabs associated with configuring the server.
3. On the General tab, use the Paging Store list box to select the JMS file store that you configured for paged messages. Click Apply to save your changes.

For instructions on configuring a paging store, refer to Configuring a Message Paging Store for a JMS Server.

4. On the Thresholds & Quotas tab, configure bytes paging:

- Select the Bytes Paging Enabled check box.
- In the Bytes Threshold High field, enter an amount that will start bytes paging when the number of bytes on the JMS server exceeds this threshold.
- In the Bytes Threshold Low field, enter an amount that will stop bytes paging once the number of bytes on the JMS server falls below this threshold.

5. On the Thresholds & Quotas tab, configure messages paging:

- Select the Messages Paging Enabled check box.
- In the Messages Threshold High field, enter an amount that will start messages paging when the number of messages on the JMS server exceeds this threshold.
- In the Messages Threshold Low field, enter an amount that will stop messages paging once the number of messages on the JMS server falls below this threshold.

6. Click Apply to save the new bytes and/or messages paging values.
7. Repeat steps 2-6 to configure paging for additional JMS servers in the domain.

Note: Each JMS server must have its own paging store.

8. After you configure your JMS server (or servers) for paging, do one of the following:

- If you are not configuring the JMS server's destinations for paging, reboot WebLogic Server to activate paging.
- If you are configuring the JMS server's destinations for paging, follow refer to either Configuring Message Paging on a JMS Template or Configuring Message Paging on Destinations.

### Configuring Message Paging on a JMS Template

JMS templates provide an efficient way to define multiple destinations (topics or queues) with similar attribute settings. To configure paging on a template for destinations, do the following:

1. Click the JMS node in the left pane.
2. Click the JMS Templates node. The right pane shows all the templates defined in the domain.
3. Click the template that you want to configure for paging. The right pane shows the tabs associated with configuring the template.
4. On the Thresholds & Quotas tab, configure bytes paging:

- Select the Bytes Paging Enabled check box.
- In the Bytes Threshold High field, enter an amount that will start bytes paging when the number of bytes on the JMS server exceeds this threshold.
- In the Bytes Threshold Low field, enter an amount that will stop bytes paging once the number of bytes on the JMS server falls below this threshold.

5. On the Thresholds & Quotas tab, configure messages paging:

- Select the Messages Paging Enabled check box.
- In the Messages Threshold High field, enter an amount that will start messages paging when the number of messages on the JMS server exceeds this threshold.
- In the Messages Threshold Low field, enter an amount that will stop messages paging once the number of messages on the JMS server falls below this threshold.

6. Click Apply to save the new bytes and/or messages paging values.
7. Repeat steps 3-6 to configure paging for additional JMS templates.
8. After configuring all of your JMS templates for paging, reboot WebLogic Server to activate paging.

### Configuring Message Paging on Destinations

Follow these directions if you are configuring paging on destinations without using a JMS template.

1. Under JMS Servers, expand a server instance that is already configured for paging.
2. Click the Destinations node. The right pane shows all of the server's topics and queues.
3. Click the topic or queue that you want to configure for paging. The right pane shows the tabs associated with configuring the topic or queue.
4. On the Thresholds & Quotas tab, configure bytes paging:

- Select the Bytes Paging Enabled check box.
- In the Bytes Threshold High field, enter an amount that will start bytes paging when the number of bytes on the JMS server exceeds this threshold.
- In the Bytes Threshold Low field, enter an amount that will stop bytes paging once the number of bytes on the JMS server falls below this threshold.

5. On the Thresholds & Quotas tab, configure messages paging:

- Select the Messages Paging Enabled check box.
- In the Messages Threshold High field, enter an amount that will start messages paging when the number of messages on the JMS server exceeds this threshold.
- In the Messages Threshold Low field, enter an amount that will stop messages paging once the number of messages on the JMS server falls below this threshold.

6. Click Apply to save the new bytes and/or messages paging values.
7. Repeat steps 3-6 to configure paging for additional JMS destinations.
8. After you configure all your destinations for paging, reboot WebLogic Server to activate paging.

Note: If you use JMS templates to configure your destinations, a destination's explicit Byte/Messages Paging configuration overrides the template's configuration. For more information, refer to Configuring a Destination to Override Message Paging on a JMS Template and to JMS Template Tasks.

### Configuring a Destination to Override Message Paging on a JMS Template

Follow these directions if you want to override a template's settings and enable or disable paging on a specific destination.

1. Under JMS Servers, expand a server instance that is already configured for paging.
2. Click the Destinations node. The right pane shows all of the server's topics and queues.
3. Click the topic or queue that you want to configure for paging. The right pane shows the topics or queues associated with the server instance.
4. On the Thresholds & Quotas tab, configure the Bytes Paging Enabled and/or Messages Paging Enabled attributes on the destination according to how you want to override the JMS template for the destination.

- To disable paging for the destination, select False in the Bytes Paging Enabled and/or the Messages Paging Enabled list boxes.
- To enable paging for the destination, select True in the Bytes Paging Enabled and/or the Messages Paging Enabled list boxes.

5. Click Apply to save the new bytes and/or messages paging values.
6. Repeat steps 2-5 to configure paging for additional JMS destinations on the same server instance.
7. Once all of your destinations are configured for paging, then reboot WebLogic Server to activate paging.

## JMS Message Paging Attributes

The following sections briefly describe the message paging attributes available with WebLogic Server JMS.

### JMS Server Message Paging Attributes

Table 52-3 describes the message paging attributes that you define when configuring paging on a JMS Server. For detailed information about other JMS Server attributes, and the valid and default values for them, see JMS Template Tasks.

Table 52-3 JMS Server Attributes

Attribute | Description
--- | ---
Bytes Paging Enabled | If the Bytes Paging Enabled check box is not selected (False), then server bytes paging is explicitly disabled. If the Bytes Paging Enabled check box is selected (True), a paging store has been configured, and both the Bytes Threshold Low and Bytes Threshold High attributes are greater than -1, then server bytes paging is enabled. If either the Bytes Threshold Low or Bytes Threshold High attribute is undefined, or defined as -1, then server bytes paging is implicitly disabled—even though the Bytes Paging Enabled check box is selected (True).
Messages Paging Enabled | If the Messages Paging Enabled check box is not selected (False), then server messages paging is explicitly disabled. If the Messages Paging Enabled check box is selected (True), a paging store has been configured, and both the Messages Threshold Low and Messages Threshold High attributes are greater than -1, then server messages paging is enabled. If either the Messages Threshold Low or Messages Threshold High attribute is undefined, or defined as -1, then server paging is implicitly disabled—even though the Messages Paging Enabled check box is selected (True).
Paging Store | The name of the persistent store where non-persistent messages are paged. A paging store cannot be the same store used for persistent messages or durable subscribers. Two JMS servers cannot use the same paging store; therefore, you must configure a unique paging store for each server.

### JMS Template Message Paging Attributes

Table 52-4 describes the message paging attributes that you define when configuring paging on JMS templates for destinations. For detailed information about other JMS template attributes, and the valid and default values for them, see JMS Template Tasks.

Table 52-4 JMS Template Attributes

Attribute | Description
--- | ---
Bytes Paging Enabled | If the Bytes Paging Enabled check box is not selected (False), then destination-level bytes paging is disabled for the JMS template's destinations—unless the destination setting overrides the template. If the Bytes Paging Enabled check box is selected (True), a paging store has been configured for the JMS Server, and both the Bytes Threshold Low and Bytes Threshold High attributes are greater than -1, then destination-level bytes paging is enabled for the JMS template's destinations—unless the destination setting overrides the template. If no value is defined in the JMS Template MBean, then the value defaults to False and bytes paging is disabled for the JMS template's destinations.
Messages Paging Enabled | If the Messages Paging Enabled check box is not selected (False), then destination-level messages paging is disabled for the template's destination—unless the destination setting overrides the template. If the Messages Paging Enabled check box is selected (True), a paging store has been configured for the JMS Server, and both the Messages Threshold Low and Messages Threshold High attributes are greater than -1, then destination-level messages paging is enabled for this destination—unless the destination setting overrides the template. If no value is defined in the JMS Template MBean, then the value defaults to False and messages paging is disabled for the template's destinations.

### JMS Destination Message Paging Attributes

Table 52-5 describes the attributes that you define when configuring message paging on destinations. For detailed information about other JMS destination attributes, and valid and default values for them, see JMS Queue and Topic Destination Tasks.

Table 52-5 JMS Destination Attributes

Attribute | Description
--- | ---
Bytes Paging Enabled | If Bytes Paging Enabled is set to False, then destination-level bytes paging is disabled for this destination. If Bytes Paging Enabled is set to True, a paging store has been configured for the JMS Server, and both the Bytes Threshold Low and Bytes Threshold High attributes are greater than -1, then destination-level bytes paging is enabled for this destination. If Bytes Paging Enabled is set to Default, then this value inherits the template's value—if a template is specified. If no template is configured for the destination, then the Default value is equivalent to False.
Messages Paging Enabled | If Messages Paging Enabled is set to False, then destination-level messages paging is disabled for this destination. If Messages Paging Enabled is set to True, a paging store has been configured for the JMS Server, and both the Messages Threshold Low and Messages Threshold High attributes are greater than -1, then destination-level messages paging is enabled for this destination. If Messages Paging Enabled is set to Default, then this value inherits the template's value—if a template is specified. If no template is configured for the destination, then the Default value is equivalent to False.

Note: If server paging is enabled, and destination-level paging is disabled for a given destination, than messages on the destination can still be paged if server paging is triggered. However, when destination-level paging is disabled for a given destination, then the destination's high thresholds will not force the destination to page out messages when they are exceeded.

### Message Paging Threshold Attributes

Table 52-6 briefly describes the bytes and messages paging thresholds available with JMS servers, templates, and destinations. For detailed information about other JMS server, template, and destination attributes, and the valid and default values for them, see JMS Server Tasks, JMS Queue and Topic Destination Tasks, and JMS Template Tasks.

Table 52-6 Paging Threshold Attributes

Attribute | Description
--- | ---
Bytes Threshold High | Start paging when the number of bytes exceeds this threshold.
Bytes Threshold Low | Stop paging when the number of bytes falls back below this threshold.
Messages Threshold High | Start paging when the number of messages exceeds this threshold.
Messages Threshold Low | Stop paging when the number of messages falls back below this threshold.

The thresholds are defined for servers, templates, and destinations as follows:

- If either bytes high/low threshold value is not defined (or is defined as -1), then the number of bytes is not used to determine when and what to page.
- If either messages high/low threshold value is not defined (or is defined as -1), then the number of messages is not used to determine when and what to page.
- A server or template/destination must have the Bytes/Messages Paging Enabled attribute set to True in order for paging to take place. If the thresholds are set, but paging is not enabled, messages are still logged on the server indicating threshold conditions.

## Related Topics

For more information on tuning Weblogic JMS performance, refer to the following help topics:

- Controlling the Flow of Messages on JMS Servers and Destinations
- Avoiding Quota Exceptions by Blocking Message Producers
- Handling Expired Messages

# 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
- Configuring Flow Control
- Flow Control Thresholds
- Avoiding Quota Exceptions by Blocking Message Producers

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

To configure message flow control on a connection factory, follow these steps:

1. Under the Services —> JMS node in the navigation tree, click the Connection Factory node. The right pane shows the connection factories defined in the domain
2. Select the connection factory instance for which you will configure message flow control. The right pane shows the tabs associated with configuring the connection factory.
3. Select the Configuration —> Flow Control tab.
4. Define the Flow Control attributes as described in following table:

Table 52-7 Flow Control Attributes

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.

5. Click Apply to store new attribute values.

For detailed information about other connection factory attributes, and the valid and default values for them, see JMS Connection Factory Tasks.

## Flow Control Thresholds

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

Table 52-8 Flow Control Threshold Attributes

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 JMS destination attributes, and the valid and default values for them, see JMS Server Tasks and JMS Queue and Topic Destination Tasks.

# Avoiding Quota Exceptions by Blocking Message Producers

The following sections describe two additional "Flow Control" features that can help you to avoid receiving message quota errors by temporarily blocking message producers from sending messages to a destination (queue or topic) when it has exceeded its specified maximum message quota.

- A Send Timeout value can be set for a JMS connection factory to provide message producers the option of waiting a specified length of time (in milliseconds) until space becomes available on a destination that has exceeded its message quota.
- The Blocking Send Policy enables you to define a JMS server's blocking behavior when multiple producers are competing for space on a destination that has exceeded its message quota.

For instructions on configuring the Blocking Send Policy and Send Timeout features:

- Defining a Send Timeout on a JMS Connection Factory.
- Specifying a Blocking Send Policy on a JMS Server.

## Defining a Send Timeout on a JMS Connection Factory

The Send Timeout feature provides more control over message send operations by giving produces the option of waiting a user-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.

Follow these directions to define how long a JMS connection factory will block message requests when a destination exceeds its maximum quota.

1. Under the Services —> JMS node in the navigation tree, click the Connection Factory node. The right pane shows the connection factories defined in the domain.
2. Select the connection factory instance for which you will configure a send timeout. The right pane shows the tabs associated with configuring the connection factory.
3. Select the Configuration —> Flow Control tab.
4. 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 attribute, see JMS Connection Factory --> Configuration --> Flow Control.

5. Click Apply to save the new value.

## Specifying a Blocking Send Policy on a JMS Server

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.

Follow these directions to define how a JMS server will block message requests when its destinations are at maximum quota.

1. Under the Services —> JMS node in the navigation tree, click the Servers node. The right pane shows the JMS servers defined in the domain.
2. Select the server instance for which you will configure a blocking send policy. The right pane shows the tabs associated with configuring the server.
3. Select the Configuration —> Thresholds & Quota tab.
4. 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 attribute, see JMS Server --> Configuration --> Thresholds & Quotas.

5. Click Apply to save the new value.

## Related Topics

For more information on tuning Weblogic JMS performance, refer to the following help topics:

- Controlling the Flow of Messages on JMS Servers and Destinations
- Paging Out Messages To Free Up Memory
- Handling Expired Messages

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

In previous releases, WebLogic JMS implemented a passive message expiration policy. Messages expired as they were discovered and were then simply discarded from the system. Since no active searches were made for expired messages, they could accumulate on the system and strain system resources. Active message expiration addresses this issue by ensuring 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 special destination.

- Defining a Message Expiration Policy
- Enabling Active Message Expiration

## 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 attribute on the Templates node 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 a Topic
- Configuring an Expiration Policy On a Queue
- Configuring an Expiration Policy On a JMS Template
- Defining an Expiration Logging Policy

### Configuring an Expiration Policy On a Topic

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.

1. Under Services —> JMS —> Servers in the navigation tree, expand the server instance that you want to configure.
2. Click the Destinations node. The right pane shows all of the server's topics and queues.
3. Select the topic for which you will configure an expiration policy. The right pane shows the tabs associated with configuring the topic.
4. Click the Configuration —> Expiration Policy tab.
5. From the Expiration Policy list box, select an expiration policy option.

- none and Discard — If this topic has no JMS template, then "none" is equivalent to Discard. Discard means that 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 Step 6.
- 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 --> Expiration Policy.

6. If you selected the Log expiration policy in Step 5, 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.

7. Click Apply to save the new expiration policy values.
8. Repeat steps 3-7 to configure an expiration policy for additional topics.

### Configuring an Expiration Policy On a Queue

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.

1. Under Services —> JMS —> Servers in the navigation tree, expand the server instance that you want to configure.
2. Click the Destinations node. The right pane shows all of the server's topics and queues.
3. Select the queue for which you will configure an expiration policy. The right pane shows the tabs associated with configuring the queue.
4. Click the Configuration —> Expiration Policy tab.
5. From the Expiration Policy list box, select an expiration policy option.

- none and Discard — If this queue has no JMS template, then "none" is equivalent to Discard. Discard means that 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 Step 6.
- 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 JMS Queue --> Configuration --> Expiration Policy.

6. If you selected the Log expiration policy in Step 5, 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.

7. Click Apply to save the new expiration policy values.
8. Repeat steps 3-7 to configure an expiration policy for additional queues.

### Configuring an Expiration Policy On a JMS Template

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.

1. Expand the Services —> JMS —> Templates node in the navigation tree. The right pane shows all the JMS templates defined in the domain (if any).
2. Select the template for which you will configure an expiration policy. The right pane shows the tabs associated with configuring the template.
3. Click the Configuration —> Expiration Policy tab.
4. In the Expiration Policy list box, select an expiration policy option.

- none and Discard — Expired messages are removed from the messaging system. The removal is not logged and the message is not redirected to another location. If "none" is defined for a given destination, then expired messages are discarded.
- 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 Step 5.
- Redirect — Moves expired messages from their current location into the Error Destination defined for the destination.

For more information about the Expiration Policy options, see JMS Template --> Configuration --> Expiration Policy.

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

6. Click Apply to save the new expiration policy values.
7. Repeat steps 2-6 to configure an expiration policy for additional JMS templates.

### Defining an Expiration Logging Policy

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.

1. Under the Services —> JMS node in the navigation tree, click the Servers node. The right pane shows the JMS servers defined in the domain.
2. Select the server instance for which you will configure an active expiration scan interval. The right pane shows the tabs associated with configuring the server.
3. Using the Scan Expiration Interval field on the Configuration —> General tab, 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 Configuring a JMS Server to Actively Scan Destinations for Expired Messages.

4. Click Apply to save the new value.

## Related Topics

For more information on tuning Weblogic JMS performance, refer to the following topics:

- Paging Out Messages To Free Up Memory
- Controlling the Flow of Messages on JMS Servers and Destinations
- Avoiding Quota Exceptions by Blocking Message Producers