Configuring and Managing WebLogic JMS

Introduction and Roadmap

The following sections describe the contents and organization of this guide—Configuring and Managing WebLogic JMS.

Document Scope and Audience

This document is a resource for system administrators who configure, manage, and monitor WebLogic JMS resources, including JMS servers, stand-alone destinations (queues and topics), distributed destinations, and connection factories.

The document is relevant to production phase administration, monitoring, and performance tuning. It does not address the pre-production development or testing phases of a software project. For links to WebLogic Server documentation and resources for these topics, see Related Documentation.

It is assumed that the reader is familiar with WebLogic Server system administration. This document emphasizes the value-added features provided by WebLogic Server JMS and key information about how to use WebLogic Server features and facilities to maintain WebLogic JMS in a production environment.

Guide to This Document

This chapter, Introduction and Roadmap, describes the organization and scope of this guide.
Understanding JMS Resource Configuration, is an overview of WebLogic JMS architecture and features.
Configuring Basic JMS System Resources, describes how to configure basic WebLogic JMS resources, such as a JMS server, destinations (queues and topics), and connection factories.
Configuring Advanced JMS System Resources, explains how to configure clustering JMS features, such as JMS servers, migratable targets, and distributed destinations.
Configuring JMS Application Modules for Deployment, describes how to prepare JMS resources for an application module that can be deployed as a stand-alone resource that is globally available, or as part of an Enterprise Application that is available only to the enclosing application.
Monitoring JMS Statistics and Managing Messages, describes how to monitor and manage the run-time statistics for your JMS objects from the Administration Console.
Using WLST to Manage JMS Servers and JMS System Resources, explains how to use the WebLogic Scripting Tool to create and manage JMS resources programmatically.
Tuning WebLogic JMS, explains how to get the most out of your applications by using the administrative performance tuning features available with WebLogic JMS.
Troubleshooting WebLogic JMS, explains how to configure and manage message logs, and how to temporarily pause message operations on destinations.

JMS Samples and Tutorials for the JMS Administrator

In addition to this document, BEA Systems provides JMS code samples and tutorials that document JMS configuration, API use, and key JMS development tasks. BEA recommends that you run some or all of the JMS examples before configuring your own system.

Avitek Medical Records Application (MedRec) and Tutorials

MedRec is an end-to-end sample J2EE application shipped with WebLogic Server that simulates an independent, centralized medical record management system. The MedRec application enables patients, doctors, and administrators to manage patient data using a variety of different clients.

MedRec demonstrates WebLogic Server and J2EE features, and highlights BEA-recommended best practices. MedRec is included in the WebLogic Server distribution, and can be accessed from the Start menu on Windows machines. For Linux and other platforms, you can start MedRec from the WL_HOME\samples\domains\medrec directory, where WL_HOME is the top-level installation directory for WebLogic Platform.

JMS Examples in the WebLogic Server Distribution

This release of WebLogic Server optionally installs API code examples in WL_HOME\samples\server\examples\src\examples, where WL_HOME is the top-level directory of your WebLogic Server installation. You can start the examples server, and obtain information about the samples and how to run them from the WebLogic Server Start menu.

Additional JMS Examples Available for Download

Additional API examples for download at http://codesamples.projects.dev2dev.bea.com. These examples are distributed as ZIP files that you can unzip into an existing WebLogic Server samples directory structure.

You build and run the downloadable examples in the same manner as you would an installed WebLogic Server example. See the download pages of individual examples for more information at https://codesample.projects.dev2dev.bea.com.

New and Changed JMS Features In This Release

WebLogic Server introduces the following improvements in the configuration, administration, availability, and performance of WebLogic JMS.

Configuration and Administration Enhancements:

Simplified Configuration and Targeting of JMS System Resources

Message Management, Monitoring, and Diagnostics:

Functionality Enhancements

Automatic JMS Client Failover

Performance Improvements

Deprecated JMS Methods and Interfaces

Note: If you are not familiar with the new features provided in version 9.0 of WebLogic Server, see the What's New in WebLogic Server 9.0 section of the WebLogic Server Release Notes.

Simplified Configuration and Targeting of JMS System Resources

