Managing JMS

 

This section explains how to manage WebLogic JMS, describing the following topics:

• Configuring JMS

• Monitoring JMS

• Recovering From a WebLogic Server Failure

Configuring JMS

Using the Administration Console, you define configuration attributes to:

• Enable JMS.

• Create JMS servers.

• Create and/or customize values for JMS servers, connection factories, destinations (queues and topics), destination templates, destination keys, backing stores, session pools, and connection consumers.

• Set up custom JMS applications.

• Define thresholds and quotas.

• Enable any desired JMS features, such as server clustering (see the next section), concurrent message processing, destination sort ordering, and persistent messaging.

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, the WebLogic Server will not boot JMS when you restart it. A sample JMS configuration is provided with the product.

When migrating from a previous release, the configuration information will be converted automatically, as described in "Migrating Existing Applications" in Programming WebLogic JMS.

To configure WebLogic JMS attributes, perform the following steps:

1. Start the Administration Console.

2. Select the JMS button under Services in the left pane to expand the list.

3. Follow the procedures described in the following sections, or in the Administration Console Online Help, to create and configure the JMS objects.

Once WebLogic JMS is configured, applications can begin sending and receiving messages using the JMS API. For more information about developing WebLogic JMS applications, see "Developing a WebLogic JMS Application" in Programming WebLogic JMS.

Note: To assist with your WebLogic JMS configuration planning, Programming WebLogic JMS provides configuration checklists that enable you to view the attribute requirements and/or options that support various JMS features.

Configuring Connection Factories

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. You define and configure one or more connection factories to create connections with predefined attributes. 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 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. For more information on JMS clustering, refer to "WebLogic JMS Fundamentals"in Programming WebLogic JMS.

To configure connection factories, use the Connection Factories node in the Administration Console to define the following:

• Configuration attributes including:

  • Name of the connection factory

  • Name for accessing the connection factory within the JNDI namespace

  • Client identifier (client ID) that can be used for clients with durable subscribers. For more information about durable subscribers, see "Developing a WebLogic JMS Application" in Programming WebLogic JMS.

  • Default message delivery attributes (that is, priority, time-to-live, and mode)

  • 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).

  • Whether or not the close() method is allowed to be called from the onMessage() method.

  • Transaction attributes (transaction time-out and whether or not JTA user transactions are allowed)

• Targets (WebLogic Servers) that are associated with a connection factory to support clustering. Targets enable you to limit the set of servers, groups, and/or clusters on which a connection factory may be deployed.

WebLogic JMS defines one connection factory, by default: weblogic.jms.ConnectionFactory. All configuration attributes are set to their default values for this default connection factory, as described in "JMS Connection Factories" in the Administration Console Online Help.

If the default connection factory definition is appropriate for your application, you do not need to configure any additional connection factories for your application.

Note: Using the default connection factory, you have no control over the JMS server on which the connection factory may be deployed. If you would like to target a particular JMS server, create a new connection factory and specify the appropriate JMS server target(s).

For instructions on creating and configuring a connection factory, see "JMS Connection Factories" in the Administration Console Online Help.

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 Templates

Templates provide an efficient way to define multiple destinations with similar attribute settings. 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 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.

To define the destination template configuration attributes, use the Templates node in the Administration Console. The configurable attributes for a destination 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 template specifies an override value for an attribute, the override value is used.

• The Name attribute is not inherited by the destination. This name is valid for the template only. All destinations must explicitly define a unique name.

• The JNDI Name, Enable Store, and Template attributes are not defined for destination templates.

• The Multicast attributes are not defined for destination templates because they apply only to topics.

Any attributes that are not explicitly defined for a destination are assigned default values. If no default value exists, then you must be sure to specify a value within the destination 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.

For instructions on creating and configuring a template, see "JMS Templates" in the Administration Console Online Help.

Configuring Destination Keys

Destination keys are used to define the sort order for a specific destination.

To create a destination key, use the Destination Keys node in the Administration Console and define the following configuration attributes:

• Name of the destination key

• Property name on which to sort

• Expected key type

• Direction in which to sort (ascending or descending)

