Configuring and Managing WebLogic JMS

Understanding JMS Resource Configuration

These sections briefly review the different WebLogic JMS concepts and features, and describe how they work with other application components and WebLogic Server.

It is assumed the reader is familiar with Java programming and JMS 1.1 concepts and features.

• Overview of JMS and WebLogic Server
• What Is the Java Message Service?
• WebLogic JMS Anatomy and Environment
• Domain Configuration: System Resources vs. Application Resources
• What Are JMS Configuration Resources?
• WebLogic Server Value-Added JMS Features
• Enterprise-Grade Reliability
• Enterprise-Level Features
• Tight Integration With WebLogic Server
• Interoperability With Other Messaging Services
• Clustered WebLogic JMS

 

---

Overview of JMS and WebLogic Server

The WebLogic Server implementation of JMS is an enterprise-class messaging system that is tightly integrated into the WebLogic Server platform. It fully supports the JMS 1.1 Specification and also provides numerous WebLogic JMS Extensions that go beyond the standard JMS APIs.

What Is the Java Message Service?

An enterprise messaging system enables applications to asynchronously communicate with one another through the exchange of messages. A message is a request, report, and/or event that contains information needed to coordinate communication between different applications. A message provides a level of abstraction, allowing you to separate the details about the destination system from the application code.

The Java Message Service (JMS) is a standard API for accessing enterprise messaging systems that is implemented by industry messaging providers. Specifically, 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

WebLogic JMS accepts messages from producer applications and delivers them to consumer applications. For more information on JMS API programming with WebLogic Server, see Programming WebLogic JMS.

WebLogic JMS Anatomy and Environment

The following figure illustrates the WebLogic JMS architecture.

Figure 2-1 WebLogic JMS Architecture

 

The major components of the WebLogic JMS architecture include:

