10 Troubleshooting WebLogic JMS

This chapter provides information on how to troubleshoot WebLogic JMS messages and configurations.

For more information on monitoring JMS statistics and managing JMS messages, see Chapter 8, "Monitoring JMS Statistics and Managing Messages."

Configuring Notifications for JMS

A notification is an action that is triggered when a watch rule evaluates to true. JMS notifications are used to post messages to JMS topics and/or queues in response to the triggering of an associated watch. In the system resource configuration file, the elements <destination-jndi-name> and <connection-factory-jndi-name> define how the message is to be delivered.

For more information, see "Configuring Notifications" in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

Debugging JMS

Once you have narrowed the problem down to a specific application, you can activate WebLogic Server's debugging features to track down the specific problem within the application.

Enabling Debugging

You can enable debugging by setting the appropriate ServerDebug configuration attribute to true. Optionally, you can also set the server StdoutSeverity to Debug.

You can modify the configuration attribute in any of the following ways.

Enable Debugging Using the Command Line

Set the appropriate properties on the command line. For example,

-Dweblogic.debug.DebugJMSBackEnd=true 
-Dweblogic.log.StdoutSeverity="Debug"

This method is static and can only be used at server startup.

Enable Debugging Using the WebLogic Server Administration Console

Use the WebLogic Server Administration Console to set the debugging values:

  1. If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit (see "Using the Change Center" in Introduction to Oracle WebLogic Server).

  2. In the left pane of the console, expand Environment and select Servers.

  3. On the Summary of Servers page, click the server on which you want to enable or disable debugging to open the settings page for that server.

  4. Click Debug.

  5. Expand default.

  6. Select the check box for the debug scopes or attributes you want to modify.

  7. Select Enable to enable (or Disable to disable) the debug scopes or attributes you have checked.

  8. To activate these changes, in the Change Center of the Administration Console, click Activate Changes.

    Not all changes take effect immediately—some require a restart (see "Using the Change Center" in Introduction to Oracle WebLogic Server).

    This method is dynamic and can be used to enable debugging while the server is running.

Enable Debugging Using the WebLogic Scripting Tool

Use the WebLogic Scripting Tool (WLST) to set the debugging values. For example, the following command runs a program for setting debugging values called debug.py:

java weblogic.WLST debug.py

The main scope, weblogic, does not appear in the graphic; jms is a sub-scope within weblogic. Note that the fully-qualified DebugScope for DebugJMSBackEnd is weblogic.jms.backend.

The debug.py program contains the following code:

user='user1'
password='password'
url='t3://localhost:7001'
connect(user, password, url)
edit()
cd('Servers/myserver/ServerDebug/myserver')
startEdit()
set('DebugJMSBackEnd','true')
save()
activate()

Note that you can also use WLST from Java. The following example shows a Java file used to set debugging values:

import weblogic.management.scripting.utils.WLSTInterpreter;
import java.io.*;
import weblogic.jndi.Environment;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

public class test {
        public static void main(String args[]) {
       try {
              WLSTInterpreter interpreter = null;
              String user="user1";
              String pass="pw12ab";
              String url ="t3://localhost:7001";
              Environment env = new Environment();
              env.setProviderUrl(url);
              env.setSecurityPrincipal(user);
              env.setSecurityCredentials(pass);
              Context ctx = env.getInitialContext();

              interpreter = new WLSTInterpreter();
              interpreter.exec
                     ("connect('"+user+"','"+pass+"','"+url+"')");
              interpreter.exec("edit()");
              interpreter.exec("startEdit()");
              interpreter.exec
                     ("cd('Servers/myserver/ServerDebug/myserver')");
              interpreter.exec("set('DebugJMSBackEnd','true')");       
              interpreter.exec("save()");
              interpreter.exec("activate()");

       } catch (Exception e) {
       System.out.println("Exception "+e);
       }
       }
}

Using the WLST is a dynamic method and can be used to enable debugging while the server is running.

Changes to the config.xml File

Changes in debugging characteristics, through console, or WLST, or command line are persisted in the config.xml file.

This sample config.xml fragment shows a transaction debug scope (set of debug attributes) and a single JMS attribute.

Example 10-1 Example Debugging Stanza for JMS

<server>
<name>myserver</name>
<server-debug>
<debug-scope>
<name>weblogic.transaction</name>
<enabled>true</enabled>
</debug-scope>
<debug-jms-back-end>true</debug-jms-back-end>
</server-debug>
</server> 

JMS Debugging Scopes

