JMS: Configuring

JMS: Configuring

[Attributes and Console Screen Reference for JMS]
The following sections explain how to configure the Java Message Service for WebLogic Server:

JMS and WebLogic Server
JMS Server Tasks
JMS Connection Factory Tasks
JMS Queue and Topic Destination Tasks
JMS Distributed Destination Tasks
JMS Template Tasks
Destination Keys Tasks
JMS Store Tasks
Session Pools Tasks
Connection Consumers Tasks
Simple Access to Remote or Foreign JMS Providers

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

JMS: Tuning
JMS: Monitoring
Messaging Bridge

JMS and WebLogic Server

JMS (Java Message Service) is a standard API for accessing enterprise messaging systems. Specifically, WebLogic JMS:

Enables Java applications sharing a messaging system to exchange messages.
Simplifies application development by providing a standard interface for creating, sending, and receiving messages.

The following figure illustrates WebLogic JMS messaging.
Figure 48-1 WebLogic Server JMS Messaging

As illustrated in the figure, WebLogic JMS accepts messages from producer applications and delivers them to consumer applications.

Configuring WebLogic JMS

Using the Administration Console, you define configuration attributes to:

Create JMS servers and target a WebLogic Server instance or a Migratable Target where the JMS server will be deployed, as describe in JMS Server Tasks.
Create and/or customize values for JMS servers, connection factories, destinations (queues and topics), JMS templates, destination sort order (using destination keys), persistent stores (file or JDBC), paging stores, session pools, and connection consumers.
Define message and/or bytes thresholds and quotas, as well as a maximum allowable message size on your JMS servers, destinations, and templates, as discussed in JMS Server Tasks, JMS Queue and Topic Destination Tasks, and JMS Template Tasks.
Enable any desired WebLogic JMS features, such as:
Server clustering using multiple connection factories, as described in "Managing JMS in Programming WebLogic JMS.
High availability and load balancing for destinations across a cluster by using distributed destinations, as described in JMS Distributed Destination Tasks.
Persistent messages and durable subscribers, as described in "Developing a WebLogic JMS Application in Programming WebLogic JMS.
Paging out message bodies during peak load periods to free up memory, as described in Paging Out Messages To Free Up Memory.
Controlling message flow during peak load periods, including blocking message producers, as described in Controlling the Flow of Messages on JMS Servers and Destinations.
Establishing a message expiration policy to ensure that expired messages are cleaned up immediately, as described in Handling Expired Messages.
Preventing message quota errors by temporarily blocking message producers from sending messages to a destination when it exceeds its specified maximum message quota, as described in Avoiding Quota Exceptions by Blocking Message Producers.
Concurrent message processing via session pools, as described in Session Pools Tasks.

Messaging bridge for transferring messages (includes transactional messages) between any two JMS providers - including separate implementations of WebLogic JMS, as described in Messaging Bridge.

WebLogic JMS provides default values for some configuration attributes; provide values for all others. If you specify an invalid value for any configuration attribute, or if you fail to specify a value for an attribute for which a default does not exist, WebLogic Server will not boot JMS when you restart it.
A sample examplesJMSServer configuration is provided with the product in the Examples Server. For more information about starting the Examples Server, see "Starting the Default, Examples, and Pet Store Servers in the Installation Guide. There are also instructions for manually configuring a basic JMS implementation in the "Starting WebLogic Server and Configuring JMS section of Programming WebLogic JMS.
When you port WebLogic JMS applications from a previous release of Weblogic Server, the configuration information is automatically converted, as described in "Porting WebLogic JMS Applications in Programming WebLogic JMS.
Once WebLogic JMS is configured, applications can send and receive messages using the JMS API. For more information about developing WebLogic JMS applications, refer to "Developing a WebLogic JMS Application in Programming WebLogic JMS.
Note: To assist with your WebLogic JMS configuration planning, Programming WebLogic JMS provides configuration checklists for the attribute requirements and/or options that support various JMS features.

JMS Configuration Naming Rules

Each server within a domain must have a name that is unique for all configuration objects in the domain. Within a domain, each server, machine, cluster, virtual host, and any other resource type must be named uniquely and must not use the same name as the domain. This unique naming rule also applies to all configurable JMS objects, such as JMS servers, stores, templates, connection factories, session pools, and connection consumers.
The one exception to this unique naming rule, however, is for JMS queue and topic destinations on different JMS servers in a domain, as follows:

Queue destinations can use the same name as other queues on different JMS servers; topic destinations can also use the same name as other topics on different JMS servers.
Queue destinations cannot use the same name with topic destinations, nor can queues nor topics use the same name as any other configurable objects.

JMS Server Tasks

A JMS server manages connections and message requests on behalf of clients. Use the Services - > JMS - > Server node to configure a JMS server and assign it to either an independent WebLogic Server instance or a migratable server target where it will be deployed.

Configuring a JMS Server

You must first configure a JMS server before you can configure any destinations or consumers.

Expand the JMS - > Servers node. The JMS Servers table displays in the right pane showing all the JMS servers defined in your domain.
Click the Configure a new JMS Server text link. A dialog displays in the right pane showing the tabs associated with configuring a new JMS server.
On the Configuration General tab, define the general configuration attributes for a JMS server:
Enter a name for the JMS server. This name must be unique within the WebLogic Server instance or its cluster. For more information, see JMS Configuration Naming Rules.
Select an existing persistent store (disk-based file or JDBC-accessible database) for storing persistent messages. To select a store, first configure a JMS file store or a JDBC store using the JMS - > Stores node. If you do not assign a persistent store for a JMS server, persistent messaging is not supported on that server.
Select a paging store where message bodies can be temporarily swapped out from memory when the JMS server's message load reaches a specified threshold. To select a paging store, first configure a JMS file store using the JMS - > Stores node. A paging store cannot be the same JMS file store used for storing persistent messages or durable subscribers. If you do not assign a paging store for a JMS server, paging is not supported on that server.
Select an existing JMS template that is used to create all temporary destinations (temporary queues or topics).
Specify an Expiration Scan Interval to define how long the JMS server will pause between its cycles of scanning local destinations for expired messages to be processed.

For more information about JMS server general attributes, see JMS Server --> Configuration --> General.
Click Create to create a JMS server instance with the name you specified in the Name field. The new instance is added under the JMS Servers node in the left pane. A Destinations node and a Session Pools node are automatically added under the new server instance by default.
On the Configuration Thresholds & Quotas tab, define the following upper and lower message/byte threshold and maximum quota attributes for a JMS server:
Specify the maximum bytes or message quota that can be stored in a JMS server.
Specify the upper threshold value that trigger events based on the number of bytes or messages stored in a JMS server. Events include message paging, message flow control, and system log messages.
Specify the lower threshold value that trigger events based on the number of bytes or messages stored in a JMS server. Events include message paging, message flow control, and system log messages.
Indicate whether bytes or messages paging is enabled on a JMS server for temporarily swapping messages out from memory to a paging store when a JMS server's message load reaches a specified bytes/messages threshold.
Specify the maximum size of a message that will be accepted from message producers on a JMS server. The size includes the message body, any user-defined properties, and the user-defined JMS header fields: JMSCorrelationID and JMSType.
Select the server's policy on whether to deliver smaller messages before larger ones when a destination has exceeded its message quota.

For more information about the Thresholds & Quota attributes, see JMS Server --> Configuration --> Thresholds & Quotas.
Click Apply to save your changes.
On the Target and Deploy tab, select an independent WebLogic Server or a migratable server target on which to deploy the JMS server.
For more information see, Targeting and Deploying a JMS Server.
Click Apply to target the JMS server.

Targeting and Deploying a JMS Server

You can assign a JMS server to either an independent WebLogic Server instance or to a migratable target server where it will be deployed. Whereas, a connection factory or template can be instantiated on multiple WebLogic Server instances simultaneously

Under the JMS - > Servers node in the left pane, click the node for the JMS server instance that you want to assign. A dialog displays in the right pane showing the tabs associated with this instance.
Click the Target and Deploy tab.
Complete one of the following steps for targeting either an independent server or a migratable target server:
From the Target list box, select the server target where you want to deploy the JMS server. When a target WebLogic Server boots, the JMS server boots as well. If no target WebLogic Server is specified, the JMS server will not boot. The deployment of a JMS server differs from that of a connection factory or template.
From the Migratable Target list box, select the migratable target where you want to deploy the JMS server. Migratable targets define a set of WebLogic Server instances in a cluster that can potentially host an exactly-once service, such as JMS. When a migratable target server boots, the JMS server boots as well on the user-preferred server in the cluster. However, a JMS server and all of its destinations can migrate to another server within the cluster in response to a server failure or due to a scheduled migration for system maintenance.
For more information on configuring a migratable target for JMS, see "Managing JMS in Programming WebLogic JMS.

