Managing WebLogic JMS

The WebLogic Server Administration Console provides an interface for easily enabling, configuring, and monitoring the features of the WebLogic Server, including JMS. To invoke the Administration Console, refer to the procedures described in "Starting and Stopping Servers" in the Administration Console Online Help.

The following sections provide an overview of configuring and monitoring WebLogic JMS:

• Configuring WebLogic JMS
• Configuring WebLogic JMS Clustering
• Configuring JMS Migratable Targets
• Tuning WebLogic JMS
• Monitoring WebLogic JMS
• Recovering from a WebLogic Server Failure

 

---

Configuring WebLogic JMS

Using the Administration Console, you define configuration attributes to:

• Enable JMS.
• Create JMS servers and target a WebLogic Server instance or a Migratable Target where the JMS server will be deployed.
• Create and/or customize values for JMS servers, connection factories, destinations (physical queues and topics), distributed destinations (sets of physical queue and topic members within a cluster) destination templates, destination sort ordering (using destination keys), persistent stores, paging stores, session pools, and connection consumers.
• Set up custom JMS applications.
• Define thresholds and quotas.
• Enable any desired JMS features, such as:
• server clustering using multiple connection factories
• concurrent message processing via session pools
• persistent messages and durable subscribers
• paging out messages during peak loads to free up memory
• controlling message flow during peak loads

WebLogic JMS provides default values for some configuration attributes; you must 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 Installing WebLogic Server.

When migrating from a previous release of Weblogic Server, the configuration information is converted automatically, as described in Porting Existing Applications.

To configure WebLogic JMS attributes, follow the procedures described in the "Configuring JMS" section of the Administration Console Online Help, to create and configure the JMS objects. 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.

Note: Configuration Checklists, provides checklists that enable you to view the attribute requirements and/or options for supporting various JMS features.

Starting WebLogic Server and Configuring JMS

The following sections review how to start WebLogic Server and the Administration console, as well as provide a procedure for configuring a basic JMS implementation.

Starting the Default WebLogic Server

The default role for a WebLogic Server is the Administration Server. If a domain consists of only one WebLogic Server, that server is the Administration Server. If a domain consists of multiple WebLogic Servers, you must start the Administration Server first, and then you start the Managed Servers.

For complete information about starting the Administration Server, see "Starting and Stopping Servers" in the Administration Console Online Help.

Starting the Administration Console

The Administration Console is the Web-based administrator front-end (administrator client interface) to WebLogic Server. You must start the server before you can access the Administration Console for a server.

For complete details about using the Administration Console to configure a WebLogic Server, see "Starting and Using the Administration Console" in Configuring and Managing a WebLogic Server.

Configuring a Basic JMS Implementation

This section describes how to configure a basic JMS implementation using the Administration Console.

1. Under the Services node in the left pane, click the JMS node to expand the list.
2. Optionally, create a File Store for storing persistent messages in a flat file, and/or a Paging Store for swapping messages out to memory:
   1. Click the Stores node in the left pane, and then click the Configure a new JMS File Store link in the right pane.
   2. On the General tab, give the store a name, specify a directory, and then click the Create button.
   3. Repeat these steps to create a Paging Store.

   Note: For more information on configuring file stores, see "JMS File Store Tasks" in the Administration Console Online Help.

3. Optionally, create a JDBC Store for storing persistent messages in a database:
   1. Click the JDBC node in the left pane to expand it.
   2. Click the Connection Pools node in the left pane, and then click the Configure a new JDBC Connection Pool link in the right pane.
   3. On the Configuration tabs, set the attributes for the connection pool, such as Name, URL, and database Properties. Click Apply on each tab when you're done making changes.
   4. On the Target and Deploy tab, target an independent WebLogic Server instance or a server cluster on which to deploy the connection pool by selecting the appropriate check box, and then click Apply.
   5. Return to the JMS -> Stores node, and then click the Configure a new JMS JDBC Store link in the right pane.
   6. Give the JDBC Store a name, select a connection pool, and a prefix name. Then click Create.

   Note: For more information on configuring JDBC-accessible JMS JDBC stores, see "JMS JDBC Store Tasks", "Configuring JDBC Connection Pools," "Configuring JDBC Multipools," and "Configuring JDBC DataSources" in the Administration Console Online Help.

