2 Understanding JMS Resource Configuration

This chapter briefly reviews the basic 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

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, available at http://www.oracle.com/technetwork/java/jms/index.html, 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 that share 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 JMS for Oracle WebLogic Server.

WebLogic JMS Architecture and Environment

Figure 2-1 illustrates the WebLogic JMS architecture.

Figure 2-1 WebLogic JMS Architecture

Description of Figure 2-1 follows
Description of "Figure 2-1 WebLogic JMS Architecture"

In Figure 2-1, A1 and B1 are connection factories, and B2 is a queue.

The major components of the WebLogic JMS architecture include:

  • A JMS server is an environment-related configuration entity that acts as management container for JMS queue and topic resources defined within JMS modules that are targeted to specific that JMS server. 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. You can configure one or more JMS servers per domain, and a JMS server can manage one or more JMS modules. For more information, see Overview of JMS Servers.

  • JMS modules contain configuration resources, such as standalone queue and topic destinations, distributed destinations, and connection factories, and are defined by XML documents that conform to the weblogic-jms.xsd schema. For more information, see What Are JMS Configuration Resources?

  • 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

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 information and application-related information. Examples of environment-related information 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 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.

Examples of application-related definitions that are independent of the domain environment are the various Java EE application components configurations, such as EAR, WAR, JAR, RAR files, and 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.

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 life cycle and tuning, any modification to these applications must be completed by the application development team.

What Are JMS Configuration Resources?

JMS configuration resources, such as destinations and connections factories, are stored outside of the WebLogic domain as module descriptor files, which are defined by XML documents that conform to the weblogic-jms.xsd schema. JMS modules do not include JMS server definitions, which are stored in the WebLogic domain configuration file, as described in Overview of JMS Servers.

You create and manage JMS resources either as system 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 Java EE modules and can be deployed either with a Java EE application (as a packaged resource) or as stand-alone modules that can be made globally available. See Overview of JMS Modules.

Overview of JMS Servers

JMS servers are environment-related configuration entities that act as management containers for destination 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.

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.

JMS Server Behavior in WebLogic Server 9.x and Later

The current release of JMS server behavior differs in certain respects from the behavior in pre-9.x releases:

  • Because destination resources are encapsulated in JMS modules, they are not nested under JMS servers in the configuration file. However, a sub-targeting relationship between JMS servers and destinations is maintained because each standalone destination resource within a JMS module is always targeted to a single JMS server. This way, JMS servers continue to manage persistent messages, durable subscribers, message paging, and, optionally, quotas for their targeted destinations. Multiple JMS modules can be targeted to each JMS server in a domain.

  • JMS servers support the default 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 for backward compatibility.)

  • JMS servers support an improved message paging mechanism. For more information on message paging, see Performance and Tuning for Oracle WebLogic Server.

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

  • Non-persistent messages published to a Uniform Distributed Topic member that is offline are saved and made available when the member comes back online.

    In releases prior to 9.0, if you did not configure a persistent store for a JMS server or if there was a persistent store defined and storedEnabled=false was set on the distributed topic (DT) member, non-persistent messages were dropped and not made available when the DT member came back online. If your application depends on dropping these messages, you can approximate similar behavior by setting the Delivery Timeout value for a server to a very low value. This will allow the messages to be disregarded before an offline DT member would come back online. New applications developed on WebLogic Server releases and higher can use partitioned distributed topics with message-driven beans (MDBs) as message consumers to provide a similar capability. See "Developing Advanced Pub/Sub Applications" in Programming JMS for Oracle WebLogic Server.

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

Overview of JMS Modules

JMS modules are application-related definitions that are independent of the domain environment. You create and manage JMS resources either as system modules or as application modules. JMS system modules are typically configured using the Administration Console or the WebLogic Scripting Tool (WLST), which adds a reference to the module in the domain's config.xml file. JMS application modules are a WebLogic-specific extension of Java EE modules and can be deployed either with a Java EE application (as a packaged resource) or as stand-alone modules that can be made globally available.

The main difference between system modules and application modules comes down to ownership. System modules are owned and modified by the WebLogic administrator and are available to all applications. Application modules are owned and modified by the WebLogic developers, who package the JMS resource modules with the application's EAR file.

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 stand-alone JMS module, and without extensive manual JMS reconfiguration.

These sections describe the different types of JMS module and the resources that they can contain:

JMS System Modules

WebLogic Administrators typically use the Administration Console or the WebLogic Scripting Tool (WLST) to create and deploy (target) JMS modules, and to configure the module's configuration resources, such as queues, and topics connection factories.

JMS modules that you configure this way are considered system modules. JMS system modules are owned by the Administrator, who can at any time add, modify, or delete resources. 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.

When you create a JMS system module 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 system module file and a list of target servers and clusters on which the module is deployed.

The JMS module conforms to the weblogic-jms.xsd schema, as described in JMS Schema. System modules are also accessible through WebLogic Management Extension (JMX) utilities, 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

Description of Figure 2-2 follows
Description of "Figure 2-2 Reference from config.xml to a JMS System Module"

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

JMS Application Modules

JMS configuration resources can also be managed as deployable application modules, similar to standard Java EE descriptor-based modules. JMS Application modules can be deployed either with a Java EE 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 developers typically create application 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, manage, and tune.

As discussed in Domain Configuration, 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 configuring JMS application modules, see Chapter 5, "Configuring JMS Application Modules for Deployment."

Comparing JMS System Modules and Application Modules

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:

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 Java EE 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


Admin Console or WLST




Yes – via JMX

Global and local



IDE or XML editor

No – must be redeployed


Yes – via deployment plan

Yes – via deployment plan

Global, local, and application


For more information about preparing JMS application modules for deployment, see Chapter 5, "Configuring JMS Application Modules for Deployment" and "Deploying Applications and Modules with weblogic.deployer" in Deploying Applications to Oracle WebLogic Server.

Configurable JMS Resources in Modules

The following configuration resources are defined as part of a system module or an application module:

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

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

JMS Schema

In support of the modular configuration model for JMS resources, Oracle provides a schema for WebLogic JMS objects: weblogic-jms.xsd. 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-jms.xsd schema is available online at http://xmlns.oracle.com/weblogic/weblogic-jms/1.2/weblogic-jms.xsd.

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.

A JMS interop module can also implement many of the WebLogic Server 9.x or later features, such as message unit-of-order and destination quota. However, it cannot implement the following WebLogic Server 9.x or later features:

  • Uniform distributed destination resources

  • JMS store-and forward resources


    Use of any new features in the current release in a JMS interop module may possibly break compatibility with JMX clients prior to WebLogic Server 9.x.

Other Environment-Related System Resources for WebLogic JMS

These environment-related resources must be configured by the administrator as domain configuration resources in order to be accessible to JMS Servers and JMS modules.

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 Server Environments for Oracle WebLogic Server.

JMS Store-and-Forward (SAF)

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 "Configuring SAF for JMS Messages" in Configuring and Managing Store-and-Forward for Oracle WebLogic Server.

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 the Messaging Bridge for Oracle WebLogic Server.