JMS configurations are stored as modules, which are defined by an XML file that conforms to the weblogic-jmsmd.xsd schema. The configuration of JMS resources in a globally-available system module using the Administration Console, has been simplified so you can choose whether to simply accept pre-selected targets for a resource type or proceed to an advanced targeting page where you can either select an existing subdeployment or create a new one. A subdeployment is a mechanism by which JMS module resources (such as queues, topics, and connection factories) are grouped and targeted to a server resource (such as JMS servers, server instances, or cluster). A module-level subdeployment management page has also been added to allow you to manage the configured subdeployments in JMS system modules.

For more information, see JMS System Module and Resource Subdeployment Targeting.

Message Life Cycle Logging for JMS SAF Destinations

The Store-and-Forward service now includes message life cycle logging for JMS SAF destinations. The Message Life Cycle Logging feature provides an administrator with better transparency about the existence of JMS messages from a JMS server's viewpoint, in particular 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 a JMS server is down.

For more information, see Troubleshooting WebLogic Store-and-Forward in Configuring and Managing WebLogic Store-and-Forward.

Enhanced Run-time Management for Durable Topic Subscribers and Distributed Queues

New message administration enhancements allow administrators to manage durable topic subscribers and distributed queues using either the Administration Console or through new public runtime APIs. This functionality also provides the ability to view and browse all messages, and to manipulate most messages on durable subscribers and distributed queues. These message management enhancements include message browsing (for sorting), message manipulation (such as move and delete), message import and export.

For more information on managing messages, see Monitoring JMS Statistics and Managing Messages.

Automatic JMS Client Failover

The JMS client reconnect feature provides transparent failover by making JMS client objects individually and collectively refreshable on a network failure. The network connection failure could be due to transient (temporary blip in the network connection) or non-transient (server bounce or network failure) reasons. For release 9.1, refreshable client objects include Destinations, Connections, Sessions, and Producers.

For example, a JMS destination (queue or topic) looked up via JNDI will be re-usable after a network failure without requiring it to be re-looked up. This network failure could be between the JMS client JVM and the remote WebLogic Server it is connected to as part of the JNDI lookup, or between the JMS client JVM and any remote WebLogic server in the same cluster that the client subsequently connects to.

See Automatic Failover for JMS Clients in Programming WebLogic JMS.

Performance Improvements

The following performance enhancing features have been added for release 9.1.

Message Prefetching Available for Synchronous Message Consumers

In WebLogic Server 9.1, synchronous consumers can use the same efficient behavior as asynchronous consumers by enabling the Prefetch Mode for Synchronous Consumers option on the consumer's JMS connection factory using the Administration Console or new APIs. Similar to the asynchronous message pipeline, when the Prefetch Mode is enabled on a connection factory, its targeted JMS server will proactively push batches of unconsumed messages to synchronous message consumers, using the connection factory's Messages Maximum per Session parameter to define the maximum number of prefetched messages per batch.

This may improve performance because messages are ready and waiting for synchronous consumers when the consumers are ready to process more messages, and it may also reduce network traffic by reducing synchronous calls from consumers that must otherwise continually poll for messages.

See Receiving Messages Synchronously in Programming WebLogic JMS.

Improved Tuning of Message Latency or Throughput on Destinations

The Messaging Performance Preference tuning option on JMS destinations enables you to fine-tune message handling by a destination. JMS destinations include internal algorithms that attempt to automatically optimize performance by grouping messages into batches for delivery to consumers. In response to changes in message rate and other factors, these algorithms change batch size and delivery times. However, it is impossible for the algorithms to optimize performance for every messaging environment. The Messaging Performance Preference tuning option enables you to modify how these algorithms react to changes in message rate and other factors so that you can fine-tune performance for your system.

See Tuning Destination Performance.

Deprecated JMS Methods and Interfaces

The following method has been removed for release 9.1:

weblogic.jms.extensions.WLMessage.getSize()

WebLogic Server Value-Added JMS Features

WebLogic JMS provides numerous WebLogic JMS Extension APIs that go above and beyond the standard JMS APIs specified by the JMS 1.1 Specification. Moreover, it is tightly integrated into the WebLogic Server platform, allowing you to build highly-secure J2EE applications that can be easily monitored and administered through the WebLogic Server console. In addition to fully supporting XA transactions, WebLogic JMS also features high availability through its clustering and service migration features, while also providing seamless interoperability with other versions of WebLogic Server and third-party messaging providers.

The following sections provide an overview of the unique features and powerful capabilities of WebLogic JMS.