4. Optionally, create a JMS Template to define multiple destinations with similar attribute settings. You also need a JMS Template to create temporary queues.
   1. Click the Templates node in the left pane, and then click the Configure a new JMS Template link in the right pane.
   2. On the General tab, give the template a name, and then click Create.
   3. Fill in the Thresholds & Quotas, Override, Expiration Policy, and Redelivery tabs, as appropriate. Click Apply on each tab when you're done making changes.

   Note: For more information on configuring a JMS Template, see "JMS Template Tasks" in the Administration Console Online Help.

5. Configure a JMS Server, as follows:
   1. Click the Server node in the left pane, and then click the Configure a new JMS Server link in the right pane.
   2. On the General tab, give the server a name, select a Store if you created one, select a Paging Store if you created one, and select a Template if you created one. Then click Create.
   3. Fill in the Thresholds & Quotas tab, as appropriate. Click Apply when you're done making changes.
   4. On the Target and Deploy tab, target an independent WebLogic Server instance or a Migratable Target server on which to deploy the JMS server by selecting the appropriate check box, and then click Apply.

   Note: For more information on configuring a JMS Server, see "JMS Server Tasks" in the Administration Console Online Help.

6. Create the JMS Destinations, which are queues (Point-To-Point) or topics (Pub/Sub):
   1. Under the Servers node in the left pane, click your new JMS server instance to expand the list, and then click the Destinations node.
   2. Click either the Configure a new JMS Queue or Configure a new JMS Topic link in the right pane.
   3. On the General tab, give the destination a name and a JNDI name. Fill in the other attributes, as appropriate, and then click Create.
   4. Fill in the Thresholds & Quotas, Override, Redelivery, Expiration Policy, and Multicast (for topics only) tabs, as appropriate. Click Apply on each tab when you're done making changes.

   Note: For more information on configuring a Destinations, see "JMS Destination Tasks" in the Administration Console Online Help.

7. Create a Connection Factory to enable your JMS clients to create JMS connections:
   1. Click to the expand the Connection Factory node and in the left pane, and then click the Configure a new JMS Connection Factory link in the right pane.
   2. On the General tab, give the connection factory a name and a JNDI name. Fill in the other attributes, as appropriate, and then click Create.
   3. Fill in the Transactions and Flow Control tabs, as appropriate. Click Apply on each tab when you're done making changes.
   4. On the Target and Deploy tab, target an independent WebLogic Server instance or a server cluster on which to deploy the connection factory by selecting selecting the appropriate check box, and then click Apply.

   Note: For more information on configuring a Connection Factory, see "JMS Connection Factory Tasks" in the Administration Console Online Help.

8. Optionally, use the Destination Keys node to define the sort order of messages that arrive on a specific destination. For more information, see "JMS Destination Key Tasks" in the Administration Console Online Help.
9. Optionally, use the Distributed Destinations node to make your physical destinations part of a single distributed destination set within a server cluster. For more information, see "Distributed Destinations Tasks" in the Administration Console Online Help.
10. Optionally, create JMS Session Pools, which enable your applications to process messages concurrently, and Connection Consumers (queues or topics) that retrieve server sessions and process messages. For more information, see "JMS Session Pools Tasks" and "JMS Connection Consumers Tasks" in the Administration Console Online Help.

 

---

Configuring WebLogic JMS Clustering

A WebLogic Server cluster is a group of servers that work together to provide a more scalable, more reliable application platform than a single server. A cluster appears to its clients as a single server but is in fact a group of servers acting as one. A cluster provides three key features above a single server:

• Scalability—servers can be added to the cluster dynamically to increase capacity.
• High Availability—redundancy of multiple servers insulates applications from failures. Redundancy of multiple destinations (queues and topics) as members of a single distributed destination set within a cluster ensures redistribution of the messaging load to other available members in the set when one member becomes unavailable.
• Migratability—respond to migration requests and bring a JMS server online and offline in an orderly fashion. This includes both scheduled migrations as well as migrations in response to a WebLogic Server failure.

A clustered service is an API or interface that is available on multiple servers in the cluster.

Note: JMS clients depend on unique WebLogic Server names to successfully access a cluster—even when WebLogic Servers reside in different domains. Therefore, make sure that all WebLogic Servers that JMS clients contact have unique server names.

For more information about starting WebLogic clusters and its features and benefits, see "Configuring WebLogic Servers and Clusters" in Using WebLogic Server Clusters.