Click Apply to save your assignments.

Monitoring a JMS Server

On the JMS Monitoring tab, you can monitor statistics for view run-time information for active JMS servers, destinations, and server session pools.

Expand the JMS node.
Click the Servers node. The JMS Servers information displays in the right pane showing all the JMS servers defined in your domain.
Click the JMS server that you want to monitor from the JMS server list, or from the JMS Servers table displayed in the right pane.
Click the Monitoring tab to display the monitoring links for monitoring JMS server data:
Monitor all Active JMS Servers - A table displays showing all instances of the JMS server deployed across the WebLogic Server domain.
Monitor all Active JMS Destinations - A table displays showing all active JMS destinations for the current domain.
Monitor all Active JMS Session Pool Runtimes - A table displays showing all active JMS session pools for the current domain.

For more information about monitoring JMS objects, see JMS: Monitoring.

JMS Connection Factory Tasks

Connection factories are objects that enable JMS clients to create JMS connections. A connection factory supports concurrent use, enabling multiple threads to access the object simultaneously. WebLogic JMS provides preconfigured "default connection factories" that can be enabled or disabled on a per-server basis, as described in Using a Default Connection Factory. Otherwise, you can configure one or more connection factories to create connections with predefined attributes that better suit your application - as long as each connection factory is uniquely named. WebLogic Server adds them to the JNDI space during startup, and the application then retrieves a connection factory using WebLogic JNDI.
You can establish cluster-wide, transparent access to JMS destinations from any server in the cluster, either by using the default connection factories for each server instance, or by configuring one or more connection factories and targeting them to one or more server instances in the cluster. This way, each connection factory can be deployed on multiple WebLogic Servers. For more information on configuring JMS clustering, see "Managing JMS in Programming WebLogic JMS.

Using a Default Connection Factory

WebLogic JMS defines two default connection factories, which can be looked up using the following JNDI names:

weblogic.jms.ConnectionFactory
weblogic.jms.XAConnectionFactory

You only need to configure a new connection factory if the pre-configured settings of the default factories are not suitable for your application. The main difference between the pre-configured settings for the default connection factories and a user-defined connection factory is the default value for the "XA Connection Factory Enabled" attribute to enable JTA transactions, as shown in the following table:

Default Connection Factory. . .

XAConnectionFactoryEnabled setting is. . .
weblogic.jms.ConnectionFactory False
weblogic.jms.XAConnectionFactory True

An XA factory is required for JMS applications to use JTA user-transactions, but is not required for transacted sessions. For more information about using transactions with WebLogic JMS, see "Using Transactions with WebLogic JMS in Programming WebLogic JMS.
All other default factory configuration attributes are set to the same default values as a user-defined factory. For more information about the XA Connection Factory Enabled attribute, and to see the default values for the other connection factory attributes, see Attributes and Console Screen Reference for JMS.
Another distinction when using the default connection factories is that you have no control over targeting the WebLogic Server instances where the connection factory may be deployed. However, you can enable and/or disable the default connection factories on a per-WebLogic Server basis.

For more information on enabling or disabling the default connection factories, see Server --> Services --> JMS.
For information on deploying a user-defined connection factory on independent server instances, on specific servers within a cluster, or on an entire cluster, see Deploying a Connection Factory on Multiple Individual Servers and Deploying a Connection Factory on a Cluster.

Note: Some connection factory attributes are dynamically configurable. When dynamic attributes are modified at run time, the new values become effective for new connections only, and do not affect the behavior of existing connections.

Configuring a JMS Connection Factory

Using the Services - > JMS - > Connection Factories node, you can configure one or more connection factories to create connections with predefined attributes.

Expand the JMS - > Connection Factories node. The JMS Connection Factories table displays in the right pane showing all the connection factories defined in your domain.
Click the Configure a new JMS Connection Factory text link. A dialog displays in the right pane showing the tabs associated with configuring a new connection factory.
On the Configuration General tab, define the general configuration attributes for the connection factory.
Enter a name for the connection factory. This name must be unique within the WebLogic Server instance or its cluster. For more information, see JMS Configuration Naming Rules.
Enter a JNDI name for accessing the connection factory within the JNDI namespace.
Specify a client identifier (client ID) for clients with durable subscribers. For more information about durable subscribers, see "Developing a WebLogic JMS Application in Programming WebLogic JMS.
Define the default message delivery attributes: Priority, Time To Live, Time To Deliver, and the Delivery Mode (Persistent or Non-Persistent).
Specify the maximum number of outstanding messages that may exist for an asynchronous session and the overrun policy (that is, the action to be taken, for multicast sessions, when this maximum is reached).
Indicate whether the close() method is allowed to be called from the onMessage() method.
Choose whether all messages are acknowledged or only previously received messages are acknowledged.
For distributed destinations, determine whether non-anonymous producers created through a connection factory are load balanced on a per-call basis and whether server affinity is used when load balancing consumers or producers in a distributed destination.

For more information about general connection factory attributes, see JMS Connection Factory --> Configuration --> General.
Click Create to create a connection factory instance with the name you specified in the Name field. The new instance is added under the JMS Connection Factories node in the left pane.
On the Configuration Transactions tab, define a value for the transaction time-out attribute and use the XAConnectionFactoryEnabled field to indicate whether a transaction queue or topic connection factory is returned and whether the connection factory creates sessions that are JTA aware.
For more information about connection factory transaction attributes, see JMS Connection Factory --> Configuration --> Transactions.
Click Apply to save your changes.
On the Configuration Flow Control tab, define values that instruct a message 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. Use the Send Timeout attribute to specify the maximum time that a producers will wait for sufficient quota on a JMS server and destination to accommodate the message that it is attempting to send.
For more information about connection factory flow control attributes, see JMS Connection Factory --> Configuration --> Flow Control.
Click Apply to save your changes.
On the Target and Deploy tab, assign the connection factory to a WebLogic Server instance or to a server cluster. Targets enable you to limit the set of servers, groups, and/or clusters on which a connection factory may be deployed.
For more information see, Deploying a Connection Factory on Multiple Individual Servers and Deploying a Connection Factory on a Cluster.
Click Apply to save your changes.

Deploying a Connection Factory on Multiple Individual Servers

You can establish cluster-wide, transparent access to JMS destinations from any server in a domain by deploying one or more connection factories on multiple WebLogic Server instances simultaneously.

Expand the JMS - > Connection Factories node, and then select the connection factory that you want to deploy. A dialog displays in the right pane showing the tabs associated with this instance.
Click the Target and Deploy tab. All the server instances in the domain are listed in the Independent Servers box. A check mark is displayed next to each server already targeted to the connection factory.
To deploy the connection factory on one or more servers in the list, select the check mark displayed next to each server name.
Connection Factories can also be undeployed from individual servers whenever necessary by clearing the check mark displayed next to each server name.
Click Apply to save your assignments.

Deploying a Connection Factory on a Cluster

In a clustered environment, you can establish cluster-wide, transparent access to JMS destinations from any server in a cluster by deploying a connection factory on all server instances in the cluster, or even to specific servers within the cluster.

Expand the JMS - > Connection Factories node, and then select the connection factory that you want to deploy. A dialog displays in the right pane showing the tabs associated with this instance.
Click the Target and Deploy tab. All the clusters configured in the domain are listed in the Clusters box. A check mark is displayed next to each cluster name already targeted to the connection factory.
The Connection factory can be targeted to either all the servers in a cluster or to selected servers within a cluster:
To deploy the connection factory on all the servers in a cluster, click the "All servers in the cluster" button under the cluster name.
To deploy the connection factory on only selected servers within a cluster, click the "Some servers in the cluster" button under the cluster name. Then target one or more servers in the cluster by selecting the check mark displayed next to each server name.

Connection Factories can also be undeployed from an entire cluster or from selected servers within a cluster whenever necessary, by doing the following:
To undeploy a connection factory from all the servers in a cluster, clear the check box next to the cluster name.
To undeploy a connection factory from only selected servers in a cluster, click the "Some servers in the cluster" button under the cluster name. Then undeploy one or more servers in the cluster by clearing the check mark displayed next to each server name.

Click Apply to save your assignments.

JMS Queue and Topic Destination Tasks

A JMS destination identifies a queue (point-to-point) or topic (publish/subscribe) for a JMS server. After configuring a JMS server, configure one or more queue or topic destinations for each JMS server.
You configure destinations explicitly or by configuring a destination template that can be used to define multiple destinations with similar attribute settings, as described in JMS Template Tasks.
You can configure multiple physical destinations as members of a single distributed destination set within a cluster. Therefore, if one WebLogic Server instance within the cluster fails, then the other instances hosting the same distributed destination will continue to provide service to JMS producers and consumers. For more information, see JMS Distributed Destination Tasks.
Note: To help manage recovered or rolled back messages, you can also configure a target error destination for messages that have reached their redelivery limit. The error destination must be a destination that is configured on the local JMS server. For more information, see "Configuring an Error Destination for Undelivered Messages in Programming WebLogic JMS.
Some destination attributes are dynamically configurable. When attributes are modified at run time, only incoming messages are affected; stored messages are not affected.