The following are registered debugging scopes for JMS:

  • DebugJMSBackEnd (scope weblogic.jms.backend) – prints information for debugging the JMS Back End (including some information used for distributed destinations and JMS SAF).

  • DebugJMSFrontEnd (scope weblogic.jms.frontend) – prints information for debugging the JMS Front End (including some information used for multicast).

  • DebugJMSCommon (scope weblogic.jms.common) – prints information for debugging JMS common methods (including some information from the client JMS producer).

  • DebugJMSConfig (scope weblogic.jms.config) – prints information related to JMS configuration (backend, distributed destinations, and foreign servers).

  • DebugJMSBoot (scope weblogic.jms.boot) – prints some messages at boot time regarding what store the JMS server is using and its configured destinations.

  • DebugJMSDispatcher (scope weblogic.jms.dispatcher) – prints information related to PeerGone() occurrences.

  • DebugJMSDistTopic (scope weblogic.jms.config) – prints information about distributed topics, and primary bind and unbind information.

  • DebugJMSPauseResume (scope weblogic.jms.pauseresume) – prints information about (backend) pause/resume destination operations.

  • DebugJMSModule (scope weblogic.jms.module) – prints a lot of information about JMS module operations and message life cycle.

  • DebugJMSMessagePath (scope weblogic.jms.messagePath) – prints information following a message through the message path (client, frontend, backend), including the message identifier.

  • DebugJMSSAF (scope weblogic.jms.saf) – prints information about JMS SAF (store-and-forward) destinations.

  • DebugJMSCDS (scope weblogic.jms.CDS) – prints detailed information about JMS "Configuration Directory Service" (used by various sub-systems to get the notification of configuration changes to the JMS resources configured in the server from within a cluster as well as across the clusters and domains).

  • DebugJMSWrappers (scope weblogic.jms.wrappers) – prints information pooling and wrapping of JMS connections, sessions, and other objects, used inside an EJB or servlet using the resource-reference element in the deployment descriptor.

Messaging Kernel and Path Service Debugging Scopes

The following are registered debugging scopes for the messaging kernel and the Path service.

  • DebugMessagingKernel (scope weblogic.messaging.kernel) – prints information about the messaging kernel.

  • DebugMessagingKernelBoot (scope weblogic.messaging.kernelboot) – prints information about booting the messaging kernel (processing messages).

  • DebugPathSvc (scope weblogic.messaging.pathsvc) – prints limited information about some unusual conditions in the path service.

  • DebugPathSvcVerbose (scope weblogic.messaging.pathsvcverbose) – prints limited information about unusual conditions in the path service.

Request Dyeing

Another option for debugging is to trace the flow of an individual (typically "dyed") application request through the JMS subsystem. For more information, see "Configuring the Dye Vector via the DyeInjection Monitor" in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

Message Life Cycle Logging

JMS logging is enabled by default when you create a JMS server, however, you must specifically enable it on message destinations in the JMS modules targeted to this JMS server (or on the JMS template used by destinations). For more information on WebLogic logging services, see "Understanding WebLogic Logging Services" in Configuring Log Files and Filtering Log Messages for Oracle WebLogic Server.

The message life cycle is an external view of the events that a JMS message traverses through once it has been accepted by the JMS server, either through the JMS APIs or the JMS Message Management APIs. Message life cycle logging provides an administrator with easy access to information about the existence and status of JMS messages from the JMS server viewpoint. In particular, each message log contains information about basic life cycle events such as message production, consumption, and removal.

Logging can occur on a continuous basis and over a long period of time. It can be also be used in real-time mode while the JMS server is running, or in an off-line fashion when the JMS server is down. For information about configuring message logging, see the following sources in the Oracle WebLogic Server Administration Console Help:

Events in the JMS Message Life Cycle

When message life cycle logging is enabled for a JMS destination, a record is added to the JMS server's message log file each time a message meets the conditions that correspond to a basic message life cycle event. The life cycle events that trigger a JMS message log entry are as follows:

  • Produced – This event is logged when a message enters a JMS server via the WebLogic Server JMS API or the JMS Management API.

  • Consumed – This event is logged when a message leaves a JMS server via the WebLogic Server JMS API or the JMS Management API.

  • Removed – This event is logged when a message is manually deleted from a JMS server via the WebLogic Server JMS API or the JMS Management API.

  • Expired – This event is logged when a message reaches the expiration time stored on the JMS server. This event is logged only once per message even though a separate expiration event occurs for each topic subscriber who received the message.

  • Retry exceeded – This event is logged when a message has exceeded its redelivery retry limit. This event may be logged more than one time per message, as each topic subscriber has its own redelivery count.

  • Consumer created – This event is logged when a JMS consumer is created for a queue or a JMS durable subscriber is created for a topic.

  • Consumer destroyed – This event is logged when a JMS consumer is closed or a JMS durable subscriber is unsubscribed.

Message Log Location

The message log is stored under your domain directory, as follows:

USER_DOMAIN\servers\servername\logs\jmsServers\jms_server_name\jms.messages.log

where USER_DOMAIN is the root directory of your domain, typically c:\Oracle\Middleware\user_projects\domains\USER_DOMAIN, which is parallel to the directory in which WebLogic Server program files are stored, typically c:\Oracle\Middleware\wlserver_10.3.