How JMS Clustering Works

You can establish cluster-wide, transparent access to destinations from any server in the cluster by configuring multiple connection factories and using targets to assign them to WebLogic Servers. Each connection factory can be deployed on multiple WebLogic Servers. The administrator can configure multiple JMS servers on the various nodes in the cluster—as long as the JMS servers are uniquely named—and can then assign JMS destinations to the various JMS servers.

The application uses the Java Naming and Directory Interface (JNDI) to look up a connection factory and create a connection to establish communication with a JMS server. Each JMS server handles requests for a set of destinations. Requests for destinations not handled by a JMS server are forwarded to the appropriate WebLogic Server.

JMS Clustering Requirements

The following guidelines apply when configuring WebLogic JMS to work in a clustered environment in a single WebLogic domain or in a multi-domain environment.

• All WebLogic Servers that JMS clients contact must have unique server names.
• All JMS servers targeted to nodes in the cluster must be uniquely named.
• If persistent messaging is required, all JMS stores must be uniquely named.

JMS Distributed Destination within a Cluster

The WebLogic JMS administrator can also configure multiple destinations as part of a single distributed destination set within a cluster. Producers and consumers are able to send and receive to the distributed destination. In the event of a single server failure within the cluster, WebLogic JMS then distributes the load across all available physical destinations within the distributed destination set. For more information, see "Distributed Destination Tasks" in the Administration Console Online Help.

JMS as a Migratable Service within a Cluster

WebLogic JMS takes advantage of the migration framework implemented in the WebLogic Server core for clustered environments. This allows WebLogic JMS to properly respond to migration requests and bring a JMS server online and offline in an orderly fashion. This includes both scheduled migrations as well as migrations in response to a WebLogic Server failure. For more information, see Configuring JMS Migratable Targets.

Configuration Steps

In order to use WebLogic JMS in a clustered environment, you must:

1. Administer WebLogic clusters as described in "Configuring WebLogic Servers and Clusters" in Using WebLogic Server Clusters.
2. Identify server targets for JMS servers and for connection factories using the Administration Console:
   • For JMS servers, you can identify either a single-server target or a migratable target, which is a set of WebLogic Server instances in a cluster that can host an "exactly-once" service like JMS in case of a single server failure. For more information on migratable targets, see Configuring JMS Migratable Targets.
   • For connection factories, you can identify either a single-server target or a cluster target, which are WebLogic Server instances that are associated with a connection factory to support clustering.

   For more information about these configuration attributes, see "JMS Server Tasks" or "JMS Connection Factory Tasks" in the Administration Console Online Help.

   Note: You cannot deploy the same destination on more than one JMS server. In addition, you cannot deploy a JMS server on more than one WebLogic Server.

3. Optionally, you can configure your physical destinations as part of a single distributed destination set within a cluster. For more information, see "Distributed Destination Tasks" in the Administration Console Online Help.

What About Failover?

For WebLogic JMS implementations that are part of a WebLogic 7.0 clustered environment, JMS offers service continuity in the event of a single Weblogic Server failure by enabling you to configure multiple physical destinations (queues and topics) as part of a single distributed destination set. In addition, implementing the Migratable Service feature, will ensure that pinned "exactly-once" services, like JMS, do not introduce a single point of failure for dependent applications in the cluster,

However, automatic failover is not currently supported by WebLogic JMS. For information about performing a manual failover, refer to Recovering from a WebLogic Server Failure.

 

---

Configuring JMS Migratable Targets

As an "exactly-once" service, WebLogic JMS is not active on all WebLogic Server instances in a cluster. It is instead "pinned" to a single server in the cluster to preserve data consistency. To ensure that pinned services do not introduce a single point of failure for dependent applications in the cluster, WebLogic Server can be configured to migrate exactly-once services to any server in the migratable target list.

WebLogic JMS takes advantage of the migration framework by allowing an administrator to specify a migratable target for a JMS server in the Administration Console. Once properly configured, a JMS server and all of its destinations can migrate to another WebLogic Server within a cluster.

This allows WebLogic JMS to properly respond to migration requests and bring a JMS server online and offline in an orderly fashion. This includes both scheduled migrations as well as migrations in response to a WebLogic Server failure with the cluster.

For more information about defining migratable targets, see "Migration for Pinned Services" in Using WebLogic Server Clusters.

How JMS Migration Works