For instructions on creating and configuring a destination key, see "JMS Destination Keys" in the Administration Console Online Help.

Configuring Stores

The backing store consists of a file or database that is used for persistent messaging.

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 supports and provides JDBC drivers for the following databases:

• Cloudscape

• Informix

• Microsoft SQL (MSSQL) Server (Versions 6.5 and 7)

• Oracle (Version 8.1.6)

• Sybase (Version 12)

Optionally, you can restrict the access control list (ACL) for the JDBC connection pool. If you restrict this ACL, you must include the WebLogic system user and any user who sends JMS messages in the list. For more information, see "Managing Security" in the Administration Guide.

Note: The JMS examples are set up to work with the Cloudscape Java database. An evaluation version of Cloudscape is included with WebLogic Server and a demoPool database is provided.

To create a file or database store, use the Stores node in the Administration Console and define the following configuration attributes:

• Name of the backing store

• (For a file store) Directory within which file stores will be saved

• (For a JDBC database store) JDBC connection pool and database table name prefix for use with multiple instances

  Warning: You cannot configure a XA connection pool with a JDBC database store.

  Note: JMS backing stores can increase the amount of memory required during initialization of a WebLogic Server as the number of stored messages increases. If initialization fails due to insufficient memory when you are rebooting a 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 backing store. Try rebooting again.

About JMS Stores

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

• <prefix>JMSStore

• <prefix>JMSState

The prefix name uniquely identifies JMS tables in the backing store. Specifying unique prefixes allows multiple stores to exist in the same database. The prefix is configured via the Administration Console when configuring the JDBC store. A prefix is prepended to table names when the DBMS requires fully qualified names, or when you must differentiate between JMS tables for two WebLogic servers, enabling multiple tables to be stored on a single DBMS.

The prefix should be specified using the following format, which will result in a valid table name when prepended to the JMS table name:

[[catalog.]schema.]prefix

Warning: No two JMS stores should be allowed to use the same database tables, as this will result in data corruption.

For instructions on creating and configuring a store, see "JMS File Stores" and "JMS JDBC Stores" for information about file and JDBC database stores, respectively, in the Administration Console Online Help.

Recommended JDBC Connection Pool Settings for JMS Stores

For implementations using a JDBC store, if the DBMS should shut down and then come back online, WebLogic JMS will not be able to access the store until WebLogic Server is shutdown and restarted. To avoid this situation, you should configure the following attributes on the JDBC Connection Pool associated with the JMS store:

TestConnectionsOnReserve="true"
TestTableName="[[[catalog.]schema.]prefix]JMSState"

Otherwise, if the JDBC resource goes down and comes back up, JMS cannot re-use it until the WebLogic Server is shutdown and restarted.

Configuring JMS Servers

A JMS server manages connections and message requests on behalf of clients.

To create a JMS server, use the Servers node in the Administration Console and define the following:

• Configuration attributes including:

  • Name of the JMS server.

  • Backing store (file or JDBC database) required for persistent messaging. If you do not assign a backing store for a JMS server, persistent messaging is not supported on that server.

  • Template that is used to create all temporary destinations, including temporary queues and temporary topics.

  • Thresholds and quotas for messages and bytes (maximum number, and high and low thresholds).

• Targets (WebLogic Servers) that are associated with a JMS server to support clustering. Targets enable you to limit the set of servers, groups, and/or clusters on which the JMS server may be deployed.

  Note: The deployment of a JMS server differs from that of a connection factory or template. A JMS server is deployed on a single server. A connection factory or template can be instantiated on multiple servers simultaneously.

For instructions on creating and configuring a JMS server, see "JMS Servers" in the Administration Console Online Help.

Configuring Destinations

A destination identifies a queue or topic. Once you have defined a JMS server, you can configure its destinations. You can configure one or more destinations for each JMS server.

You can configure destinations explicitly or by configuring a destination template that can be used to define multiple destinations with similar attribute settings, as described in Configuring Templates.

To configure destinations explicitly, use the Destinations node in the Administration Console, and define the following configuration attributes:

• Name and type (queue or topic) of the destination

• Name for accessing the destination within the JNDI namespace

• Whether or not a store is enabled for storing persistent messages