• JMS servers host a defined set of destinations (queues for point-to-point communication or topics for publish-and-subscribe) in a JMS module, with which client applications can interact, and any associated persistent storage that resides on a WebLogic Server instance.
• JMS modules contain configuration resources (queue and topic destinations, connection factories, templates, destination keys, quota, distributed destinations, foreign servers, JMS store-and-forward), and are defined by XML documents that conform to the weblogic-jmsmd.xsd schema.
• Client JMS applications that either produce messages to destinations or consume messages from destinations.
• JNDI (Java Naming and Directory Interface), which provides a server lookup facility.
• WebLogic persistent storage (a server instance's default store, a user-defined file store, or a user-defined JDBC-accessible store) for storing persistent message data.

 

---

Domain Configuration: System Resources vs. Application Resources

In general, the WebLogic Server domain configuration file (config.xml) contains the configuration information required for a domain. This configuration information can be further classified into environment-related (or system resource definitions) and application-related information. Some examples of environment-related definitions are the identification and definition of JMS servers, JDBC data sources, WebLogic persistent stores, and server network addresses. These system resources are usually unique from domain to domain.

The configuration and management of these system resources are the responsibility of a WebLogic administrator, who usually receives this information from an organization's system administrator or MIS department. To accomplish these administrative tasks, an administrator can use the WebLogic Administration Console, various command-line tools, such as WebLogic Scripting Tool (WLST), or JMX APIs for programmatic administration.

Some examples of application-related definitions that are highly independent of the domain environment are the various J2EE application components configurations, such as EAR, WAR, JAR, RAR files, and which in this release includes JMS and JDBC modules. The application components are originally developed and packaged by an application development team, and may contain optional programs (compiled Java code) and respective configuration information (also called descriptors, which are mostly stored as XML files). In the case of JMS and JDBC modules, however, there are no compiled Java programs involved. These pre-packaged applications are given to WebLogic Server administrators for deployment in a WebLogic domain.

WebLogic Server provides tools for deploying applications, such as the Administration Console and the weblogic.Deployer command-line utility. The process of deploying an application links the application components to the environment-specific resource definitions, such as which server instances should host a given application component (targeting), and the WebLogic persistent store to use for persisting JMS messages.

Once the initial deployment is completed, an administrator has only limited control over deployed applications. For example, administrators are only allowed to ensure the proper life-cycle of these applications (deploy, undeploy, redeploy, remove, etc.) and to tune the parameters, such as increasing or decreasing the number of instances of any given application to satisfy the client needs. Other than lifecycle and tuning, any modification to these applications must be completed by the application development team.

 

---

What Are JMS Configuration Resources?

In prior releases, all JMS configuration information was stored in a WebLogic domain's configuration file. In this release, JMS configurations (destinations, connections factories, templates, etc.) are stored outside of the WebLogic domain as module descriptor files, which are defined by XML documents that conform to the weblogic-jmsmd.xsd schema. JMS modules do not include JMS server definitions, which are still stored in the WebLogic domain configuration file.

You create and manage JMS resources either as system resource modules, similar to the way they were managed prior to this release, or as application modules. JMS application modules are a WebLogic-specific extension of J2EE modules and can be deployed either with a J2EE application (as a packaged resource) or as standalone modules that can be made globally available.

With modular deployment of JMS resources, you can migrate your application and the required JMS configuration from environment to environment, such as from a testing environment to a production environment, without opening an enterprise application file (such as an EAR file) or a standalone JMS module, and without extensive manual JMS reconfiguration.

JMS Servers

JMS servers are environment-related configuration entities that act as management containers for JMS queue and topic resources within JMS modules that are targeted to specific JMS servers. A JMS server's primary responsibility for its targeted destinations is to maintain information on what persistent store is used for any persistent messages that arrive on the destinations, and to maintain the states of durable subscribers created on the destinations. As a container for targeted destinations, any configuration or run-time changes to a JMS server can affect all of its destinations.

As in prior releases, JMS servers are persisted in the domain's config.xml file and multiple JMS servers can be configured on the various WebLogic Server instances in a cluster, as long as they are uniquely named. Client applications use either the JNDI tree or the java:/comp/env naming context to look up a connection factory and create a connection to establish communication with a JMS server. Each JMS server handles requests for all targeted modules' destinations. Requests for destinations not handled by a JMS server are forwarded to the appropriate server instance.

There are a number of behavioral differences compared to how JMS servers operated in prior releases:

• Because destinations are encapsulated in JMS modules, they are no longer nested under JMS servers in the configuration file. However, the prior "subtargeting" relationship between JMS servers and destinations is still maintained since destination resources within a JMS module are always targeted to JMS servers. This way, JMS servers still manage persistent messages, durable subscribers, message paging, and, optionally, quota for destinations targeted to them. Multiple JMS modules can be targeted to each JMS server in a domain.
• JMS servers support the new Persistent Store that is available to multiple subsystems and services within a server instance, as described in Persistent Stores.
• JMS servers can store persistent messages in a host server's default file store by enabling the "Use the Default Store" option. In prior releases, persistent messages were silently downgraded to non-persistent if no store was configured. Disabling the Use the Default Store option, however, forces persistent messages to be non-persistent.
• In place of the deprecated JMS stores (JMS file store and JMS JDBC store), JMS servers now support user-defined WebLogic File Stores or JDBC stores, which provide better performance and more capabilities than the legacy JMS stores. (The legacy JMS stores are supported in this release for backward compatibility.)
• JMS servers support an improved message paging mechanism. For more information on message paging, see Paging Out Messages To Free Up Memory.
• The configuration of a dedicated paging store is no longer necessary because paged messages are stored in a directory on your file system -- either to a user-defined directory or to a default paging directory if one is not specified.
• Temporary paging of messages is always enabled and is controlled by the value set on the Message Buffer Size option. When the total size of non-pending, unpaged messages reaches this setting, a JMS server will attempt to reduce its memory usage by paging out messages to the paging directory.
• You can pause message production or message consumption operations on all the destinations hosted by a single JMS server, either programmatically with JMX or by using the Administration Console. For more information see, Controlling Message Operations on Destinations.
• JMS servers can be undeployed and redeployed without having to reboot WebLogic Server.

For more information on configuring JMS servers, see JMS Server Configuration.

JMS System Resource Modules

When you create a JMS module using the Administration Console, the WebLogic Scripting Tool (WLST), or WebLogic Management Extension (JMX) utilities, the WebLogic Server creates a JMS module file in the config\jms subdirectory of the domain directory, and adds a reference to the module in the domain's config.xml file as a JMSSystemResource element. This reference includes the path to the JMS module file and a list of target servers and clusters on which the module is deployed. The JMS module conforms to the weblogic-jmsmd.xsd schema, as described in JMS Schema.

JMS resources that you configure this way are considered system modules. JMS system modules are owned by the Administrator, who can delete, modify, or add similar resources at any time. System modules are globally available for targeting to servers and clusters configured in the domain, and therefore are available to all applications deployed on the same targets and to client applications. System modules are also accessible through JMX as a JMSSystemResourceMBean. The naming convention for JMS system modules is MyJMSModule-jms.xml.

Figure 2-2 shows an example of a JMS system module listing in the domain's config.xml file and the module that it maps to in the config\jms directory.

Figure 2-2 Reference from config.xml to a JMS System Module

 

The following basic configuration resources are defined as part of a system or packaged JMS module:

• Queue and topic destinations, as described in Queue and Topic Destination Resources.
• Connection factories, as described in Connection Factory Resources.
• Templates, as described in JMS Template Resources.
• Destination keys, as described in Destination Key Resources.
• Quota, as described in Quota Resources.

The following advanced clustered configuration resources are also defined as part of a system or packaged JMS module:

• Distributed destinations, as described in Configuring Distributed Destinations.
• Foreign servers, as described in Accessing Foreign Server Providers.
• JMS store-and-forward (SAF) configuration items, as described in Store-and-Forward (SAF) Service.

All other JMS-related resources must be configured by the administrator as domain configuration resources. This includes:

• JMS servers (required), as described in JMS Servers
• Store-and-Forward agents (optional), as described in Store-and-Forward (SAF) Service.
• Path service (optional), as described in Path Service.
• Messaging bridges (optional), as described in Messaging Bridges.
• Persistent stores (optional), as described in Persistent Stores

For more information about configuring JMS system modules, see Configuring JMS System Resources.

JMS Application Modules

JMS configuration resources can also be managed as deployable application modules, similar to standard J2EE descriptor-based modules. JMS Application modules can be deployed either with a J2EE application as a packaged module, where the resources in the module are optionally made available to only the enclosing application (i.e., application-scoped), or as a standalone module that provides global access to the resources defined in that module.

Application modules are generally created and packaged by an application developer and are then deployed, managed, and tuned by a WebLogic administrator. As discussed in Domain Configuration: System Resources vs. Application Resources, JMS application modules do not contain compiled Java programs as part of the package, enabling administrators or application developers to create and manage JMS resources on demand.

For more information about JMS application modules, see Configuring JMS Application Modules for Deployment.

Standalone JMS Modules

A JMS application module can be deployed by itself as a standalone module, in which case the module is available to the server or cluster targeted during the deployment process. JMS resources deployed in this manner can be reconfigured using the weblogic.Deployer utility or the Administration Console, but are not available through JMX or WLST. However, standalone JMS modules are available using the basic JSR-88 deployment tool provided with WebLogic Server plug-ins (without using WebLogic Server extensions to the API) to configure, deploy, and redeploy J2EE applications and modules to WebLogic Server.

For information about WebLogic Server deployment, see "Understanding WebLogic Server Deployment." For more information about preparing standalone JMS modules for deployment, see Deploying Standalone JMS Modules.

Packaged JMS Modules

JMS application modules can also be included as part of an J2EE Enterprise Application Archive (EAR), as a packaged module. Packaged modules are bundled with an EAR file or in an exploded EAR directory, and are referenced in the weblogic-application.xml deployment descriptor. The packaged module is deployed along with the Enterprise Application, and its resources can be be made available only to the enclosing application. Using packaged modules ensures that an application always has access to required resources and simplifies the process of moving the application into new environments. For more information about preparing packaged JMS modules for deployment, see Deploying JMS Modules That Are Packaged In an Enterprise Application.

JMS Schema

In support of the modular configuration model for JMS resources in this release, BEA provides a schema for WebLogic JMS objects: weblogic-jmsmd.xsd, where jmsmd stands for JMS module descriptor. When you create JMS resource modules (descriptors), the modules must conform to the schema. IDEs and other tools can validate JMS resource modules based on this schema.

The weblogic-jmsmd.xsd schema is available online at http://www.bea.com/ns/weblogic/90/weblogic-jmsmd.xsd.

Ownership of Configured JMS Resources

A key to understanding WebLogic JMS configuration and management is that who creates a JMS resource and how a JMS resource is created determines how a resource is deployed and modified. Both WebLogic administrators and programmers can configure JMS modules:

• WebLogic Administrators typically use the Administration Console or the WebLogic Scripting Tool (WLST) to create and deploy (target) JMS modules. These JMS modules are considered system resource modules. See JMS System Resource Modules for more details.
• Application developers typically create modules in an enterprise-level IDE or another development tool that supports editing XML descriptor files, then package the JMS modules with an application and pass the application to a WebLogic Administrator to deploy. These JMS modules are considered application modules. See JMS Application Modules for more details.

Comparing System and Application Module Capabilities

In contrast to system modules, deployed application modules are owned by the developer who created and packaged the module, rather than the administrator who deploys the module, which means the administrator has more limited control over deployed resources. When deploying an application module, an administrator can change resource properties that were specified in the module, but the administrator cannot add or delete resources. As with other J2EE modules, deployment configuration changes for a application module are stored in a deployment plan for the module, leaving the original module untouched.

Table 2-1 lists the JMS module types and how they can be configured and modified.

Table 2-1 JMS Module Types and Configuration and Management Options

Module Type	Created with	Dynamically Add/Remove Modules	Modify with JMX Remotely	Modify with Deployment Tuning Plan (non-remote)	Modify with Admin Console	Scoping	Default Sub-module Targeting
System	Admin Console or WLST	Yes	Yes	No	Yes - via JMX	Global and local	No
Packaged	IDE or XML editor	No - must be redeployed	No	Yes - via deployment plan	Yes - via deployment plan	Global, local, and application	Yes

For more information about preparing JMS application modules for deployment, see Configuring JMS Application Modules for Deploymentand Deploying Applications and Modules in Deploying Applications to WebLogic Server

JMS Interop Modules

A JMS interop module is a special type of JMS system resource module. It is created and managed as a result of a JMS configuration upgrade for this release, and/or through the use of WebLogic JMX MBean APIs from prior releases.

JMS interop modules differ in many ways from JMS system resource modules, as follows.

• The JMS module descriptor is always named as interop-jms.xml and the file exists in the domain's config\jms directory.
• Interop modules are owned by the system, as opposed to other JMS system resource modules, which are owned mainly by an administrator.
• Interop modules are targeted everywhere in the domain.
• The JMS resources that exist in a JMS interop module can be accessed and managed using deprecated JMX (MBean) APIs.
• The MBean of a JMS interop module is JMSInteropModuleMBean, which is a child MBean of DomainMBean, and can be looked up from DomainMBean like any other child MBean in a domain.

An interop module can also implement many of the new JMS features in this release, such as "Unit-of-Order" and "Quota". However, it cannot implement the following new features:

• Uniform Distributed Destinations
• JMS Store-and Forward

Caution: Use of any new feautures in the current release in a JMS interop module may possibly break compatibility with prior release JMX clients.

Persistent Stores

The WebLogic Persistent Store provides a built-in, high-performance storage solution for all subsystems and services that require persistence. For example, it can store persistent JMS messages or temporarily store messages sent using the Store-and-Forward feature. Each WebLogic Server instance in a domain has a default persistent store that requires no configuration and which can be simultaneously used by subsystems that prefer to use the system's default storage. However, you can also configure a dedicated file-based store or JDBC database-accessible store to suit your JMS implementation. For more information on configuring a persistent store for JMS, see "Using the WebLogic Persistent Store" in Configuring WebLogic Server Environments.

Store-and-Forward (SAF) Service

The SAF service enables WebLogic Server to deliver messages reliably between applications that are distributed across WebLogic Server instances. For example, with the SAF service, an application that runs on or connects to a local WebLogic Server instance can reliably send messages to a destination that resides on a remote server. If the destination is not available at the moment the messages are sent, either because of network problems or system failures, then the messages are saved on a local server instance, and are forwarded to the remote destination once it becomes available.

JMS modules utilize the SAF service to enable local JMS message producers to reliably send messages to remote JMS queues or topics. For more information, see "Understanding the Store-and-Forward Service" in Configuring and Managing WebLogic Store-and-Forward.

Path Service

The WebLogic Server Path Service is a persistent map that can be used to store the mapping of a group of messages to a messaging resource by pinning messages to a distributed queue member or store-and-forward path. For more information on configuring a path service, see Using the WebLogic Path Service.

Messaging Bridges

The Messaging Bridge allows you to configure a forwarding mechanism between any two messaging products, providing interoperability between separate implementations of WebLogic JMS, or between WebLogic JMS and another messaging product. The messaging bridge instances and bridge source and target destination instances are persisted in the domain's config.xml file. For more information, see "Understanding the Messaging Bridge" in Configuring and Managing WebLogic Messaging Bridge.

 

---

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: This section lists only the value-added features for prior releases. 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 Programming WebLogic JTA.
• File or database persistent message storage (both fully XA transaction capable), as described in "Using the WebLogic Persistent Store" in Configuring WebLogic Server Environments.
• Supports connection clustering using connection factories targeted on multiple WebLogic Servers, as described in Configuring WebLogic JMS Clustering.
• Distributed destinations that provide higher destination availability, load balancing, and failover support in a cluster, as described in "Using Distributed Destinations" in Programming WebLogic JMS.
• Failed server migration for manually restarting JMS servers on another WebLogic Server instance in a cluster, as described in Configuration Steps for JMS Service Migration.
• 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

• Message paging automatically kicks in during peak load periods to free up virtual memory.
• 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 Quota.
• Timer services available for scheduled message delivery, as described in "Setting Message Delivery Times" 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.
• Flexible expired message policies to handle expired messages, as described in Handling Expired Messages.
• Supports messages containing XML (Extensible Markup Language), as described in "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, as described in "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, as described in see "Enhanced 2EE Support for Using WebLogic JMS With EJBs and Servlets" 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, EJBs, 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.
• 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 Programming 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

• 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. Can also reference remote instances of WebLogic Server in another cluster or domain in the local JNDI tree. For more information, see Foreign Server Resources.
• Uses MDBs to transactionally receive messages from multiple JMS providers, as described in "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. Server-side applications use standard JMS APIs, but get automatic transaction enlistment, as described in 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 as described in "How to Configure the Tuxedo Queuing Bridge" in the WebLogic Tuxedo Connector Administration Guide.

Clustered WebLogic JMS

The WebLogic JMS architecture implements clustering of multiple JMS servers by supporting cluster-wide, transparent access to JMS destinations from any server in the cluster. Although WebLogic Server supports distributing JMS destinations and connection factories throughout a cluster, JMS topics and queues are still managed by WebLogic Server instances in the cluster.

For more information about configuring clustering for WebLogic JMS, see Configuring WebLogic JMS Clustering. For detailed information about WebLogic Server clustering, see Using WebLogic Server Clusters.