For implementations that are part of a WebLogic clustered environment, WebLogic JMS implements the weblogic.cluster.Migratable interface, which allows JMS servers to respond to activate and deactivate requests.

Table 3-1 WebLogic JMS Migration Process

Migration state...	What takes place...
Initialization	Initialization of a JMS server includes processing any configuration or deployment information and creating the appropriate objects. Destinations and other JMS resources are unavailable at this time. In addition, the persistent store is not opened, as this could compromise the integrity of the store. The JMS server makes itself available to handle changes in configuration that may occur between initialization and activation.
Activation	When a JMS server is activated, it opens the persistent store, performs any necessary recovery, reconciles the contents of the store with the current configuration, and makes the destinations available for access by applications. In addition, any configured server session pools begin processing after activation is complete.
Deactivation	When a JMS server is deactivated it stops all server session pool processing, marks all destinations as unavailable, flushes and closes its persistent stores, purges its destinations, and deletes all objects for the JMS server.

Configuration Steps

In order to make WebLogic JMS a migratable service in a clustered environment, you must do the following:

1. Administer WebLogic clusters as described in "Configuring WebLogic Servers and Clusters" in the Using WebLogic Server Clusters.
2. Configure a migratable target for the cluster as described in "Server -> Control -> JMS Migration Config. -> " in the Administration Console Online Help.
3. Identify a migratable target server on which to deploy a JMS server as described in "JMS Server Tasks" in the Administration Console Online Help.

   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 WebLogic Server failure or due to a scheduled migration for maintenance.

   Note: A JMS server and all of its destination members can migrate to another WebLogic Server within a cluster—even when the target WebLogic Server is already hosting a JMS server with all of its destination members. Although this can lead to situations where the same WebLogic server hosts two physical destinations for a single distributed destination, this is permissible in the short term, since the WebLogic Server can host multiple physical destinations for that distributed destination. For more information about JMS distributed destinations, see Using Distributed Destinations.

4. For implementations that use persistent messaging, make sure that the persistent store is configured such that all the candidate servers in a migratable target share access to a persistent store. For more information about migrating persistent stores, see Persistent Store Migration.
5. The administrator can manually migrate services before performing server maintenance or to a healthy server if the host server fails.

Persistent Store Migration

Weblogic JMS persistent stores cannot be migrated along with JMS servers; therefore, applications that need access to persistent stores from other physical machines after the migration of a JMS server must implement an alternative solution, as follows:

• Implement a hardware solution, such as a dual-ported SCSI disk or Storage Area Network (SAN) to make your JMS persistent store available from other machines.
• Use JDBC to access your JMS JDBC store, which can be on yet another server. Applications can then take advantage of any high-availability or failover solutions offered by your database vendor.

For more information about configuring a JMS JDBC store, see "Configuring JDBC Stores" in the Administration Console Online Help.

Migration Failover

For information about procedures for recovering from a WebLogic Server failure, see Recovering from a WebLogic Server Failure.

 

---

Tuning WebLogic JMS

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

• Synchronous Write Policies for JMS File Stores—disabling synchronous writes improves file store performance, often quite dramatically, but at the expense of possibly losing sent messages or generating duplicate received messages in the event of an operating system crash or a hardware failure.

For more information, see "Configuring a Synchronous Write Policy for JMS File Stores" in the Administration Console Online Help.

• Using Message Paging—you can free up valuable virtual memory during peak message load periods by swapping out messages from memory to persistent storage whenever your message loads reach a specified threshold. From a performance perspective, this feature can greatly benefit WebLogic Server implementations with the large message spaces that are required by today's enterprise applications.

For more information, see "Using Message Paging" in the Administration Console Online Help.

• Establishing Message Flow Control—a JMS server or JMS destination (queue or topic) can be configured to instruct message producers to limit their message flow when it determines that it is becoming overloaded.

For more information, see "Establishing Message Flow Control" in the Administration Console Online Help.

• Avoiding Quota Exceptions by Block Message Producers—the "Blocking Send" features 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.

For more information, see "Avoiding Quota Exceptions by Blocking Message Producers" in the Administration Console Online Help.

• Active Expired Message Handling—active message expiration ensures that expired messages are cleaned up immediately. Moreover, expired message auditing gives you the option of tracking expired messages, either by logging when a message expires or by redirecting expired messages to a special destination.

For more information, see "Handling Expired Messages" in the Administration Console Online Help.