Creating a JMS Queue

A JMS queue defines a point-to-point destination type for a JMS server. After defining a JMS server, configure one or more queue destinations for each JMS server.

Expand the JMS - > Servers node and select a JMS server instance.
Click the Destinations node. The JMS Destinations table displays in the right pane showing all the JMS queues.
Click the Configure a new JMS Queue text link. A dialog shows the tabs associated with configuring a new queue.
On the Configuration General tab, define the general configuration attributes for the queue.
Enter a name for the queue destination. This name must be unique within the WebLogic Server instance or its cluster. For more information, see JMS Configuration Naming Rules.
Enter a JNDI name for accessing the queue within the JNDI namespace.
Indicate whether the JNDI name for the queue (if specified) is replicated across the cluster.
Specify whether the queue supports persistent messaging by using the JMS store specified for the JMS server.
Select an existing JMS template if you are using one to create queues.
Select existing destination keys that will define the sort order for messages arriving on the queue.

For more information about the queue general attributes, see JMS Queue --> Configuration --> General.
Click Create to create a queue instance with the name you specified in the Name field. The new instance is added under the Destinations node in the left pane.
On the Configuration Thresholds & Quotas tab, define the following upper and lower message/byte threshold and maximum quota attributes for the queue:
Specify the maximum bytes or message quota that can be stored in a queue.
Specify the upper threshold value that trigger events based on the number of bytes or messages stored in a queue. Events include message paging, message flow control, and system log messages.
Specify the lower threshold value that trigger events based on the number of bytes or messages stored in a queue. Events include message paging, message flow control, and system log messages.
Indicate whether bytes or messages paging is enabled on a queue for temporarily swapping messages out from memory to a paging store when a queue's message load reaches a specified bytes/messages threshold.
Specify the maximum size of a message that will be accepted from message producers on a queue. The size includes the message body, any user-defined properties, and the user-defined JMS header fields: JMSCorrelationID and JMSType.

For more information about the Thresholds & Quota attributes, see JMS Queue --> Configuration --> Thresholds & Quotas.
On the Configuration Overrides tab, define the message attributes that can override those specified by a message producer, including the priority, time-to-live, time-to-deliver, and delivery mode.
For more information about the queue override attributes, see JMS Queue --> Configuration --> Overrides.
On the Configuration Redelivery tab, define the message redelivery attributes, including redelivery delay override, redelivery limit, and error destination.
For more information about the queue redelivery attributes, see JMS Queue --> Configuration --> Redelivery.
On the Configuration Expiration Policy tab, define the message expiration policy to use when expired messages are encountered on the queue.
For more information about the queue expiration policy attributes, see JMS Queue --> Configuration --> Expiration Policy.
Click Apply to save any changes you made on these tabs.

Creating a JMS Topic

A JMS topic identifies a publish/subscribe destination type for a JMS server. After defining a JMS server, configure one or more topic destinations for each JMS server.

Expand the JMS - > Servers node and select a JMS server instance.
Click the Destinations node. The JMS Destinations table displays in the right pane showing any configured JMS topics.
Click the Configure a new JMS Topic text link. A dialog shows the tabs associated with configuring a new topic.
On the Configuration General tab, define the general configuration attributes for the topic.
Enter a name for the topic destination. This name must be unique within the WebLogic Server instance or its cluster. For more information, see JMS Configuration Naming Rules.
Enter a JNDI name for accessing the topic within the JNDI namespace.
Indicate whether the JNDI name for the topic (if specified) is replicated across the cluster.
Specify whether the topic supports persistent messaging by using the JMS store specified for the JMS server.
Select an existing JMS template if you are using one to create topics.
Select existing destination keys that will define the sort order for messages arriving on the topic.

For more information about the topic general attributes, see JMS Topic --> Configuration --> General.
Click Create to create a topic instance with the name you specified in the Name field. The new instance is added under the Destinations node in the left pane.
On the Configuration Thresholds & Quotas tab, define the following upper and lower message/byte threshold and maximum quota attributes for the topic:
Specify the maximum bytes or message quota that can be stored in a topic.
Specify the upper threshold value that trigger events based on the number of bytes or messages stored in a topic. Events include message paging, message flow control, and system log messages.
Specify the lower threshold value that trigger events based on the number of bytes or messages stored in a topic. Events include message paging, message flow control, and system log messages.
Indicate whether bytes or messages paging is enabled on a topic for temporarily swapping messages out from memory to a paging store when a topic's message load reaches a specified bytes/messages threshold.
Specify the maximum size of a message that will be accepted from message producers on a topic. The size includes the message body, any user-defined properties, and the user-defined JMS header fields: JMSCorrelationID and JMSType.

For more information about the topic Thresholds & Quota attributes, see JMS Topic --> Configuration --> Thresholds & Quotas.
On the Configuration Overrides tab, define the message attributes that can override those specified by a message producer, including the priority, time-to-live, time-to-deliver, and delivery mode.
For more information about the topic override attributes, see JMS Topic --> Configuration --> Overrides.
On the Configuration Redelivery tab, define the message redelivery attributes, including redelivery delay override, redelivery limit, and error destination.
For more information about the topic redelivery attributes, see JMS Topic --> Configuration --> Redelivery.
On the Configuration Expiration Policy tab, define the message expiration policy logging properties to use when expired messages are encountered on the topic.
For more information about the topic expiration policy attributes, see JMS Topic --> Configuration --> Expiration Policy.

On the Configuration Mulitcast tab, define the mulitcast attributes for the topic, including a multicast address, time-to-live (TTL), and port.
For more information about the topic expiration policy attributes, see JMS Topic --> Configuration --> Multicast.
Click Apply to save any changes you made on these tabs.

JMS Template Tasks

A JMS template provides an efficient means of defining multiple destinations with similar attribute settings. JMS templates offer the following benefits:

You do not need to re-enter every attribute setting each time you define a new destination; you can use the JMS template and override any setting to which you want to assign a new value.
You can modify shared attribute settings dynamically simply by modifying the template.

The configurable attributes for a JMS template are the same as those configured for a destination. These configuration attributes are inherited by the destinations that use them, with the following exceptions:

If the destination that is using a JMS template specifies an override value for an attribute, the override value is used.
If the destination that is using a JMS template specifies a message redelivery value for an attribute, that redelivery value is used.
The Name attribute is not inherited by the destination. This name is valid for the JMS template only. You must explicitly define a unique name for all destinations. For more information, see JMS Configuration Naming Rules.
The JNDI Name, Enable Store, and Template attributes are not defined for JMS templates.
The Multicast attributes are not defined for JMS templates because they apply only to topic destinations.

Any attributes that are not explicitly defined for a destination are assigned default values. If no default value exists, be sure to specify a value within the JMS template or as a destination attribute override. If you do not do so, the configuration information remains incomplete, the WebLogic JMS configuration fails, and the WebLogic JMS does not boot.

Creating a JMS Template

To define the JMS template configuration attributes for destinations, use the JMS - > Templates node.

Expand the JMS - > Templates node. The JMS Templates table displays in the right pane showing all the templates defined in the domain.
Click the Configure a new JMS Template text link. A dialog displays in the right pane showing the tabs associated with configuring a new template.
On the Configuration General tab, define the general configuration attributes for the JMS template.
Name of the JMS template. This name must be unique within the WebLogic Server instance or its cluster. For more information, see JMS Configuration Naming Rules.
Destination keys used to define the sort order for messages arriving on destinations created from this JMS template.

For more information about the topic general attributes, see JMS Template --> Configuration --> General.
Click Create to create a template instance with the name you specified in the Name field. The new instance is added under the Templates node in the left pane.
On the Configuration Thresholds & Quotas tab, define the following upper and lower message/byte threshold and maximum quota attributes for the destinations created from this JMS template:
Specify the maximum bytes or message quota that can be stored in a destination.
Specify the upper threshold value that trigger events based on the number of bytes or messages stored in a destination. Events include message paging, message flow control, and system log messages.
Specify the lower threshold value that trigger events based on the number of bytes or messages stored in a destination. Events include message paging, message flow control, and system log messages.
Indicate whether bytes or messages paging is enabled on a destination for temporarily swapping messages out from memory to a paging store when a destination's message load reaches a specified bytes/messages threshold.
Specify the maximum size of a message that will be accepted from message producers on a destination. The size includes the message body, any user-defined properties, and the user-defined JMS header fields: JMSCorrelationID and JMSType.