Enabling JMS Message Logging

You can enable or disable JMS message logging for a queue, topic, JMS template, uniform distributed queue, and uniform distributed topic using the WebLogic Server Administration Console. For more information see the following sources in the Oracle WebLogic Server Administration Console Help:

WebLogic Java Management Extensions (JMX) enables you to access the JMSSystemResourceMBean and JMSRuntimeMBean MBeans to manage JMS message logs. For more information see "Overview of WebLogic Server Subsystem MBeans" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

Note:

Logging JMS messages for non-durable subscribers is not enabled in the default configuration. To enable, set the following system property: weblogic.jms.message.logging.logNonDurableSubscriber=true.

You can also use the WebLogic Scripting Tool to configure JMS message logging for a JMS servers and JMS system resources. For more information, see Chapter 6, "Using WLST to Manage JMS Servers and JMS System Module Resources."

When you enable message logging, you can specify whether the log entry will include all the message header fields or a subset of them; all system-defined message properties or a subset of them; all user-defined properties or a subset of them. You may also choose to include or to exclude the body of the message. For more information about message headers and properties see "Developing a Basic JMS Application" in Programming JMS for Oracle WebLogic Server.

JMS Message Log Content

Each record added to the log includes basic information such as the message ID and correlation ID for the subject message. You can also configure the JMS server to include additional information such as the message type and user properties.

JMS Message Log Record Format

