Managing JMS

 

The following sections explain how to manage the Java Message Service (JMS) for WebLogic Server:

• JMS and WebLogic Server

• Configuring JMS

• Monitoring JMS

• Tuning JMS

• Recovering from a WebLogic Server Failure

 

---

JMS and WebLogic Server

JMS 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 17-1 WebLogic Server JMS Messaging

 

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

 

---

Configuring JMS

Using the Administration Console, you define configuration attributes to:

• Enable JMS.

• Create JMS servers and target a WebLogic server instance.

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

• Set up custom JMS applications.

• Define thresholds and quotas.

• Enable any desired JMS features, such as server clustering, concurrent message processing, destination sort ordering, persistent messaging, and message paging.

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 Installation Guide.

When you migrate WebLogic Server applications 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, 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 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, and connection factories.

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.

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 WebLogic Servers.

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 Administration Console.

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 JMSFile 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 stores, see Configuring Stores.

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 Targets tab, target a WebLogic Server instance or a server cluster on which to deploy the connection pool by selecting either the Servers tab or the Clusters tab. Select a target by moving it from the Available list into the Chosen List, and then click Apply.

   5. Return to the JMS -> Stores node, and then click the Configure a new JMSJDBCStore 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 connection pools, see Configuring and Managing JDBC Connection Pools, MultiPools, and DataSources Using the Administration Console.

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, 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 Configuring JMS Templates.