For more information about the JMS template Thresholds & Quota attributes, see JMS Template --> Configuration --> Thresholds & Quotas.
On the Configuration Override tab, define the message attributes that can override those specified by a message producer for destinations created from this JMS template, including the priority, time-to-live, time-to-deliver, and delivery mode.
For more information about the JMS template override attributes, see JMS Template --> Configuration --> Override.
On the Configuration Redelivery tab, define the message redelivery attributes for destinations created from this JMS template, including redelivery delay override, redelivery limit, and error destination.
For more information about the JMS template redelivery attributes, see JMS Template --> Configuration --> Redelivery.
On the Configuration Expiration Policy tab, define the message expiration policy logging properties to use when expired messages are encountered on destinations created from this JMS template.
For more information about the JMS template expiration policy attributes, see JMS Template --> Configuration --> Expiration Policy.
Click Apply to save any changes you made on these tabs.

Destination Keys Tasks

Use destination keys to define the sort order for messages that arrive on a specific destination.

Creating a JMS Destination Key

To create a destination key, use the Destination Keys node.

Expand the JMS - > Destination Keys node. The JMS Destinations Keys table displays in the right pane showing all the destination keys.
Click the Create a new JMS Destination Key text link. A dialog shows the tabs associated with configuring a new destination key.
On the Configuration General tab, define the general destination key attributes:
Enter a name of the destination key.
Select a message sort key name or the name of a message header field on which to sort. Message header field keys start with the letters JMS and ignore the key type setting. (For better performance, use message header fields as sorting keys, rather than message properties.)
Select the expected property type for the sort key. (This setting is ignored for message header field keys, which have an implied type.)
Select the direction in which the key will sort messages (ascending or descending).

For more information about the JMS destination key attributes, see JMS Destination Key --> Configuration.
Click Create to create a destination key instance with the name you specified in the Name field. The new instance is added under the Destination Keys node in the left pane.

JMS Store Tasks

WebLogic JMS can store persistent messages in either a JDBC-accessible database or a disk-based file.
The following are some similarities and differences between file stores and JDBC stores.

Both have the same transaction semantics and guarantees. As with JDBC store writes, file store writes are guaranteed to be persisted to disk and are not simply left in an intermediate (unsafe) cache.
Both have the same application interface (no difference in application code).
File stores are generally much faster.
File stores are easier to configure.
File stores generate no network traffic; JDBC stores will generate network traffic if the database is on a different machine from the JMS server.
File stores are much better suited to paging non-persistent messages.
JDBC stores may make it easier to handle failure recovery since the JDBC interface can access the database from any machine on the same network; with the file store, the disk must be shared or migrated.
You cannot configure a transaction (XA) connection pool with a JMS JDBC store. For more information, see Handling Transactions with JMS JDBC Stores.

JMS stores can increase the amount of memory required during initialization of a WebLogic Server instance as the number of stored messages increases. If initialization fails due to insufficient memory while rebooting WebLogic Server, increase the heap size of the Java Virtual Machine (JVM) proportionally to the number of messages that are currently stored in the JMS store. Then, try rebooting the server again. For more information on setting heap sizes, see "Tuning WebLogic Server Applications in the WebLogic Performance and Tuning Guide.

JMS File Store Tasks

A JMS file store consists of a disk-based file that is used for storing persistent messages and durable subscribers on a local file system. It is also the recommended store for temporarily paging messages to disk when memory has been exhausted.
Notes: In order for a JMS file store to handle failure recovery, the disk must be shared or migrated. Therefore, it is highly recommended that you implement a hardware solution, such as a dual-ported SCSI disk or Storage Area Network (SAN) to make your file store available from other machines.
Also, you should avoid using a Network File System (NFS) solution to access JMS file stores due to synchronicity limitations and performance issues.

Creating a JMS File Store

A disk-based JMS file store stores persistent messages and durable subscribers in a file-system directory. This directory must exist on your file system, so be sure to create it before completing this tab.

Expand the JMS - > Stores node. The JMS Stores table displays in the right pane showing all the JMS stores.
Click the Create a new JMS File Store text link. A dialog shows the tabs associated with configuring a new file store.
On the Configuration tab, define the general file store attributes:
Enter a name for the file store. This name must be unique within the WebLogic Server instance or its cluster. For more information, see JMS Configuration Naming Rules.
Select a Synchronous Write policy to determine how this JMS file store writes data to disk. This policy also affects the JMS file store's performance, scalability, and reliability. For more information see, Improving JMS File Store Performance.
Note: If the JMS 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 JMS 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.
Click Create to create a file store instance with the name you specified in the Name field. The new instance is added under the Stores node in the left pane.

Configuring a Paging Store

A JMS file store is the recommended store type when configuring message paging for the JMS server and destinations. A paging store cannot be the same JMS file store used for storing persistent messages or durable subscribers for a JMS server. Therefore, you need to configure an additional JMS file store to be used exclusively for message paging for each JMS server.
For more information on configuring paging for a JMS server, see Paging Out Messages To Free Up Memory.

Expand the JMS - > Stores node. The JMS Stores table displays in the right pane showing all the JMS stores.
Click the Create a new JMS File Store text link. A dialog shows the tabs associated with configuring a new file store.
On the Configuration tab, define the general file store attributes:
Enter a name for the file store. This name must be unique within the WebLogic Server instance or its cluster (for example, "JMSPagingStore"). For more information, see JMS Configuration Naming Rules.
The Synchronous Write policy is ignored when the JMS file store is used exclusively for paging out messages to disk.
Enter the pathname to the directory on the file system where the JMS 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.
Click Create to create a paging store instance with the name you specified in the Name field. The new instance is added under the Stores node in the left pane.
Make sure to select this "paging" file store on the JMS Server Configuration General tab.

JMS JDBC Store Tasks

Through the use of JDBC, JMS enables you to store persistent messages in a database, which is accessed through a designated JDBC connection pool. The JMS database can be any database that is accessible through a JDBC driver. WebLogic JMS detects some drivers for the following databases:

Pointbase
Microsoft SQL (MSSQL) Server
Oracle
Sybase
Cloudscape
Informix
IBM DB2
Times Ten

The weblogic/jms/ddl directory within the weblogic.jar file contains JMS DDL files for these databases, which are actually text files containing the SQL commands that create the JMS database tables. To use a different database, simply copy and edit any one of these .ddl files. Note that the JMS samples provided with your WebLogic Server distribution are set up to work with the Pointbase Java database. An evaluation version of Pointbase is included with WebLogic Server and a demoPool database is provided.
If your existing JMS JDBC stores somehow become corrupted, you can regenerate them using the utils.Schema utility. For more information see, "JDBC Database Utility in Programming WebLogic JMS.

Creating a JMS JDBC Store

Expand the JMS - > Stores node. The JMS Stores table displays in the right pane showing all the JMS stores.
Click the Create a new JMS JDBC Store text link. A dialog shows the tabs associated with configuring a new JDBC store.
On the Configuration tab, define the general JMS JDBC store attributes:
Enter a name for the JDBC-accessible database store. This name must be unique within the WebLogic Server instance or its cluster. For more information, see JMS Configuration Naming Rules.
Select an existing JDBC connection pool that will be used to access the JMS JDBC store. For more information see,
Enter the prefix name that will be prepended to the JMS table names in this JMS JDBC store for use with multiple instances.

For more information about the JMS JDBC store attributes, see JMS JDBC Store --> Configuration.
Click Create to create a JDBC store instance with the name you specified in the Name field. The new instance is added under the Stores node in the left pane.

Using Prefixes with JMS JDBC Stores

The JMS database contains two system tables that are generated automatically and are used internally by JMS:

<prefix>JMSStore
<prefix>JMSState

When a JMS JDBC store is used, WebLogic Server JMS may spend a significant amount of time scanning all database tables to find its own tables. If, however, the name of the store includes a unique prefix that includes the schema name, this search time can be reduced, thus improving boot performance.
For this reason we recommend adding a unique prefix to the store name when configuring a JMS JDBC store to identify JMS tables in the store. The prefix may be any string, but in many databases, the user name is used as the schema name. A prefix is prepended to table names when the DBMS requires fully qualified names, or when differentiate between JMS tables for two WebLogic Servers, enabling multiple tables to be stored on a single DBMS.
Warning: No two JMS stores should be allowed to use the same database tables, as this will result in data corruption.
Specify the prefix using the following format, which will result in a valid table name when prepended to the JMS table name:
[[[catalog.]schema.]prefix]JMSStore
where catalog identifies the set of system tables being referenced by the DBMS and schema translates to the ID of the table owner. For example, in a production database the JMS administrator could maintain a unique table for the Sales department, as follows:
[[[Production.]JMSAdmin.]Sales]JMSStore
Note: For some DBMS vendors, such as Oracle, there is no catalog to set or choose, so this format simplifies to [[schema.]prefix]. For more information, refer to your DBMS documentation for instructions on how to write and use a fully-qualified table name.