Except where noted, all records added to the JMS Message Life Cycle Log contain the following pieces of information in the order in which they are listed:

  • Date – The date and time the message log record is generated.

  • Transaction identifier – The transaction identifier for the transaction with which the message is associated

  • WLS diagnostic context – A unique identifier for a request or unit of work flowing through the system. It is included in the JMS message log to provide a correlation between events belonging to the same request.

  • Raw millisecond value for "Date" – To aid in troubleshooting high-traffic applications, the date and time the message log record is generated is displayed in milliseconds.

  • Raw nanosecond value for "Date" – To aid in troubleshooting high-traffic applications, the date and time the message log record is generated is displayed in nanoseconds.

  • JMS message ID – The unique identifier assigned to the message.

  • JMS correlation ID – A user-defined identifier for the message, often used to correlate messages about the same subject.

  • JMS destination name – The fully-qualified name of the destination server for the message.

  • JMS message life cycle event name – The name of the message life cycle event that triggered the log entry.

  • JMS user name – The name of the user who (produced? consumed? received?) the message.

  • JMS message consumer identifier – This information is included in the log only when the message life cycle event being logged is the "Consumed" event, the "Consumer Created" event, or the "Consumer Destroyed" event. If the message consumed was on a queue, the log will include information about the origin of the consumer and the OAM identifier for the consumer known to the JMS server. If the consumer is a durable subscriber, the log will also include the client ID for the connection and the subscription name.

    The syntax for the message consumer identifier is as follows:

    MC:CA(…):OAMI(wls_server_name.jms.connection#.session#.consumer#)
    

    where

    • MC stands for message consumer,

    • CA stands for client address,

    • OAMI stands for OA&M identifier,

    • and, when applicable, CC stands for connection consumer.

    If the consumer is a durable subscriber the additional information will be shown using the following syntax:

    DS:client_id.subscription_name[message consumer identifier]
    

    where DS stands for durable subscriber.

  • JMS message content – This field can be customized on a per destination basis. However, the message body will not be available.

  • JMS message selector – This information is included in the log only when the message life cycle event being logged is the "Consumer Created" event. The log will show the "Selector" argument from the JMS API.

Sample Log File Records

The sample log file records that follow show the type of information that is provided in the log file for each of the message life cycle events. Each record is a fixed length, but the information included will vary depending upon relevance to the event and on whether a valid value exists for each field in the record. The log file records use the following syntax:

####<date_and_time_stamp> <transaction_id> <WLS_diagnostic_context> 
<date_in_milliseconds> <date_in_nanoseconds> <JMS_message_id> 
<JMS_correlation_id> <JMS_destination_name> <life_cycle_event_name> 
<JMS_user_name> <consumer_identifier> <JMS_message_content> 
<JMS_message_selector> 

Note:

If you choose to include the JMS message content in the log file, note that any occurrences of the left-pointing angle bracket (<) and the right-pointing angle bracket (>) within the contents of the message will be escaped. In place of a left-pointing angle bracket you will see the string "&lt;" and in place of the right-pointing angle bracket you will see "&gt;" in the log file.

Consumer Created Event

####<May 13, 2005 4:06:33 PM EDT> <> <> <1116014793818> <345063> <> <>
 <jmsfunc!TestQueueLogging> <ConsumerCreate> <system> <MC:CA(/10.61.6.56):OAMI(myserver.jms.connection456.session460.consumer462)> <> <> 

Consumer Destroyed Event

####<May 13, 2005 4:06:33 PM EDT> <> <> <1116014793844> <40852> <> <>
<jmsfunc!TestQueueLogging> <ConsumerDestroy> <system> <MC:CA(/10.61.6.56):OAMI(myserver.jms.connection456.session460.consumer462)> <> <> 

Message Produced Event

####<May 13, 2005 4:06:43 PM EDT> <> <> <1116014803018> <693671> <ID:<327315.1116014803000.0>> <testSendRecord> <jmsfunc!TestQueueLoggingMarker>
 <Produced> <system> <> <&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;mes:WLJMSMessage
 xmlns:mes="http://www.bea.com/WLS/JMS/Message"&gt;&lt;mes:Header&gt;&lt;mes:JMSCor
relationID&gt;testSendRecord&lt;/mes:JMSCorrelationID&gt;&lt;mes:JMSDeliveryMode
&gt;NON_PERSISTENT&lt;/mes:JMSDeliveryMode&gt;&lt;mes:JMSExpiration&gt;0&lt;
/mes:JMSExpiration&gt;&lt;mes:JMSPriority&gt;4&lt;/mes:JMSPriority&gt;&lt;
mes:JMSRedelivered&gt;false&lt;/mes:JMSRedelivered&gt;&lt;mes:JMSTimestamp&gt;
1116014803000&lt;/mes:JMSTimestamp&gt;&lt;mes:Properties&gt;&lt;mes:property
name="JMSXDeliveryCount"&gt;&lt;mes:Int&gt;0&lt;/mes:Int&gt;&lt;/mes:property
&gt;&lt;/mes:Properties&gt;&lt;/mes:Header&gt;&lt;mes:Body&gt;&lt;mes:Text/&gt;
&lt;/mes:Body&gt;&lt;/mes:WLJMSMessage&gt;> <> 

Message Consumed Event

####<May 13, 2005 4:06:45 PM EDT> <> <> <1116014805137> <268791> <ID:<327315.1116014804578.0>> <hello> <jmsfunc!TestQueueLogging> <Consumed> <system>
<MC:CA(/10.61.6.56):OAMI(myserver.jms.connection456.session475.consumer477)> <&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;mes:WLJMSMessage
 xmlns:mes="http://www.bea.com/WLS/JMS/Message"&gt;&lt;mes:Header&gt;&lt;mes:
JMSCorrelationID&gt;hello&lt;/mes:JMSCorrelationID&gt;&lt;mes:JMSDeliveryMode
&gt;PERSISTENT&lt;/mes:JMSDeliveryMode&gt;&lt;mes:JMSExpiration&gt;0&lt;/mes:
JMSExpiration&gt;&lt;mes:JMSPriority&gt;4&lt;/mes:JMSPriority&gt;&lt;mes:
JMSRedelivered&gt;false&lt;/mes:JMSRedelivered&gt;&lt;mes:JMSTimestamp&gt;
1116014804578&lt;/mes:JMSTimestamp&gt;&lt;mes:JMSType&gt;SendRecord&lt;/mes:
JMSType&gt;&lt;mes:Properties&gt;&lt;mes:property name="JMS_BEA_RedeliveryLimit"&gt;&lt;mes:Int&gt;1&lt;/mes:Int&gt;&lt;/mes:property&gt;&lt;mes:
property name="JMSXDeliveryCount"&gt;&lt;mes:Int&gt;1&lt;/mes:Int&gt;&lt;/mes:property&gt;
&lt;/mes:Properties&gt;&lt;/mes:Header&gt;&lt;mes:Body&gt;&lt;mes:Text/&gt;&lt;/mes:Body&gt;&lt;/mes:WLJMSMessage&gt;> <> 

Message Expired Event

####<May 13, 2005 4:06:47 PM EDT> <> <> <1116014807258> <445317>
<ID:<327315.1116014807234.0>> <bar> <jmsfunc!TestQueueLogging> <Expired> <<WLS
 Kernel>> <> <&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;mes:WLJMSMessage
 xmlns:mes="http://www.bea.com/WLS/JMS/Message"&gt;&lt;mes:Header&gt;&lt;mes:
JMSCorrelationID&gt;bar&lt;/mes:JMSCorrelationID&gt;&lt;mes:JMSDeliveryMode&gt;
PERSISTENT&lt;/mes:JMSDeliveryMode&gt;&lt;mes:JMSExpiration&gt;1116014806234
&lt;/mes:JMSExpiration&gt;&lt;mes:JMSPriority&gt;4&lt;/mes:JMSPriority&gt;&lt;
mes:JMSRedelivered&gt;false&lt;/mes:JMSRedelivered&gt;&lt;mes:JMSTimestamp&gt;
1116014807234&lt;/mes:JMSTimestamp&gt;&lt;mes:JMSType&gt;ExpireRecord&lt;/mes:
JMSType&gt;&lt;mes:Properties&gt;&lt;mes:property name="JMS_BEA_RedeliveryLimit"&gt;&lt;mes:Int&gt;1&lt;/mes:Int&gt;&lt;/mes:property&gt;&lt;mes:
property name="JMSXDeliveryCount"&gt;&lt;mes:Int&gt;0&lt;/mes:Int&gt;&lt;/mes:property&gt;
&lt;/mes:Properties&gt;&lt;/mes:Header&gt;&lt;mes:Body&gt;&lt;mes:Text/&gt;&lt;/mes:Body&gt;&lt;/mes:WLJMSMessage&gt;> <> 

Retry Exceeded Event

####<May 13, 2005 4:06:53 PM EDT> <> <> <1116014813491> <394206> <ID:<327315.1116014813453.0>> <bar> <jmsfunc!TestQueueLogging> <Retry exceeded>
<<WLS Kernel>> <> <&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;mes:WLJMSMessage xmlns:mes="http://www.bea.com/WLS/JMS/Message"&gt;&lt;mes:Header&gt;&lt;mes:
JMSCorrelationID&gt;bar&lt;/mes:JMSCorrelationID&gt;&lt;mes:JMSDeliveryMode&gt;
PERSISTENT&lt;/mes:JMSDeliveryMode&gt;&lt;mes:JMSExpiration&gt;0&lt;/mes:
JMSExpiration&gt;&lt;mes:JMSPriority&gt;4&lt;/mes:JMSPriority&gt;&lt;mes:
JMSRedelivered&gt;true&lt;/mes:JMSRedelivered&gt;&lt;mes:JMSTimestamp&gt;
1116014813453&lt;/mes:JMSTimestamp&gt;&lt;mes:JMSType&gt;RetryRecord&lt;/mes:
JMSType&gt;&lt;mes:Properties&gt;&lt;mes:property name="JMS_BEA_RedeliveryLimit"&gt;&lt;mes:Int&gt;1&lt;/mes:Int&gt;&lt;/mes:property&gt;&lt;mes:
property name="JMSXDeliveryCount"&gt;&lt;mes:Int&gt;2&lt;/mes:Int&gt;&lt;/mes:property
&gt;&lt;/mes:Properties&gt;&lt;/mes:Header&gt;&lt;mes:Body&gt;&lt;mes:Text/&gt;
&lt;/mes:Body&gt;&lt;/mes:WLJMSMessage&gt;> <> 

Message Removed Event

####<May 13, 2005 4:06:45 PM EDT> <> <> <1116014805071> <169809> <ID:<327315.1116014804859.0>> <hello> <jmsfunc!TestTopicLogging> <Removed>
 <system> <DS:messagelogging_client.foo.SendRecordSubscriber> <&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;mes:WLJMSMessage xmlns:mes="http://www.bea.com/WLS/JMS/Message"&gt;&lt;mes:
Header&gt;&lt;mes:JMSCorrelationID&gt;hello&lt;/mes:JMSCorrelationID&gt;&lt;mes:
JMSDeliveryMode&gt;PERSISTENT&lt;/mes:JMSDeliveryMode&gt;&lt;mes:JMSExpiration
&gt;0&lt;/mes:JMSExpiration&gt;&lt;mes:JMSPriority&gt;4&lt;/mes:JMSPriority&gt;
&lt;mes:JMSRedelivered&gt;false&lt;/mes:JMSRedelivered&gt;&lt;mes:JMSTimestamp
&gt;1116014804859&lt;/mes:JMSTimestamp&gt;&lt;mes:JMSType&gt;
SendRecordSubscriber&lt;/mes:JMSType&gt;&lt;mes:Properties&gt;&lt;mes:property
 name="JMSXDeliveryCount"&gt;&lt;mes:Int&gt;0&lt;/mes:Int&gt;&lt;/mes:property
&gt;&lt;/mes:Properties&gt;&lt;/mes:Header&gt;&lt;mes:Body&gt;&lt;mes:Text/&gt;&lt;/mes:Body&gt;&lt;/mes:WLJMSMessage&gt;> <> 

Managing JMS Server Log Files

After you create a JMS server, you can configure criteria for moving (rotating) old log messages to a separate file. You can also change the default name of the log file.

Rotating Message Log Files

You can choose to rotate old log messages to a new file based on a specific file size or at specified intervals of time. Alternately, you can choose not to rotate old log messages; in this case, all messages will accumulate in a single file and you will have to erase the contents of the file when it becomes too large.

If you choose to rotate old messages whenever the log file reaches a particular size you must specify a minimum file size. After the log file reaches the specified minimum size, the next time the server checks the file size it will rename the current log file and create a new one for storing subsequent messages.

If you choose to rotate old messages at a regular interval, you must specify the time at which the first new message log file is to be created, and then specify the time interval that should pass before that file is renamed and replaced.

For more information about setting up log file rotation for JMS servers, see "Configure JMS server message log rotation" in the Oracle WebLogic Server Administration Console Help.

Renaming Message Log Files

Rotated log files are numbered in order of creation. For example, the seventh rotated file would be named myserver.log00007. For troubleshooting purposes, it may be useful to change the name of the log file or to include the time and date when the log file is rotated. To do this, you add java.text.SimpleDateFormat variables to the file name. Surround each variable with percentage (%) characters. If you specify a relative pathname when you change the name of the log file, it is interpreted as relative to the server's root directory.

For more information about renaming message log files for JMS servers, see "Configure JMS server message log rotation" in the Oracle WebLogic Server Administration Console Help.

Limiting the Number of Retained Message Log Files

If you choose to rotate old message log files based on either file size or time interval, you may also wish to limit the number of log files this JMS server creates for storing old messages. After the server reaches this limit, it deletes the oldest log file and creates a new log file with the latest suffix. If you do not enable this option, the server will create new files indefinitely and you will have to manually clean up these files.

For more information about limiting the number of message log files for JMS servers, see "Configure JMS server message log rotation" in the Oracle WebLogic Server Administration Console Help.

Controlling Message Operations on Destinations

WebLogic JMS configuration and runtime APIs enable you to pause and resume message production, insertion, and/or consumption operations on a JMS destination or temporary destination, on a group of destinations configured using the same template, or on all the destinations hosted by a single JMS Server, either programmatically (using JMX and the runtime MBean API) or administratively (using the Administration Console). In this way, you can control the JMS subsystem behavior in the event of an external resource failure that would otherwise cause the JMS subsystem to overload the system by continuously accepting and delivering (and redelivering) messages.

You can boot a JMS server and its destinations in a "paused" state which prevents any message production, insertion, or consumption on those destinations immediately after boot. To resume message operation activity, the administrator can later change the state of the paused destination to "resume" normal message production, insertion, or consumption operations. In addition, new runtime options allow an administrator to change the current state of a running destination to either allow or disallow new message production, insertion, or consumption.

Definition of Message Production, Insertion, and Consumption

There are several operations performed on messages on a destination:

  • Messages are produced when a producer creates and sends a new message to that destination.

  • Messages are inserted as a result of in-flight work completion, as when a message is made available upon commitment of a transaction or when a message scheduled to be made available after a delay is made available on a destination.

  • Messages are consumed when they are removed from the destination.

You can pause and resume any or all of these operations either at boot time or during runtime, as described in the sections below.

Pause and Resume Logging

When message production, insertion, or consumption on a destination is successfully "paused" or "resumed" either at boot time or at runtime, a message is added to the server log to indicate the same. In the event of failure to pause or resume message production, insertion, or consumption on a destination, the appropriate error/exceptions are logged.

Production Pause and Production Resume

When a JMS destination is "paused for production," new and existing producers attached to that destination are unable to produce new messages for that destination. A producer that attempts to send a message to a paused destination receives an exception that indicates that the destination is paused. When a destination is "resumed from production pause," production of new messages is allowed again. Pausing message production does not prevent the insertion of messages that are the result in-flight work.

Note:

For an explanation of what constitutes in-flight work, see Definition of In-Flight Work.

Pausing and Resuming Production at Boot-time

You can pause or resume production effective at boot-time for all the destinations on a JMS server, for a group of destinations that point to the same JMS template, or for individual destinations. If you configure production-paused-at-startup, the next time you boot the server, message production activities will be disallowed for the specified destination(s) until you explicitly change the state to "production enabled" for that destination. If you configure production to resume, the next time you boot the server, message production activities will be allowed on the specified destination(s) until the state is explicitly changed to "production paused" for that destination.

For more information about pausing and resuming message production at boot-time using the Administration console, see the following sources in the Oracle WebLogic Server Administration Console Help:

Pausing and Resuming Production at Runtime

You can pause or resume production during runtime for all the destinations targeted on a JMS server, for a group of destinations that point to the same JMS template, or for individual destinations. The most recent configuration change always take precedence, regardless of the level at which it is made (JMS server level, JMS template level, or destination level).

For more information about pausing and resuming production at runtime, see the following sources in the Oracle WebLogic Server Administration Console Help:

Production Pause and Resume and Distributed Destinations

If a member destination is paused for production, that member destination will not be considered for production by the producer. Messages will be steered away to other member destinations that are available for production.

Production Pause and Resume and JMS Connection Stop/Start

Stopping or starting a JMS connection has no effect on the production pause or production resume state of a destination.

Insertion Pause and Insertion Resume

When a JMS destination is paused for "insertion," both messages inserted as a result of in-flight work and new messages sent by producers are prevented from appearing on the destination. Use insertion pause to stop all messages from appearing on a destination.

You can determine whether there is any in-flight work pending by looking at the statistics on the Administration Console. When you pause the destination for message "insertion", messages related to in-flight work completion are made "not deliverable" and new message production operations fail. All of those messages become "invisible" to the consumers and the statistics are adjusted to reflect that the messages are no longer pending.

The "insertion" pause operation supersedes the "production" pause operation. In other words, if the destination is currently in the "production paused" state, you can change it to the "insertion paused" state.

You must explicitly "resume" a destination for message insertion to allow in-flight messages to appear on that destination. Successful completion of the insertion "resume" operation will change the state of the destination to "insertion enabled" and all the "invisible" in-flight messages will be made available.

Pausing and Resuming Insertion at Boot Time

You can pause or resume insertion effective at boot-time for all the destinations on a JMS server, for a group of destinations that point to the same JMS template, or for individual destinations. If you configure insertion-paused-at-startup, the next time you boot the server, message insertion and production activities will be disallowed on the specified destination(s) until you explicitly change the state to "insertion enabled" for that destination. If you configure insertion to resume, the next time you boot the server, message insertion activities will be allowed on the specified destination(s) until the state is explicitly changed to "insertion paused" for that destination.

For more information about pausing and resuming message insertion at boot-time, see the following sources in the Oracle WebLogic Server Administration Console Help:

Pausing and Resuming Insertion at Runtime

You can pause or resume insertion during runtime for all the destinations on a JMS server, for a group of destinations that point to the same JMS template, or for individual destinations. The most recent configuration change always take precedence, regardless of the level at which it is made (JMS Server level, JMS Template level, or destination level).

For more information about pausing and resuming insertion at runtime, see the following sources in the Oracle WebLogic Server Administration Console Help:

Insertion Pause and Resume and Distributed Destination

If a member destination is paused for insertion, that member destination will not be considered for message forwarding. Messages will be steered away to other member destinations that are available for insertion.

Insertion Pause and Resume and JMS Connection Stop/Start

Stopping or starting a JMS Connection has no effect on the insertion pause or insertion resume state of a destination.

Consumption Pause and Consumption Resume

When a JMS destination is "paused for consumption," messages on that destination are not available for consumption. When the destination is "resumed from consumption pause", both new and existing consumers attached to that destination are allowed to consume messages on the destination again.

When the destination is paused for consumption, the destination's state is marked as "consumption paused" and all new, synchronous receive operations will block until consumption is resumed and there are messages available for consumption. All synchronous receive with blocking time-out operations will block for the specified length of time. Messages will not be delivered to synchronous consumers attached to that destination while the destination is paused for consumption.

After a successful consumption "pause" operation, the user has to explicitly "resume" the destination to allow consume operations on that destination.

Pausing and Resuming Consumption at Boot-time

You can pause or resume consumption effective at boot-time for all the destinations on a JMS server, for a group of destinations that point to the same JMS template, or for individual destinations. If you configure consumption-paused-at-startup, the next time you boot the server, message consumption activities will be disallowed on the specified destination(s) until you explicitly change the state to "consumption enabled" for that destination. If you configure consumption to resume, the next time you boot the server, message consumption activities will be allowed on the specified destination(s) until the state is explicitly changed to "consumption paused" for that destination.

For more information about pausing and resuming consumption at boot-time, see the following sources in the Oracle WebLogic Server Administration Console Help:

Pausing and Resuming Consumption at Runtime

You can pause or resume consumption during runtime for all the destinations on a JMS server, for a group of destinations that point to the same JMS template, or for individual destinations. The most recent configuration change always take precedence, regardless of the level at which it is made (JMS Server level, JMS Template level, or destination level).

For more information about pausing and resuming consumption at runtime, see the following sources in the Oracle WebLogic Server Administration Console Help:

Consumption Pause and Resume and Queue Browsers

Queue Browsers are special type of consumers that are only allowed to "peek" into queue destinations. A browse operation on a destination paused for consumption is perfectly legitimate and is allowed.

Consumption Pause and Resume and Distributed Destination

Member destinations that are currently paused for consumption are not considered by the consumer load balancing algorithm.

Consumption Pause and Resume and Message-Driven Beans

Pausing a destination for consumption will prevent a message-driven bean (MDB) from getting any messages from its associated destination. This feature gives you more flexible control over the delivery of messages delivery to MDBs from the individual destination level as opposed to using connection start/stop. In other words, if you use the consumption pause/resume feature, you can share the JMS connection among the multiple MDBs and still be able to prevent message delivery to selected MDBs by pausing the associated destination for consumption.

For more information on using MDBs, see "Configuring Suspension of Message Delivery During JMS Resource Outages" inProgramming Message-Driven Beans for Oracle WebLogic Server.

Consumption Pause and Resume and JMS Connection Stop/Start

The JMS connection stop/start feature determines whether a consumer can successfully invoke the receive APIs or not. The consumption pause/resume feature on a destination determines whether the receive call will get any messages from the destination or not. Stopping or starting a consumer's connection does not have any impact on the destination's consumption pause state.

If the consumer's connection is "started" from the "stopped" state, synchronous receive operations might block or time-out if the destination is currently paused for consumption. Asynchronous consumers will not receive any messages if the associated destination is in "consumption paused" state.

Definition of In-Flight Work

In-flight Work Associated with Producers

The following types of messages are inserted on a destination as a result of in-flight work associated with message producers.

  • Unborn Messages – Messages that are created by the producer with "birth time" (TimeToDeliver) set in the future. Until delivered, unborn messages are counted as "pending" messages in the destination statistics and are not available for consumption.

  • Uncommitted Messages – Messages that are produced as part of a transaction (using either user transaction or transacted session) and have not yet been either committed or rolled back. Until the transaction has been completed, uncommitted messages are counted as "pending" messages in the destination statistics and are not available for consumption.

  • Quota Blocking Send – Messages that, if initially prevented from reaching a destination due to a quota limit, will block for a specific period of time while waiting for the destination to become available. The message may exceed the message quota limit, the byte quota limit, or both quota limits on the destination. While blocking, these messages are invisible to the system and are not counted against any of the destination statistics.

In-flight Work Associated with Consumers

The following types of messages are inserted on a destination as a result of in-flight work associated with message consumers.

  • Unacknowledged (CLIENT ACK PENDING) Messages – Messages that have been received by a client and are awaiting acknowledgement from the client. These are "pending messages" which are removed from the destination/system when the acknowledgement is received.

  • Uncommitted Messages – Messages that have been received by a client within a transaction which has not yet been committed or rolled back. When the client successfully commits the transaction the messages are removed from the system.

  • Rolled-back Messages – Messages that are put back on a destination because of the successful rollback of a transaction.

    These messages might or might not be ready for redelivery to the clients immediately, depending on the redelivery parameters (i.e., RedeliveryDelay and/or RedeliveryDelayOverride and RedeliveryLimit) configured on the associated connection factory and destination, or whether rollback requests are internally processed asynchronously. Consequently, a message that's involved in a consume operation subject to a rollback request may not be visible to a consumer receiveNoWait() call if the call is made immediately after the rollback request.

    If there is a redelivery delay configured, then, for the duration of that delay, the messages are not available for redelivery and the messages are counted as "pending" in the destination statistics. After the delay period, if the redelivery limit has not been exceeded, then they are delivered and are counted as "current" messages in the destination statistics. If the redelivery limit has been exceeded, then the messages are moved to the error destination, if one has been configured, or are dropped, if no error destination has been configured.

    Rollbacks can affect the order in which messages are processed. A rolled back message can be redelivered after subsequent messages in the same queue or subscription are processed. If strict message ordering is required, see Using Message Unit-of-Order in Programming JMS for Oracle WebLogic Server.

  • Recovered Messages – Messages that appear on the queue because of an explicit call to session "recover" by the client. These messages are similar to the Rolled-back Messages discussed above.

  • Redelivered Messages – Messages that reappear on the destination because of an unsuccessful delivery attempt to the client. These messages are similar to the Rolled-back Messages discussed above.

Order of Precedence for Boot-time Pause and Resume of Message Operations

You can pause and resume destinations at boot-time by setting attributes at several different levels:

  • If you are using a JMS server to host a group of destinations, you can pause or resume message operations on the entire group of destinations.

  • If you are using a JMS template to define the attribute values of groups of destinations, you can pause or resume message operations on all of the destinations in a group.

  • You can pause and resume message operations on a single destination.

If the values at each of these levels are not in agreement at boot-time, the following order of precedence is used to determine the behavior of the message operations on the specified destination(s). For each of the attributes used to configure pausing and resumption of message operations:

  1. If the hosting JMS server for the destination has the attribute set with a valid value, then that value determines the state of the destination at boot time. Server-level settings have first precedence.

  2. If the hosting JMS server does not have the attribute set with a valid value, then the value of the attribute on the destination level has second highest precedence and determines the state of the destination at boot time.

  3. If neither the hosting JMS server nor the destination has the attribute set with a valid value, then the value of the attribute on the JMS template determines the state of the destination at boot time.

  4. If the attribute has not been set at any of the three levels, then the value is assumed to be "false".

Security

The administrative user/group can override the current state of a destination irrespective of whether the destination's state is currently being controlled by other users.

If two non-administrative users are trying to control the state of the destination, then the following rules apply.

  1. Only a user who belongs to the same group as the user who changed the state of the destination to "paused" is allowed to "resume" the destination to the normal operation.

  2. If the state change is attempted by two different users who belong to two different