5. Configure a JMS Server, as follows:

   1. Click the Server node in the left pane, and then click the Configure a new JMSServer 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 Targets tab, select a WebLogic Server instance on which to deploy the JMS server by moving it from the Available list into the Chosen List, and then clicking Apply.

      Note: For more information on configuring a JMS Server, see Configuring JMS Servers.

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 JMSQueue or Configure a new JMSTopic 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, and Multicast (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 Configuring Destinations.

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 tab, as appropriate. Click Apply when you're done making changes.

   4. On the Targets tab, target a WebLogic Server instance or a server cluster on which to deploy the connection factory by selecting either the Servers tab or the Clusters tab. Select a target by moving it from the Available list into the Chosen List, and then click Apply.

      Note: For more information on configuring a Connection Factory, see Configuring Connection Factories.

8. Optionally, use the Destination Keys node to define the sort order for a specific destination. For more information, see Configuring Destination Keys.

9. 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 Configuring Session Pools and Configuring Connection Consumers.

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:

• General configuration attributes, including:

  • Name of the JMS server.

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

  • Paging store (file recommended) required for paging. If you do not assign a paging store for a JMS server, paging is not support on that server.

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

    Note: JMS servers must be uniquely named within a domain. For more information, see JMS Configuration Naming Rules.

• Thresholds and quotas for messages and bytes (maximum number, and high and low thresholds), and whether or not bytes paging and/or messages paging is enabled.

• Target a WebLogic Server instance that is associated with a JMS server. When the target WebLogic Server boots, the JMS server boots as well. If no target WebLogic Server is specified, the JMS server will not boot.

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 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:

• General 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, time-to-deliver, 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.

  • Whether all messages or only previously received messages are acknowledged.

    JMS connection factories must be uniquely named within a domain. For more information, see JMS Configuration Naming Rules.

• Transaction attributes—transaction time-out, whether or not Java Transaction API (JTA) user transactions are allowed, and whether or not a transaction (XA) queue or XA topic connection factory is returned.

• Targets (WebLogic Server instances) 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. 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 Destinations

A destination identifies a queue (Point-To-Point) or a topic (Pub/Sub) for a JMS server. After defining a JMS server, configure one or more destination 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 Configuring JMS Templates.

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

• General configuration attributes, including:

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

  • The JMS template used for creating destinations.

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

    Note: JMS destinations have unique naming restrictions within a domain. For more information, see JMS Configuration Naming Rules.

• Thresholds and quotas for messages and bytes (maximum number, and high and low thresholds), and whether or not bytes paging and/or messages paging is enabled on the destination.

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

• Message redelivery attributes, including redelivery delay override, redelivery limit, and error destination.

• Multicasting attributes, including multicast address, time-to-live (TTL), and port (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 JMS Templates

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.

To define the JMS template configuration attributes for destinations, use the Templates node in the Administration Console. 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.

  Note: JMS templates have unique naming restrictions within a domain. 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 topics.

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.

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

Configuring Destination Keys

Use destination keys 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 persistent store consists of a file or database that is used for persistent messaging. To create a file or database store, use the Stores node in the Administration Console and define the following configuration attributes:

• Name of the JMS persistent store.

• For a JMS file store—provide the path to the location where the messages will be saved.

• For a JMS JDBC database store—provide the JDBC connection pool and database table name prefix for use with multiple instances.

  Note: JMS stores have unique naming restrictions within a domain. For more information, see JMS Configuration Naming Rules.

Warning: You cannot configure a transaction (XA) connection pool to be used with a JDBC database store For more information, see JMS JDBC Transactions.

JMS persistent 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 when you are 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 persistent 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.

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.

About JMS JDBC Stores

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: The JMS samples provided with your WebLogic Server distribution 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.

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.

JMS JDBC Transactions

You cannot configure a transaction (XA) JDBC connection pool to be used with a JMS JDBC store. JMS must use a JDBC connection pool that uses a non-XAResource driver (you cannot use an XA driver or a JTS driver). 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.

JMS JDBC Security

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

About JMS Store Table Prefixes

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

• <prefix>JMSStore

• <prefix>JMSState

The prefix name uniquely identifies JMS tables in the persistent store. Specifying unique prefixes allows multiple stores to exist in the same database. You configure the prefix 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.

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 Stores

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"

Configuring Session Pools

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.

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

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

Using the Administration Console, you can monitor statistics for the following JMS objects: JMS servers, connections, sessions, destinations, message producers, message consumers, server session pools, and durable subscribers.

JMS statistics continue to increment as long as the server is running. Statistics are reset only when the server is rebooted.

Note: For instructions on monitoring JMS connections to WebLogic Server, refer to the Server section in the Administration Console Online Help.

Monitoring JMS Objects

To view JMS monitoring information:

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.

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

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

Monitoring Durable Subscribers

To view JMS durable subscribers that are running on destination topics:

1. Follow steps 1-3, as described in Monitoring JMS Objects.

2. Select the Destinations node under Servers in the left pane, to expand the list of JMS topic and queue destinations.

   The JMS destination information is displayed in a table format in the right pane, with the Durable Subscriber Runtimes column listing the number of durable subscribers running (if any) for the destination topics listed in the table.

3. To view durable subscriber information for a specific topic, click the icon (or actual number) in the Durable Subscriber Runtimes column for the desired topic.

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

 

---

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

• Persistent Stores

• Using Message Paging

Persistent Stores

The following sections describe the tuning options available when using persistent stores with WebLogic Server JMS.

Disabling Synchronous Writes to File Stores

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

Note: At least one JMS vendor disables synchronous writes by default, and this vendor only allows enabling synchronous writes for sends and not for receives.

To disable synchronous writes for all JMS file stores running on a WebLogic server set the following command-line property:

-Dweblogic.JMSFileStore.SynchronousWritesEnabled=false

To disable synchronous writes for a particular JMS file store:

-Dweblogic.JMSFileStore.store-name.SynchronousWritesEnabled=false 

If both properties are set, the latter command overrides the former. A log message is generated when synchronous writes are disabled. This can be used to verify that the command-line property is taking effect.

Using Message Paging

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

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

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

IConfiguring Paging

Unless paging is configured and enabled, all messages (even persistent ones) are held in memory. You can configure paging for a new or existing JMS server and/or its destinations through the Administration Console. Using the attributes on the JMS Server node you can specify a paging store for a JMS server, enable bytes and/or messages paging, and configure bytes/messages high and low thresholds to start and stop paging.

Similarly, using the attributes on the Destinations node, you can configure bytes/messages paging for all topics and queues configured on a JMS server. The destinations use the paging store that is configured for the JMS server.

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

For instructions on configuring a new JMS server, templates, and destinations (Topics or Queues), see "JMS Servers," "JMS Destinations," and "JMS Templates" in the Administration Console Online Help.

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

Configuring a Paging Store for a JMS Server

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

To configure a new paging store:

1. Start the Administration Console.

2. Click the JMS Store node. The right pane shows all the JMS stores.

3. Click the Create a new JMS File Store text link. The right pane shows the tabs associated with configuring a new file store.

4. Enter values in the attribute fields.

5. Click Create to create a file store instance with the name you specified in the Name field. The new instance is added under the JMS Stores node in the left pane.

6. If you have multiple JMS servers in your domain, repeat steps 3-5 for each server instance.

Configuring Paging on a JMS Server

To enable and configure paging on an existing JMS server:

1. Click the JMS Servers node. The right pane shows all the servers defined in your domain.

2. Click the server that you want to configure for paging. The right pane shows the tabs associated with configuring the server.

3. On the General tab, use the Paging Store list box to select the store that you configured to store the paged messages. Click Apply to save your changes.

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

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

   • Select the Bytes Paging Enabled check box.

   • In the Bytes Threshold High field, enter an amount that will start bytes paging when the number of bytes on the JMS server exceeds this threshold.

   • In the Bytes Threshold Low field, enter an amount that will stop bytes paging once the number of bytes on the JMS server falls below this threshold.

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

   • Select the Messages Paging Enabled check box.

   • In the Messages Threshold High field, enter an amount that will start messages paging when the number of messages on the JMS server exceeds this threshold.

   • In the Messages Threshold Low field, enter an amount that will stop messages paging once the number of messages on the JMS server falls below this threshold.

6. Click Apply to save the new bytes and/or messages paging values.

7. Repeat steps 2-6 to configure paging for additional JMS servers in the domain.

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

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

   • If you are not configuring a JMS server's destinations for paging, reboot WebLogic Server to activate paging.

   • If you want to configure a server's destinations for paging, follow refer to either Configuring Paging on a JMS Template or Configuring Paging on Destinations.

Configuring Paging on a JMS Template

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

1. Click the JMS node in the left pane.

2. Click the JMS Templates node. The right pane shows all the templates defined in the domain.

3. Click the template that you want to configure for paging. The right pane shows the tabs associated with configuring the template.

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

   • Select the Bytes Paging Enabled check box.

   • In the Bytes Threshold High field, enter an amount that will start bytes paging when the number of bytes on the JMS server exceeds this threshold.

   • In the Bytes Threshold Low field, enter an amount that will stop bytes paging once the number of bytes on the JMS server falls below this threshold.

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

   • Select the Messages Paging Enabled check box.

   • In the Messages Threshold High field, enter an amount that will start messages paging when the number of messages on the JMS server exceeds this threshold.

   • In the Messages Threshold Low field, enter an amount that will stop messages paging once the number of messages on the JMS server falls below this threshold.

6. Click Apply to save the new bytes and/or messages paging values.

7. Repeat steps 3-5 to configure paging for additional JMS templates.

8. After configuring all of your JMS templates for paging, reboot WebLogic Server to activate paging.

Configuring Paging on Destinations

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

1. Under JMS Servers, click to expand a server instance that is already configured for paging.

2. Click the Destinations node. The right pane shows all of the server's topics and queues.

3. Click the topic or queue that you want to configure for paging. The right pane shows the tabs associated with configuring the topic or queue.

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

   • Select the Bytes Paging Enabled check box.

   • In the Bytes Threshold High field, enter an amount that will start bytes paging when the number of bytes on the JMS server exceeds this threshold.

   • In the Bytes Threshold Low field, enter an amount that will stop bytes paging once the number of bytes on the JMS server falls below this threshold.

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

   • Select the Messages Paging Enabled check box.

   • In the Messages Threshold High field, enter an amount that will start messages paging when the number of messages on the JMS server exceeds this threshold.

   • In the Messages Threshold Low field, enter an amount that will stop messages paging once the number of messages on the JMS server falls below this threshold.

6. Click Apply to save the new bytes and/or messages paging values.

7. Repeat steps 3-5 to configure paging for additional JMS destinations.

8. After you configure all your destinations for paging, reboot WebLogic Server to activate paging.

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

Configuring a Destination to Override Paging on a JMS Template

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

1. Under JMS Servers, click to expand a server instance that is already configured for paging.

2. Click the Destinations node. The right pane shows all of the server's topics and queues.

3. Click the topic or queue that you want to configure for paging. The right pane shows the topics or queues associated with the server instance.

4. On the Thresholds & Quotas tab, configure the Bytes Paging Enabled and/or Messages Paging Enabled attributes on the destination according to how you want to override the JMS template for the destination.

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

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

5. Click Apply to save the new bytes and/or messages paging values.

6. Repeat steps 2-5 to configure paging for additional JMS destinations on the same server instance.

7. Once all of your destinations are configured for paging, then reboot WebLogic Server to activate paging.

JMS Paging Attributes

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

JMS Server Paging Attributes

Table  17-1 describes the paging attributes that you define when configuring paging on a JMS Server. For detailed information about other JMS Server attributes, and the valid and default values for them, see "JMS Servers" in the Administration Console Online Help.

Table 17-1 JMS Server Attributes

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

JMS Template Paging Attributes

Table  17-3 describes the paging attributes that you define when configuring paging on JMS templates for destinations. For detailed information about other JMS template attributes, and the valid and default values for them, see "JMS Templates" in the Administration Console Online Help.

Table 17-2 JMS Template Attributes

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

JMS Destination Paging Attributes

Table  17-3 describes the attributes that you define when configuring paging on destinations. For detailed information about other JMS destination attributes, and valid and default values for them, see "JMS Destinations" in the Administration Console Online Help.

Table 17-3 JMS Destination Attributes

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

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

Paging Threshold Attributes

Table  17-4 briefly describes the bytes and messages paging thresholds available with JMS servers, templates, and destinations. For detailed information about other JMS server, template, and destination attributes, and the valid and default values for them, see "JMS Servers," "JMS Destinations," and "JMS Templates" in the Administration Console Online Help.

Table 17-4 Paging Threshold Attributes

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

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

• If either bytes high/low threshold value is not defined (or is defined as -1), then the number of bytes is not used to determine when and what to page.

• If either messages high/low threshold value is not defined (or is defined as -1), then the number of messages is not used to determine when and what to page.

• A server or template/destination must have the Bytes/Messages Paging Enabled attribute set to True in order for paging to take place. If the thresholds are set, but paging is not enabled, messages are still logged on the server indicating threshold conditions.

 

---

Recovering from a WebLogic Server Failure

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

Restarting or Replacing WebLogic Server

When a WebLogic Server fails, you can use one of three methods to perform a system recovery:

• Restart the failed server instance.

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

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

To restart the failed server instance or start up a new server instance 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.

To start up a new server instance 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

3. Optionally, perform one or more of the tasks listed in the following table:

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.

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 Fails and...	Then...
You are connected to the failed WebLogic Server instance	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 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 will be delivered to the session exception listener. You must re-establish any message consumers that may have been lost.