Recommended JDBC Connection Pool Settings for JMS JDBC Stores

The following settings are recommended when using a JDBC connection pool for JMS JDBC stores.

Automatic Reconnection to Failed Databases

WebLogic Server provides robust JDBC connection pools that can automatically reconnect to failed databases after they come back online, without requiring you to restart WebLogic Server. To take advantage of this capability, and make your use of JMS JDBC stores more robust, configure the following attributes on the JDBC connection pool associated with the JMS JDBC store:
TestConnectionsOnReserve="true"



TestTableName="[[[catalog.]schema.]prefix]JMSState"
Required Setting for WebLogic Type 4 JDBC DB2 Drivers

For connection pools used as a JMS JDBC store that use the WebLogic Type 4 JDBC driver for DB2, the BatchPerformanceWorkaround property must be set to "true" due to internal JMS batching requirements.
For more information, see the "Peformance Workaround for Batch Inserts and Updates section in the WebLogic Type 4 JDBC Drivers documentation.

Handling Transactions with JMS JDBC Stores

You cannot configure a transaction (XA) JDBC connection pool or JDBC TxDataSource to use with a JMS JDBC store. JMS must use a JDBC connection pool that uses a non-TxDataSource with a non-XAResource driver (you cannot use an XA driver or a JTS driver, or implement the "Emulate Two-Phase Commit for non-XA Driver" option). WebLogic JMS does the XA support above the JDBC driver.
This is because WebLogic JMS is its own resource manager. That is, JMS itself implements the XAResource and handles the transactions without depending on the database (even when the messages are stored in the database). This means that whenever you are using JMS and a database (even if it is the same database where the JMS messages are stored), then it is two-phase commit transaction. For more information about using transactions with WebLogic JMS, see "Using Transactions with WebLogic JMS in Programming WebLogic JMS.
From a performance perspective, you may boost your performance if the JDBC connection pool used for the database work exists on the same WebLogic Server as the JMS queue - the transaction will still be two-phase, but it will be handled with less network overhead. Another performance boost might be achieved by using JMS file stores rather than JMS JDBC stores.

Session Pools Tasks

Server session pools enable an application to process messages concurrently. After you define a JMS server, optionally, configure one or more session pools for each JMS server. Some session pool attributes are dynamically configurable, but the new values do not take effect until the session pools are restarted.
Note: Session pools are now used rarely, as they are not a required part of the J2EE specification, do not support JTA user transactions, and are largely superceded by message-driven beans (MDBs), which are a required part of the J2EE specification.
For more information about creating session pools, see "Developing a WebLogic JMS Application in Programming WebLogic JMS

Creating a JMS Session Pool

Use the Session Pools node in the Administration Console and define the following configuration attributes:

Expand the JMS - > Servers node.
Expand a JMS server instance under Servers.
Click the Session Pools node. The Session Pools table displays in the right pane showing all the session pools.
Click the Configure a new JMS Session Pool text link. A dialog shows the tabs associated with configuring a new session pool.
On the Configuration tab, define the general session pool attributes:
Enter a name for the server session pool. This name must be unique within the WebLogic Server instance or its cluster. For more information, see JMS Configuration Naming Rules.
Enter the connection factory name with which the server session pool is associated and is used to create sessions.
Enter the message listener class used to receive and process messages concurrently.
Select the acknowledge mode used by non-transacted sessions within this JMS session pool.
Specify the maximum number of concurrent sessions.
Select whether the session pool creates transacted sessions.

For more information about the session pool attributes, see JMS Session Pool --> Configuration.
Click Create to create a session pool instance with the name you specified in the Name field. The new instance is added under the Session Pools node in the left pane.

Connection Consumers Tasks

Connection consumers are queues (Point-To-Point) or topics (Pub/Sub) that retrieve server sessions and process messages. After you define a session pool, configure one or more connection consumers for each session pool.
For more information about creating connection consumers, see "Developing a WebLogic JMS Application in Programming WebLogic JMS

Creating a JMS Connection Consumer

To configure connection consumers, use the Session Pools node to define the following configuration attributes:

Expand the JMS - > Servers node.
Expand a JMS server instance under Servers.
Expand the Session Pools node, and then click a session pool instance.
Click the Consumers node. The JMS Consumers table displays in the right pane showing all the connection consumers.
Click the Configure a new JMS Connection Consumer text link. A dialog shows the tabs associated with configuring a new connection consumer.
On the Configuration tab, define the general connection consumer attributes:
Enter a name for the connection consumer. This name must be unique within the WebLogic Server instance or its cluster. For more information, see JMS Configuration Naming Rules.
Specify the maximum number of messages that can be accumulated by the connection consumer.
Specify the JMS selector expression used to filter messages. For information about defining selectors, see Developing a WebLogic JMS Application in Programming WebLogic JMS.
Specify the destination on which the connection consumer will listen.

For more information about the connection consumer attributes, see JMS Connection Consumer --> Configuration.
Click Create to create a connection consumer instance with the name you specified in the Name field. The new instance is added under the Consumers node in the left pane.

JMS Distributed Destination Tasks

A distributed destination is a set of physical destinations (queues or topics) that are called under a single JNDI name so they appear to be a single, logical destination to a client, when the members of the set are actually distributed across multiple servers within a cluster, with each destination member belonging to a separate JMS server.
By enabling you to configure multiple physical queues and topics as members of a distributed destination, WebLogic JMS supports high availability and load balancing of the JMS destinations within a cluster. For more information about using a distributed destination with your applications, see "Using Distributed Destinations in Programming WebLogic JMS.

Guidelines for Configuring Distributed Destinations

You configure distributed JMS destinations through the Services - > JMS - > Distributed Destinations node. To facilitate the configuration process, these instructions are divided into procedures that address the following scenarios:

New implementations of WebLogic JMS with no physical destinations or existing configurations of WebLogic JMS that do not require previously configured destinations to be part of a distributed destination:
Creating a Distributed Topic and Creating Members Automatically
Creating a Distributed Queue and Creating Members Automatically

Existing implementations of WebLogic JMS that require previously configured destinations to be members of a distributed destination set:
Creating a Distributed Topic and Adding Existing Physical Topics as Members Manually
Creating a Distributed Queue and Adding Existing Physical Queues as Members Manually
Note that the default Load Balancing Enabled and Server Affinity Enabled attributes for tuning a distributed destination configuration can be modified on the JMS connection factory through the Administration Console. For more information, see Configuring Message Load Balancing Across a Distributed Destination and Configuring Server Affinity For a Distributed Destination.
When a distributed topic or queue destination is created, a corresponding JMS template is automatically created with default attribute values for the distributed destination members. The new template will appear under the JMS Templates node with the same name as the distributed destination. The thresholds, quotas, and other attributes for the distributed destination members can be reset using this template.

Creating a Distributed Topic and Creating Members Automatically

Follow these steps to configure a distributed topic and automatically create its topic members on JMS servers that are part of a WebLogic Server cluster (for high availability) or on an single WebLogic Server instance that is not part of a cluster.

Expand the JMS - > Distributed Destinations node.
Click the Configure a new Distributed Topic link in the right pane. A dialog shows the tabs associated with configuring a new distributed topic.
On the Configuration General tab, define the general configuration attributes for the distributed topic.
Enter a name for the distributed topic.
Enter a JNDI name for accessing the distributed topic within the JNDI namespace. Applications use the JNDI Name to look up the distributed topic.
Note: A distributed topic that does not have a JNDI Name can be referenced by passing the Name of the distributed topic to javax.jms.TopicSession.createTopic().
Define how producers will distribute their messages across the members of a distributed topic. The valid values are Round-Robin and Random, as explained in Configuring Message Load Balancing Across a Distributed Destination.

For more information about the distributed topic general attributes, see JMS Distributed Topic --> Configuration --> General.
Click Create to create a distributed topic instance with the name you specified in the Name field. The new instance is added under the Distributed Destinations node in the left pane.
On the Thresholds & Quotas tab, define the following message/byte thresholds and maximum quota attributes for all distributed topic members:
Specify the maximum bytes or message quota that can be stored in a distributed topic.
Specify the upper threshold value that trigger events based on the number of bytes or messages stored in a distributed topic. Events include message paging, message flow control, and system log messages.
Specify the lower threshold value that trigger events based on the number of bytes or messages stored in a distributed topic. Events include message paging, message flow control, and system log messages.
Indicate whether bytes or messages paging is enabled on a distributed topic for temporarily swapping messages out from memory to a paging store when a distributed topic's message load reaches a specified bytes/messages threshold.
Specify the maximum size of a message that will be accepted from message producers on a distributed topic. The size includes the message body, any user-defined properties, and the user-defined JMS header fields: JMSCorrelationID and JMSType.