• Tuning Distributed Destinations—the following attributes on the JMS Connection Factory can be configured to tune your distributed destinations:
• Load Balancing—defines whether WebLogic JMS will spread or balance the messaging load across distributed destinations.
• Server Affinity—defines whether a WebLogic Server that is attempting to load balance consumers or producers across multiple physical destinations in a distributed destination set, will first attempt to load balance across those physical destinations being served by any JMS servers that are also running on the same WebLogic Server.

For more information, see "Tuning Distributed Destinations" in the Administration Console Online Help.

 

---

Monitoring WebLogic JMS

Statistics are provided for the following JMS objects: JMS servers, connections, sessions, destinations, durable subscribers, message producers, message consumers, and server session pools. You can monitor JMS statistics using the Administration Console.

JMS statistics continue to increment as long as the server is running. Statistics can only be reset when the server is rebooted. For more information on configuring and monitoring WebLogic JMS, see "Monitoring JMS" in the Administration Console Online Help.

Once WebLogic JMS has been configured, applications can begin sending and receiving messages through the JMS API, as described in Developing a WebLogic JMS Application.

 

---

Recovering from a WebLogic Server Failure

The following sections describe how to terminate a JMS application gracefully if a server fails and how to migrate JMS data after server failure.

Programming Considerations

You may want to program your JMS application to terminate gracefully in the event of a WebLogic Server failure. For example:

If a WebLogic Server Instance Fails and...	Then...
You are connected to the failed WebLogic Server instance	A JMSException is delivered to the connection exception listener. You must restart the application once the server is restarted or replaced.
You are not connected to the failed WebLogic Server instance	You must re-establish everything once the server is restarted or replaced.
A JMS Server is targeted on the failed WebLogic Server instance	A ConsumerClosedException is delivered to the session exception listener. You must re-establish any message consumers that have been lost.

 

Migrating JMS Data to a New Server

WebLogic JMS uses the migration framework implemented in the WebLogic Server core, which allows WebLogic JMS to properly respond to migration requests and bring a WebLogic JMS server online and offline in an orderly fashion. This includes both scheduled migrations as well as migrations in response to a WebLogic Server failure.

Once properly configured, a JMS server and all of its destination members can migrate to another WebLogic Server within a cluster.

You can recover JMS data from a failed WebLogic Server by starting a new server and doing one or more of the tasks in Table 3-2.

Note: There are special considerations when you migrate a service from a server instance that has crashed or is unavailable to the Administration Server. If the Administration Server cannot reach the previously active host of the service at the time you perform the migration, see "Migrating a Service When Currently Active Host is Unavailable".

Table 3-2 Migration Task Guide

If your JMS application uses. . .	Perform the following task. . .
Persistent messaging—JDBC Store	If the JDBC database store physically exists on the failed server, migrate the database to a new server and ensure that the JDBC connection pool URL attribute reflects the appropriate location reference. If the JDBC database does not physically exist on the failed server, access to the database has not been impacted, and no changes are required.
Persistent messaging—File Store	Migrate the file to the new server, ensuring that the pathname within the WebLogic Server home directory is the same as it was on the original server.
Transactions	Migrate the transaction log to the new server by copying all files named <servername>*.tlog. This can be accomplished by storing the transaction log files on a dual-ported disk that can be mounted on either machine, or by manually copying the files. If the files are located in a different directory on the new server, update that server's TransactionLogFilePrefix server configuration attribute before starting the new server. Note: If migrating following a system crash, it is very important that the transaction log files be available when the server is restarted at its new location. Otherwise, transactions in the process of being committed at the time of the crash might not be resolved correctly, resulting in data inconsistencies. All uncommitted transactions are rolled back.

Note: JMS persistent stores can increase the amount of memory required during initialization of WebLogic Server as the number of stored messages increases. When rebooting WebLogic Server, if initialization fails due to insufficient memory, increase the heap size of the Java Virtual Machine (JVM) proportionally to the number of messages that are currently stored in the JMS persistent store and try the reboot again.

For information about starting a new WebLogic Server, refer to see "Starting and Stopping Servers" in the Administration Console Online Help. For information about recovering a failed server, refer to Recovering Failed Servers in the Configuring and Managing WebLogic Domains guide.

For more information about migratable targets, see "Configuring WebLogic Migratable Services" in Using WebLogic Server Clusters.