Note: For a comprehensive listing of the new WebLogic JMS feature introduced in this release, see New and Changed JMS Features In This Release.

Enterprise-Grade Reliability

Out-of-the-box transaction support:

Fully supports transactions, including distributed transactions, between JMS applications and other transaction-capable resources using the Java Transaction API (JTA), as described in "Using Transactions with WebLogic JMS" in Programming WebLogic JMS.
Fully-integrated Transaction Manager, as described in "Introducing Transactions" in Using WebLogic JTA.

File or database persistent message storage (both fully XA transaction capable). See "Using the WebLogic Persistent Store" in Configuring WebLogic Server Environments.
Message Store-and-Forward (SAF) is clusterable and improves reliability by locally storing messages sent to unavailable remote destinations. See "Understanding the Store-and-Forward Service" in Configuring and Managing WebLogic Store-and-Forward.
Automatic JMS client reconnect provides transparent failover by making JMS client objects individually and collectively refreshable on a network failure. See Automatic Failover for JMS Clients in Programming WebLogic JMS.
Supports connection clustering using connection factories targeted on multiple WebLogic Servers, as described in Configuring WebLogic JMS Clustering.
Automatic creation of Uniform Distributed Destinations that provide high availability, load balancing, and failover support in a cluster, as described in "Using Distributed Destinations" in Programming WebLogic JMS.
Automatic whole server migration provides improved cluster reliability and server migration WebLogic Server now supports automatic and manual migration of a clustered server instance and all the services it hosts from one machine to another, as described in Configuring WebLogic JMS Clustering.
Redirects failed or expired messages to error destinations, as described in "Managing Rolled Back, Recovered, Redelivered, or Expired Messages" in Programming WebLogic JMS.
Provides three levels of load balancing: network-level, JMS connections, and distributed destinations.

Enterprise-Level Features

WebLogic Server fully supports the JMS 1.1 Specification, is fully compliant with the J2EE 1.4 specification, and provides numerous WebLogic JMS Extensions that go beyond the standard JMS APIs.
Provides robust message and destination management capabilities:

Administrators can manipulate most messages in a running JMS Server, using either the Administration Console or runtime APIs. See Managing JMS Messages.
Administrators can pause and resume message production, message insertion (in-flight messages), and message consumption operations on a given JMS destination, or on all the destinations hosted by a single JMS Server, using either the Administration Console or runtime APIs. See Controlling Message Operations on Destinations.
Message-Driven EJBs (MDBs) also supply message pause and resume functionality, and can even automatically temporarily pause during error conditions. See Message-Driven EJBs in Programming WebLogic Enterprise JavaBeans.

Modular deployment of JMS resources, which are defined by an XML so that you can migrate your application and the required JMS configuration from environment to environment without opening an enterprise application file, and without extensive manual JMS reconfiguration. See Overview of JMS Modules.
Message Life Cycle Logging provides an administrator with better transparency about the existence of JMS messages from the JMS server viewpoint, in particular basic life cycle events, such as message production, consumption, and removal. See Message Life Cycle Logging.
JMS message producers can group ordered messages into a single unit-of-order, which guarantees that all such messages are processed serially, in the order in which they were created. See "Using Message Unit-of-Order" in Programming WebLogic JMS.
Timer services available for scheduled message delivery, as described in "Setting Message Delivery Times" in Programming WebLogic JMS.
Flexible expired message policies to handle expired messages, as described in Handling Expired Messages.
Supports messages containing XML (Extensible Markup Language). See "Defining XML Message Selectors Using the XML Selector Method" in Programming WebLogic JMS.
Thin application client .JAR that provides full WebLogic Server J2EE functionality, including JMS, yet greatly reduces the client-side WebLogic footprint. See "WebLogic JMS Thin Client" in Programming Stand Alone Clients.
Automatic pooling of JMS client resources in server-side applications via JMS resource-reference pooling. Server-side applications use standard JMS APIs, but get automatic resource pooling. See "Enhanced J2EE Support for Using WebLogic JMS With EJBs and Servlets" in Programming WebLogic JMS.

Performance

WebLogic JMS features enterprise-class performance features, such as automatic message paging, message compression, and DOM support for XML messages:

WebLogic Server uses highly optimized disk access algorithms and other internal enhancements to provide a unified messaging kernel that improves both JMS-based and Web Services messaging performance. See "Using the WebLogic Persistent Store" in Configuring WebLogic Server Environments.
Message paging automatically kicks in during peak load periods to free up virtual memory. See Paging Out Messages To Free Up Memory.
Administrators can enable the compression of messages that exceed a specified threshold size to improve the performance of sending messages travelling across JVM boundaries using either the Administration Console or runtime APIs. See Compressing Messages.
Synchronous consumers can also use the same efficient behavior as asynchronous consumers by enabling the Prefetch Mode for Synchronous Consumers option on the consumer's JMS connection factory, using either the Administration Console or runtime APIs. See Receiving Messages Synchronously in Programming WebLogic JMS
Supplies a wide variety of performance tuning options for JMS messages. See "Tuning WebLogic JMS" in WebLogic Server Performance and Tuning.
Supports MDB transaction batching by processing multiple messages in a single transaction.
JMS SAF provides better performance than the WebLogic Messaging Bridge across clusters. See "Tuning WebLogic JMS Store-and-Forward" in WebLogic Server Performance and Tuning.
DOM (Document Object Model) support for sending XML messages greatly improves performance for implementations that already use a DOM, since those applications do not have to flatten the DOM before sending XML messages. See Sending XML Messages in Programming WebLogic JMS.
Message flow control during peak load periods, including blocking overactive senders, as described in Controlling the Flow of Messages on JMS Servers and Destinations and Defining Quotas for Destinations.
The automatic pooling of connections and other objects by the JMS wrappers via JMS resource-reference pooling. See "Enhanced J2EE Support for Using WebLogic JMS With EJBs and Servlets" in Programming WebLogic JMS.
Multicasting of messages for simultaneous delivery to many clients using IP multicast, as described in "Using Multicasting with WebLogic Server" in Programming WebLogic JMS.

Tight Integration With WebLogic Server

JMS can be accessed locally by server-side applications without a network call because the destinations can exist on the same server as the application.
Uses same ports, protocols, and user identities as WebLogic Server (T3, IIOP, and HTTP tunnelling protocols, optionally with SSL).
Web Services, Enterprise Java Beans (including MDBs), and servlets supplied by WebLogic Server can work in close concert with JMS.
Can be configured and monitored by using the same Administration Console, or by using the JMS API.
Supports the WebLogic Scripting Tool (WLST) to initiate, manage, and persist configuration changes interactively or by using an executable script. See Using WLST to Manage JMS Servers and JMS System Resources.
Complete JMX administrative and monitoring APIs, as described in Developing Custom Management Utilities with JMX.
Fully-integrated Transaction Manager, as described in "Introducing Transactions" in Using WebLogic JTA.
Leverages sophisticated security model built into WebLogic Server (policy engine), as described in the Understanding WebLogic Security and "JMS (Java Message Service) Resources" in Securing WebLogic Resources.

Interoperability With Other Messaging Services

Fully supports direct interoperability from WebLogic Server 6.1 through WebLogic Server 9.1. For example, a release 6.1 client can interoperate with a release 9.1 server and vice-versa.
Messages forwarded transactionally by the WebLogic Messaging Bridge to other JMS providers — as well as to other instances and versions of WebLogic JMS, as described see Configuring and Managing WebLogic Messaging Bridge.
Supports mapping of other JMS providers so their objects appear in the WebLogic JNDI tree as local JMS objects. Also references remote instances of WebLogic Server in another cluster or domain in the local JNDI tree. See Foreign Server Configuration.
Uses MDBs to transactionally receive messages from multiple JMS providers. See "Message-Driven EJBs" in Programming WebLogic Enterprise JavaBeans.
Reliable Web Services integration with JMS as a transport, as described in "Using Reliable Web Services Messaging" in Programming WebLogic Web Services.
Automatic transaction enlistment of non-WebLogic JMS client resources in server-side applications via JMS resource-reference pooling. See "Enhanced J2EE Support for Using WebLogic JMS With EJBs and Servlets" in Programming WebLogic JMS.
Seamless integration with BEA Tuxedo messaging provided by WebLogic Tuxedo Connector. See "How to Configure the Tuxedo Queuing Bridge" in the WebLogic Tuxedo Connector Administration Guide.
The Weblogic JMS C API enables programs written in "C" to participate in JMS applications. This implementation of the JMS C API uses JNI in order to access a Java Virtual Machine (JVM). See WebLogic C API in Programming WebLogic JMS.