For more information about these attributes, see JMS Distributed Topic --> Configuration --> Thresholds and Quotas.
Click Apply to save any changes you made on this tab.
On the Auto Deploy tab, indicate the WebLogic Server instances where you want the distributed topic members to be automatically created.
Click the Create members on the selected Servers (and JMS Servers) text link. An auto deploy dialog prompts you to select one of the following options:
Select a cluster at which to target the distributed topic, and then click Next.
or
Accept the None option to bypass this dialog so you can select an individual server or servers that are part of the cluster. (In this case, skip to Step 10).

If you selected a cluster, do the following to select WebLogic Server instances within the cluster:

All WebLogic Server instances that are members of the cluster and that are not already hosting a distributed topic are listed and are selected by default. To exclude a server instance from hosting the distributed topic, clear the corresponding check box.
Click Next to proceed to the next dialog.
Skip to Step 11 to select the JMS servers that are available on the selected WebLogic Servers for creating distributed topic members.

If you selected None on the Cluster dialog in Step 8, select a single WebLogic Server instance in the domain:

From the list box, select an individual server where you want to create a distributed topic member.
Click Next to proceed to the next dialog.

All JMS servers that are deployed on the selected WebLogic Server instances, and that are not already hosting a distributed topic, are listed and are selected by default. To exclude a JMS server from hosting the distributed topic member, clear the corresponding check box.
If there are no existing distributed topic members on the selected JMS servers, one new JMS Topic will be created on each JMS server and added as a member of the distributed topic.
Click Next to proceed to the final Auto Deploy dialog.
Click Apply to save your Auto Deploy selections.
Click the Configuration - > Members tab to view the topic members that were automatically created for the new distributed topic.
Expand the JMS - > Templates node to view the JMS template that was automatically created with the same name as the distributed topic.

Creating a Distributed Topic and Adding Existing Physical Topics as Members Manually

For existing implementations of WebLogic JMS that require previously configured destinations to be members of a distributed destination set, follow these steps to configure a distributed topic and manually add your existing physical topics as members:

Expand the JMS - > Distributed Destinations node.
Click the Configure a new Distributed Topic link in the right pane. A dialog shows the tabs associated with configuring a new distributed topic.
On the Configuration General tab, define the general configuration attributes for the distributed topic.
Enter a name for the distributed topic.
Enter a JNDI name for accessing the distributed topic within the JNDI namespace. Applications use the JNDI Name to look up the distributed topic.
Note: A distributed topic that does not have a JNDI Name can be referenced by passing the Name of the distributed topic to javax.jms.TopicSession.createTopic().
Define how producers will distribute their messages across the members of a distributed topic. The valid values are Round-Robin and Random as defined in Configuring Message Load Balancing Across a Distributed Destination.

For more information about the distributed topic general attributes, see JMS Distributed Topic --> Configuration --> General.
Click Create to create a distributed topic instance with the name you specified in the Name field. The new instance is added under the Distributed Destinations node in the left pane.
On the Thresholds & Quotas tab, define the following upper and lower message/byte threshold and maximum quota attributes for all distributed topic members:
Specify the maximum bytes or message quota that can be stored in a distributed topic.
Specify the upper threshold value that trigger events based on the number of bytes or messages stored in a distributed topic. Events include message paging, message flow control, and system log messages.
Specify the lower threshold value that trigger events based on the number of bytes or messages stored in a distributed topic. Events include message paging, message flow control, and system log messages.
Indicate whether bytes or messages paging is enabled on a distributed topic for temporarily swapping messages out from memory to a paging store when a distributed topic's message load reaches a specified bytes/messages threshold.
Specify the maximum size of a message that will be accepted from message producers on a distributed topic. The size includes the message body, any user-defined properties, and the user-defined JMS header fields: JMSCorrelationID and JMSType.

If a distributed topic member's underlying physical topic already uses a JMS Template with configured thresholds and quotas, these attributes will not apply to that topic member. For more information about these attributes, see JMS Distributed Topic --> Configuration --> Thresholds and Quotas.
Click Apply to Apply to save any changes you made on this tab.
Note: If you want to automatically create topic members on JMS servers that are part of a WebLogic Server cluster (for high availability) or on an single WebLogic Server instance that is not part of a cluster, see Creating a Distributed Topic and Creating Members Automatically.
On the Configuration - > Members tab, create distributed topic members for your existing physical topics.
Click the Configure a new Distributed Topic Member link in the right pane. A Configuration dialog shows the tabs associated with configuring a new distributed topic member.
On the Configuration tab, define the general configuration attributes for the distributed topic.
Uniquely identify the distributed topic member within a WebLogic Server domain.
Select the underlying physical topic that is associated with the distributed topic member.
Define the weight (that is, a measure of ability to handle message load) of the topic member with respect to other topic members in the distributed destination. For more information about load balancing distributed destinations, see "Developing a WebLogic JMS Application in Programming WebLogic JMS.

For more information about distributed topic member attributes, see JMS Distributed Topic Member --> Configuration.
Click Create to create the new distributed topic member. The new member is added to the Distributed Topic table.
If necessary, repeat steps 8-10 to continue adding topic members to the distributed topic.
Expand the JMS - > Templates node to view the JMS template that was automatically created with the same name as the distributed topic.

Creating a Distributed Queue and Creating Members Automatically

Follow these steps to configure a distributed queue and automatically create its queue members on JMS servers that are part of a WebLogic Server cluster (for high availability) or on an single WebLogic Server instance that is not part of a cluster.

Expand the JMS - > Distributed Destinations node.
Click the Configure a new Distributed Queue link in the right pane. A Configuration dialog shows the tabs associated with configuring a new distributed queue.
On the Configuration General tab, define the general configuration attributes for the distributed topic.
Enter a name for the distributed queue.
Enter a JNDI name for accessing the distributed queue within the JNDI namespace. Applications use the JNDI Name to look up the distributed queue.
Note: A distributed queue that does not have a JNDI Name can be referenced by passing the Name of the distributed topic to javax.jms.QueueSession.createQueue().
Define how producers will distribute their messages across the members of a distributed queue. The valid values are Round-Robin and Random, as explained in Configuring Message Load Balancing Across a Distributed Destination.
Define the amount of time, in seconds, that a distributed queue member with messages, but which has no consumers, will wait before forwarding its messages to other queue members that do have consumers.

For more information about the distributed queue general attributes, see JMS Distributed Queue --> Configuration --> General.
Click Create to create a distributed queue instance with the name you specified in the Name field. The new instance is added under the Distributed Destinations node in the left pane.
On the Thresholds & Quotas tab, define the following upper and lower message/byte threshold and maximum quotas for all distributed queue members:
Specify the maximum bytes or message quota that can be stored in a distributed queue.
Specify the upper threshold value that trigger events based on the number of bytes or messages stored in a distributed queue. Events include message paging, message flow control, and system log messages.
Specify the lower threshold value that trigger events based on the number of bytes or messages stored in a distributed queue. Events include message paging, message flow control, and system log messages.
Indicate whether bytes or messages paging is enabled on a distributed topic for temporarily swapping messages out from memory to a paging store when a distributed queue's message load reaches a specified bytes/messages threshold.
Specify the maximum size of a message that will be accepted from message producers on a distributed queue. The size includes the message body, any user-defined properties, and the user-defined JMS header fields: JMSCorrelationID and JMSType.

If a distributed queue member's underlying physical queue already uses a JMS Template with configured thresholds and quotas, these attributes will not apply to that queue member. For more information about these attributes, see JMS Distributed Topic --> Configuration --> Thresholds and Quotas.
Click Apply to save any changes you made on this tab.
On the Auto Deploy tab, indicate the WebLogic Server instances where you want the distributed queue members to be automatically created.
Click the Create members on the selected Servers (and JMS Servers) text link. A dialog prompts you to select one of the following options:
Select a cluster at which to target the distributed queue, and then click Next.
or
Accept the None option to bypass this dialog so you can select an individual server that is not in a cluster. (In this case, skip to Step 10).

If you selected a cluster, do the following to select WebLogic Server instances within the cluster:

All servers that are members of the cluster, and which are not already hosting a distributed queue, are listed and are selected by default. To exclude a server from hosting the distributed queue, clear the corresponding check box.
Click Next to proceed to the next dialog.
Skip to Step 11 to select the JMS servers that are available on the selected WebLogic Servers for creating distributed queue members.

If you selected None on the Cluster dialog in Step 8, select a single WebLogic Server instance in the domain:

From the list box, select an individual server where you want to create the distributed queue member.
Click Next to proceed to the next dialog.