• Template used for creating destinations

• Keys used to define the sort order for a specific destination

• Thresholds and quotas for messages and bytes (maximum number, and high and low thresholds)

• Message attributes that can be overridden (such as priority, time-to-live, and delivery mode)

• Multicasting attributes, including multicast address, port, and time-to-live (for topics only)

For instructions on creating and configuring a destination, see "JMS Destinations" in the Administration Console Online Help.

Some destination attributes are dynamically configurable. When attributes are modified at run time, only incoming messages are affected; stored messages are not affected.

Configuring Session Pools

Server session pools enable an application to process messages concurrently. Once you have defined a JMS server, you have the option of configuring its server session pools. You can configure one or more session pools for each JMS server.

To configure server session pools, use the Session Pools node in the Administration Console and define the following configuration attributes:

• Name of the server session pool

• Connection factory with which the server session pool is associated and is used to create sessions

• Message listener class used to receive and process messages concurrently

• Transaction attributes (acknowledge mode and whether or not the session pool creates transacted sessions)

• Maximum number of concurrent sessions

For instructions on creating and configuring a session pool, see "JMS Session Pools" in the Administration Console Online Help.

Some session pool attributes are dynamically configurable, but the new values do not take effect until the session pools are restarted.

Configuring Connection Consumers

Connection consumers retrieve server sessions and process messages. Once you have defined a session pool, you have the option of configuring its connection consumers. You can configure one or more connection consumers for each session pool.

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

• Name of the connection consumer

• Maximum number of messages that can be accumulated by the connection consumer

• JMS selector expression used to filter messages. For information about defining selectors, see "Developing a WebLogic JMS Application" in Programming WebLogic JMS.

• Destination on which the connection consumer will listen.

To create and configure a connection consumer, and for detailed information about each of the connection consumer configuration attributes, see "JMS Connection Consumers" in the Administration Console Online Help.

Monitoring JMS

Statistics are provided for the following JMS objects: JMS servers, connections, sessions, destinations, 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 be reset only when the server is rebooted.

To view JMS monitoring information, perform the following steps:

1. Start the Administration Console.

2. Select the JMS node under Services, in the left pane, to expand the list of JMS services.

3. Select the JMS Server node under JMS in the left pane.

   The JMS Servers information is displayed in the right pane.

4. Select the JMS server that you want to monitor from the JMS server list or, from the JMS Servers displayed in the right pane.

   The specified JMS server information is displayed in the right pane.

5. Select the Monitoring tab to display the monitoring data.

For detailed information about the information being monitored, see the Administration Console Online Help.

Recovering From a WebLogic Server Failure

The following sections describe how to restart or replace a WebLogic Server in the event of a system failure, and provide programming considerations for gracefully terminating an application following such an event.

Restarting or Replacing the WebLogic Server

In the event that a WebLogic Server fails, there are three methods that you can use to perform a system recovery:

• Restart the failed server

• Start up a new server using the same IP address as the failed server

• Start up a new server using a different IP address than the failed server

To restart the failed server or start up a new server using the same IP address as the failed server, boot the server and start the server processes, as described in Starting and Stopping WebLogic Servers in the Administration Guide.

To start up a new server using a different IP address than the failed server:

1. Update the Domain Name Service (DNS) so that the server alias references the new IP address.

2. Boot the server and start the server processes, as described in Starting and Stopping WebLogic Servers in the Administration Guide.

3. Optionally perform one or more of the following tasks

   If your 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 re-started at its new location. Otherwise, transactions in the process of being committed at that time of the crash might not be resolved correctly, resulting in data inconsistencies. All uncommitted transactions will be rolled back.

   Note: JMS backing stores can increase the amount of memory required during initialization of a WebLogic Server as the number of stored messages increases. When rebooting a 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 backing store and try the reboot again.

Programming Considerations

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

If a WebLogic Server Fails and...	Then...
You are connected to the failed WebLogic Server	A JMSException will be 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	You must re-establish everything once the server is restarted or replaced.
A JMS Server is targeted on the failed WebLogic Server	A ConsumerClosedException will be delivered to the session exception listener. You must re-establish any message consumers that may have been lost.