All JMS servers that are deployed on the selected WebLogic Servers, and which are not already hosting a distributed queue, are listed and are selected by default. To exclude a JMS server from hosting the distributed queue member, clear the corresponding check box.
If there are no existing distributed queue members on the selected JMS servers, one new JMS Queue will be created on each JMS server and added as a member of the distributed queue.
Click Next to proceed to the final Auto Deploy dialog.
Click Apply to save your Auto Deploy selections.
Click the Configuration - > Members tab to view the queue members that were automatically created for the new distributed queue.
Expand the JMS - > Templates node to view the JMS template that was automatically created with the same name as the distributed queue.

Creating a Distributed Queue and Adding Existing Physical Queues as Members Manually

For existing implementations of WebLogic JMS that require previously configured destinations to be members of a distributed destination set, follow these steps to configure a distributed queue and manually add your existing physical queues as members.

Expand the JMS - > Distributed Destinations node.
Click the Configure a new Distributed Queue link in the right pane. A Configuration dialog shows the tabs associated with configuring a new distributed queue.
On the Configuration General tab, define the general configuration attributes for the distributed topic.
Enter a name for the distributed queue.
Enter a JNDI name for accessing the distributed queue within the JNDI namespace. Applications use the JNDI Name to look up the distributed queue.
Note: A distributed queue that does not have a JNDI Name can be referenced by passing the Name of the distributed topic to: javax.jms.QueueSession.createQueue().
Define how producers will distribute their messages across the members of a distributed queue. The valid values are Round-Robin and Random, as explained in Configuring Message Load Balancing Across a Distributed Destination.
Define the amount of time, in seconds, that a distributed queue member with messages, but which has no consumers, will wait before forwarding its messages to other queue members that do have consumers.

For more information about the distributed queue general attributes, see JMS Distributed Queue --> Configuration --> General.
Click Create to create a distributed queue instance with the name you specified in the Name field. The new instance is added under the Distributed Destinations node in the left pane.
On the Thresholds & Quotas tab, define the following upper and lower message/byte threshold and maximum quotas for all distributed queue members:
Specify the maximum bytes or message quota that can be stored in a distributed queue.
Specify the upper threshold value that trigger events based on the number of bytes or messages stored in a distributed queue. Events include message paging, message flow control, and system log messages.
Specify the lower threshold value that trigger events based on the number of bytes or messages stored in a distributed queue. Events include message paging, message flow control, and system log messages.
Indicate whether bytes or messages paging is enabled on a distributed topic for temporarily swapping messages out from memory to a paging store when a queue's message load reaches a specified bytes/messages threshold.
Specify the maximum size of a message that will be accepted from message producers on a distributed queue. The size includes the message body, any user-defined properties, and the user-defined JMS header fields: JMSCorrelationID and JMSType.

If a distributed queue member's underlying physical queue already has a JMS Template with configured thresholds and quotas, these attributes will not apply to that queue member. For more information about these attributes, see JMS Distributed Queue --> Configuration --> Thresholds and Quotas.
Click Apply to save any changes you made on this tab.
Note: If you want to automatically create queue members on JMS servers that are part of a WebLogic Server cluster (for high availability) or on an single WebLogic Server instance that is not part of a cluster, see Creating a Distributed Queue and Creating Members Automatically.
Click the Configuration - > Members tab to define the queue members for the distributed queue.
Click the Configure a new Distributed Queue Member text link in the right pane. A Configuration dialog shows the tabs associated with configuring a new distributed queue member.
On the Configuration tab, define the general configuration attributes for the distributed queue.
Uniquely identify the distributed queue member within a WebLogic Server domain.
Select the underlying physical queue that is associated with the distributed queue member.
Define the weight (that is, a measure of ability to handle message load) of the queue member with respect to other topic members in the distributed destination. For more information about load balancing for distributed destinations, see "Developing a WebLogic JMS Application in Programming WebLogic JMS.

For more information about distributed queue member attributes, see JMS Distributed Queue Member --> Configuration.
Click Create to create the new distributed queue member. The new member is added to the Distributed Queue table.
Repeat steps 8-10 to continue adding members to the distributed queue.
Expand the JMS - > Templates node to view the JMS template that was automatically created with the same name as the distributed queue.

Creating a JMS Distributed Queue Member

Follow these steps to add an existing physical queue as a member of distributed queue.

Expand the JMS - > Distributed Destinations node. The Distributed Destinations table displays in the right pane showing all the distributed queues and topics.
Click the distributed queue that you want to add a member to. The Distributed Queue table shows all the distributed queue members that belong to the distributed queue.
Click the Configure a new Distributed Queue Member text link. A dialog shows the Configuration tab for configuring a new distributed queue member.
Define the configuration attributes for the distributed queue.
Uniquely identify the distributed queue member within a WebLogic Server domain.
Select the underlying physical queue that is associated with the distributed queue member.
Define the weight (that is, a measure of ability to handle message load) of the queue member with respect to other topic members in the distributed destination. For more information about load balancing for distributed destinations, see "Developing a WebLogic JMS Application in Programming WebLogic JMS.

For more information about distributed queue member attributes, see JMS Distributed Queue Member --> Configuration.
Click Create to create a distributed queue member with the name you specified in the Name field. The new member is added to the Distributed Queue Member table in the right pane.
Click Apply to save any changes you made.

Deleting a JMS Distributed Queue Member

Follow these steps to delete a member of distributed queue, and if necessary, to delete the member's underlying physical queue.
Note: If you need to delete the entire distributed queue, then follow the directions for Deleting a Distributed Destination.

Expand the JMS - > Distributed Destinations node. The Distributed Destinations table displays in the right pane showing all the distributed queues and topics.
Click the distributed queue that you want to delete a member from. The Distributed Queue table shows all the distributed queue members that belong to the distributed queue.
Click the Delete icon in the row of the distributed queue member that you want to delete. A dialog prompts you to confirm your deletion request.
If you want to also remove the underlying physical queue, select the Also Delete check box.
Click Remove to delete the distributed queue member (and the underlying physical queue if selected).
The Distributed Queue table redisplays in the right pane. The distributed queue member is deleted from the Distributed Queue table.

Creating a JMS Distributed Topic Member

Follow these steps to add an existing physical queue as a member of distributed queue.

Expand the JMS - > Distributed Destinations node. The Distributed Destinations table displays in the right pane showing all the distributed queues and topics.
Click the distributed topic that you want to add a member to. The Distributed Topic table shows all the distributed topic members that belong to the distributed topic.
Click the Configure a new Distributed Topic Member text link. A dialog shows the Configuration tab for configuring a new distributed topic member.
Define the general configuration attributes for the distributed topic.
Uniquely identify the distributed topic member within a WebLogic Server domain.
Select the underlying physical topic that is associated with the distributed topic member.
Define the weight (that is, a measure of ability to handle message load) of the topic member with respect to other topic members in the distributed destination. For more information about load balancing distributed destinations, see "Developing a WebLogic JMS Application in Programming WebLogic JMS.

For more information about distributed topic member attributes, see JMS Distributed Topic Member --> Configuration.
Click Create to create a distributed topic member with the name you specified in the Name field. The new member is added to the Distributed Topic table in the right pane.
Click Apply to save any changes you made.

Deleting a JMS Distributed Topic Member

Follow these steps to delete a member of distributed topic, and if necessary, to delete the member's underlying physical topic.
Note: If you need to delete the entire distributed topic, then follow the directions for Deleting a Distributed Destination.

Expand the JMS node.
Expand the Distributed Destinations node. The Distributed Destinations table displays in the right pane showing all the distributed queues and topics.
Click the distributed topic that you want to delete a member from. The Distributed Topic table shows all the distributed topic members that belong to the distributed topic.
Click the Delete icon in the row of the distributed topic member that you want to delete. A dialog prompts you to confirm your deletion request.
If you want to also remove the underlying physical queue, select the Also Delete check box.
Click Remove to delete the distributed topic member (and the underlying physical topic if selected).
The Distributed Topic table redisplays in the right pane. The distributed topic member is deleted from the Distributed Topic table.

Deleting a Distributed Destination

If you need to delete an entire distributed destination, remove it in the following sequence:

Delete all the members of the distributed queue or distributed topic, as explained in the following sections:
Deleting a JMS Distributed Queue Member
Deleting a JMS Distributed Topic Member

Delete the distributed destination itself by expanding the JMS - > Distributed Destinations node, and then clicking the trash icon next to the distributed destination that you want to delete.
Note: You can only delete a distributed destination when all its members have been properly deleted.
You can delete the JMS template that is associated with the distributed destination. However, make sure that this template is not being used by other JMS servers or destinations. To delete a JMS Template, expand the JMS - > Templates node, and then click the trash icon in the row of the JMS template that you want to delete.

Monitoring a Distributed Destinations

When monitoring distributed destinations, you may see proxy topic members or system subscriptions, which are automatically created for the topic or queue members. For more information see, Monitoring Distributed Destination System Subscriptions and Proxy Topic Members.

Simple Access to Remote or Foreign JMS Providers

WebLogic JMS enables you to reference foreign (that is, third-party) JMS providers within a local WebLogic Server JNDI tree. Using the Foreign JMS Server node, you can quickly map a foreign JMS provider so that its associated connection factories and destinations appear in the WebLogic JNDI tree as local JMS objects. A Foreign JMS Server configuration can also be used to reference remote instances of WebLogic Server in another cluster or domain in the local WebLogic JNDI tree.
Note: In order to use the Foreign JMS Providers feature to reference remote WebLogic Server clusters or domains, have a clustered JMS license, which allows a connection factory and a destination to be on different server instances. If you do not have a valid clustered JMS license, contact your BEA sales representative.
The following sections provide more information on how the Foreign JMS Server node works, configuration instructions, and a sample configuration for accessing a remote MQSeries JNDI provider.

How WebLogic JMS Accesses Foreign JMS Providers
Creating a Foreign JMS Server
Creating a Foreign JMS Connection Factory
Creating a Foreign JMS Destination
Sample Configuration for MQSeries JNDI

How WebLogic JMS Accesses Foreign JMS Providers

When a foreign JMS server is deployed, it creates local connection factory and destination objects in WebLogic Server JNDI. Then when a foreign JMS connection factory or destination object is looked up on the local server, that object performs the actual lookup on the remote JNDI directory, and the foreign object is returned from that directory.
This method makes it easier to configure multiple WebLogic Messaging Bridge destinations, since the foreign JMS server moves the JNDI Initial Context Factory and Connection URL configuration details outside of your Messaging Bridge destination configurations. You need only provide the foreign Connection Factory and Destination JNDI name for each object.
For more information on configuring a Messaging Bridge, see Messaging Bridge Configuration Tasks.
The ease-of-configuration concept also applies to configuring WebLogic Servlets, EJBs, and Message-Driven Beans (MDBs) with WebLogic JMS. For example, the weblogic-ejb-jar.xml file in the MDB can have a local JNDI name, and you can use the foreign JMS server to control where the MDB receives messages from. For example, you can deploy the MDB in one environment to talk to one JMS destination and server, and you can deploy the same weblogic-ejb-jar.xml file to a different server and have it talk to a different JMS destination without having to unpack and edit the weblogic-ejb-jar.xml file.

Creating a Foreign JMS Server

A Foreign JMS Server represents a JNDI provider that is outside the WebLogic JMS server. It contains information that allows a local WebLogic Server instance to reach a remote JNDI provider, thereby allowing for a number of foreign JMS connection factory and destination objects to be defined on one JNDI directory.
After defining a foreign JMS server, you can configure connection factory and destination objects. You can configure one or more connection factories and destinations (queues or topics) for each foreign JMS server.
To configure a foreign JMS server, follow these steps:

Expand the JMS node in the navigation tree, and then click the Foreign JMS Servers node.
Click the Configure a new Foreign JMSServer text link in the right pane. A dialog shows the tabs associated with configuring a new Foreign JMS server.
On the Configuration General tab, enter values in the Name, JNDI Initial Context Factory, JNDI Connection URL, and JNDI Properties attribute fields.
For a detailed description of the general Foreign JMS Server attributes, see Foreign JMS Server --> Configuration --> General. Note that the JNDI Properties values may be a name=value list of properties, separated by commas.

Click Create to create a foreign JMS server instance with the name you specified in the Name field. The new instance is added under the Foreign JMS Servers node in the navigation tree, and a Foreign JMS Connection Factories node and Foreign JMS Destinations node are automatically added under the new foreign JMS server instance.
On the Targets tab, select a standalone WebLogic Server instance or a cluster on which to deploy the foreign JMS server.
Servers tab - On the Available list, select the WebLogic Server instance where you want to deploy the foreign JMS server object.
Clusters tab - On the Targets list, select a WebLogic Server cluster in order to deploy the foreign JMS server object on every node in the cluster. Note that the Clusters tab is available only when the JMS server is part of a clustered WebLogic Server environment.

Click Apply to target the foreign JMS server.

Continue by configuring a connection factory and destination objects. You can configure one or more connection factories and destinations (queues or topics) for each foreign JMS server.

Creating a Foreign JMS Connection Factory

A Foreign JMS Connection Factory contains the JNDI name of the connection factory in the remote JNDI provider, the JNDI name that the connection factory is mapped to in the local WebLogic Server JNDI tree, and an optional user name and password.
The foreign JMS connection factory creates non-replicated JNDI objects on each WebLogic Server instance that the parent foreign JMS server is targeted to. (To create the JNDI object on every node in a cluster, target the foreign JMS server to the cluster.)
To configure a foreign JMS connection factory, follow these steps:

Expand the Foreign JMS Servers node, and then expand the Foreign JMS Connection Factories node.
Click the Configure a new Foreign JMSConnection Factory text link. A dialog displays in the right pane showing the tabs associated with configuring a new foreign JMS connection factory.
On the Configuration General tab, enter values in the Name, Local JNDI Name, Remote JNDI Name, User Name, and Password attribute fields.
For a detailed description of the general Foreign JMS Connection Factory attributes, see Foreign JMS Connection Factory --> Configuration --> General.

Note that the user name and password are only used when the Foreign JMS Connection Factory is used inside a resource-reference in an EJB or a servlet, and when the Container mode of authentication is used.
Click Create to create a foreign JMS connection factory instance with the name you specified in the Name field. The new instance is added under the Foreign JMS Connection Factory node in the navigation tree.

Continue by configuring the destination objects. You can configure one or more destinations (queues or topics) for each foreign JMS server.

Creating a Foreign JMS Destination

A Foreign JMS Destination represents either a queue or a topic. It contains the destination JNDI name that is looked up on the foreign JNDI provider and the JNDI name that the destination is mapped to on the local WebLogic Server. When the foreign destination is looked up on the local server, a lookup is performed on the remote JNDI directory, and the destination object is returned from that directory.
To configure a foreign JMS destination, follow these steps:

Expand the Foreign JMS Servers node, and then expand the Foreign JMS Destinations node.
Click the Configure a new Foreign JMSDestination text link. A dialog displays in the right pane showing the tabs associated with configuring a foreign destination.
On the Configuration General tab, enter values in the Name, Local JNDI Name and Remote JNDI Name attribute fields.
For a detailed description of the general Foreign JMS Destination attributes, see Foreign JMS Destination --> Configuration --> General.

Click Create to create a foreign JMS destination instance with the name you specified in the Name field. The new instance is added under the Foreign JMS Destinations node in the navigation tree.

Sample Configuration for MQSeries JNDI

The following table provides a possible a sample configuration when accessing a remote MQSeries JNDI provider.

Foreign JMS Object

Attribute Names

Sample Configuration Data
Foreign JMS Server NameJNDI Initial Context FactoryJNDI Connection URLJNDI Properties MQJNDIcom.sun.jndi.fscontext.RefFSContextFactoryfile:/MQJNDI/(If necessary, enter a comma-separated name=value list of properties.)
Foreign JMS
Connection Factory NameLocal JNDI NameRemote JNDI NameUsernamePassword MQ_QCFmqseries.QCFQCFweblogic_jmsweblogic_jms
Foreign JMS
Destination 1

Foreign JMS
Destination 2 NameLocal JNDI NameRemote JNDI Name
NameLocal JNDI NameRemote JNDI Name MQ_QUEUE1mqseries.QUEUE1QUEUE_1
MQ_QUEUE2mqseries.QUEUE2QUEUE_2

For detailed information about foreign server, connection factory, and attributes, and the valid and default values for them, refer to the following sections:

Foreign JMS Server --> Configuration --> General
Foreign JMS Connection Factory --> Configuration --> General
Foreign JMS Destination --> Configuration --> General

Default Connection Factory. . .	XAConnectionFactoryEnabled setting is. . .
weblogic.jms.ConnectionFactory	False
weblogic.jms.XAConnectionFactory	True

Foreign JMS Object	Attribute Names	Sample Configuration Data
Foreign JMS Server	NameJNDI Initial Context FactoryJNDI Connection URLJNDI Properties	MQJNDIcom.sun.jndi.fscontext.RefFSContextFactoryfile:/MQJNDI/(If necessary, enter a comma-separated name=value list of properties.)
Foreign JMS Connection Factory	NameLocal JNDI NameRemote JNDI NameUsernamePassword	MQ_QCFmqseries.QCFQCFweblogic_jmsweblogic_jms
Foreign JMS Destination 1 Foreign JMS Destination 2	NameLocal JNDI NameRemote JNDI Name NameLocal JNDI NameRemote JNDI Name	MQ_QUEUE1mqseries.QUEUE1QUEUE_1 MQ_QUEUE2mqseries.QUEUE2QUEUE_2