10 Best Practices for JMS Beginners and Advanced Users

This chapter provides advice and best practices for beginning JMS users as well as advanced JMS users. Topics include targeting, integration options, understanding URLs, high availability (HA), and tuning.

This chapter includes the following sections:

Configuration Best Practices

The following sections outline a basic procedure on how to configure JMS applications:

  1. Configure JMS Servers and Persistent Stores

  2. Configure a JMS Module

  3. Configure JMS Resources

  4. Configure SAF Agents, Stores, and Imported Destination

Configure JMS Servers and Persistent Stores

Before you start configuring JMS servers and persistent stores, consider the following:

  • Destinations, connection factories, and other JMS resources are configured separately from their host JMS servers and persistent stores. The best practice steps for configuring JMS resources will be described later.

  • If you plan to leverage WebLogic distributed destinations, you will need to configure a WebLogic cluster with a JMS server and a custom persistent store on each WebLogic server in the cluster. WebLogic JMS distributed destination features require a working WebLogic cluster.

  • As a best practice, target the JMS service artifacts to a cluster, when possible, to easily achieve both dynamic scalability and high availability of the resources. See Simplified JMS Cluster and High Availability Configuration.

  • Migratable targets are only supported with clusters. If you are not using a cluster, you may want to reconsider and use a cluster of size one. This enables the use of migratable targets, and migratable targets enable a useful restart-in-place capability as mentioned below. This also helps "future-proof" your application, as it simplifies the process of expanding from a single server to multiple servers.


    For high availability, Oracle recommends targeting the JMS artifacts to a cluster along with appropriate high availability configuration settings instead of using Migratable Targets.

Use the following steps to configure JMS servers, SAF agents, Path Service and persistent stores in configured clusters:

  1. Create a custom store on each WebLogic server that will host a JMS server. If there is already a custom store on a WebLogic server, you can skip this step as its usually more convenient and improves performance for services to share a store. (Why use a custom store? Custom stores provide more flexibility in tuning and administration. In addition, the default file store is not migratable -- only custom stores are migratable.)

  2. Target each store to the cluster. If you have decided not to use a cluster, target each store directly to its host server.

    It is recommended to use cluster-targeted JMS artifacts along with high availability settings on the store instead of using Migratable Targets. See Chapter 5, "Simplified JMS Cluster and High Availability Configuration".

  3. Configure a JMS server on each WebLogic server. Configure the JMS server to reference the store that was created in step 1. Target the JMS server to the same target that was used for the store. Multiple JMS servers can reference the same store.

  4. Configure message count quotas on each JMS server. There is no default quota, so configuring one helps protect against out-of-memory conditions. Rule of thumb: conservatively assume that each message consumes 512 bytes of memory even if it is paged out.

  5. Although JMS paging is enabled by default, verify that the default behavior is valid for your environment.

Configure a JMS Module

A homogenous set of JMS servers is a single cluster-targeted JMS server with its distribution-policy set to Distributed or a single JMS server with its distribution-policy set to Singleton, or a set of similarly configured JMS servers that each host the same distributed destination. Configure a JMS module and a single associated subdeployment for each homogenous set of JMS servers:

  1. Create a system module. Target it to a single cluster (if using clusters) or a single WebLogic Server instance. You must always target the module even when leveraging subdeployments.


    • It is almost always preferred to use system modules instead of deployable application modules. System modules can be created using the WebLogic Server Administration Console, the JMX API (Java MBeans), or WLST, there is no equivalent tooling for deployable modules. The only way to modify deployable modules is to manually edit the XML and redeploy.

    • It is always preferred to use system module configuration instead of JMS resource definitions. Configuring connection factories and destinations using a system module is generally much more flexible, maintainable, and portable than hard coding configuration in an application.

  2. Create exactly one subdeployment per module. Subdeployments are sometimes referred to as "advanced targeting" on the WebLogic Server Administration Console. A single subdeployment aids simplicity - it's much easier for third parties to understand the targeting, and it reduces the chances of making configuration errors. If a single subdeployment is not sufficient, create two modules.

  3. Populate the subdeployment only with JMS servers - not WebLogic servers. Only include the JMS servers that you wish to host destinations. This ensures that when the JMS resources are configured, they are targeted to the correct JMS servers.

    For modules that support non-distributed destinations, the subdeployment must reference a single cluster-targeted JMS server with its distribtution-policy set to Singleton or to a single JMS server targeted to a Migratable Target, or to a single JMS server targeted to a WebLogic Server.

    For modules that support subdeployments with distributed destinations, always choose a single cluster-targeted JMS server with its distribution-policy set to Distributed.

    If you have a mix of distributed and non-distributed destinations, use two modules each with its own subdeployment.

Configure JMS Resources

Configure your JMS resources and target them properly.

  1. Create destinations and target them to a single subdeployment (called "advanced targeting" on the console). Note that only distributed destinations can be targeted to a subdeployment target that resolves to multiple JMS servers. If you have a mix of distributed destinations, stand-alone destinations, and imported destinations, use two modules each with its own subdeployment. See Targeting Best Practices.

  2. Create and use custom connection factories instead of using default connection factories. Default connection factories are not tunable.

    In most cases, you can use default targeting with connection factories as default targeting causes the resource to inherit the module's target. For connection factories that are only used by remote clients, use the module's subdeployment target.

  3. Set the connection factory unmapped resource reference mode to FailSafe instead of leaving it as its default value ReturnDefault. The value FailSafe ensures that applications do not use unmapped resource references. For more information, see "Change in Behavior of Unmapped Connection Factory Resources" in Release Notes for Oracle WebLogic Server.

    For more information about setting the unmapped resource reference mode, see Specifying the Unmapped Resource Reference Mode for Connection Factories.

Configure SAF Agents, Stores, and Imported Destination

SAF agents, their stores, and their imported destinations should follow the same best practices as JMS servers, their stores, and JMS destinations. Avoid targeting a SAF agent at a cluster, as such a SAF agent is not be able to use migratable targets.

Targeting Best Practices

Oracle recommends the following targeting guidelines for JMS resources:

  • Avoid default targeting, WebLogic server targeting, and cluster targeting with destinations. Instead use advanced targeting (subdeployment targeting) for destinations and ensure that the subdeployment references only JMS servers or SAF agents.This applies to all destination types, including non-distributed, distributed, and imported.

    Even if the current JMS Servers or SAF Agents in your domain are only used for your specific application, this is a best practice because:

    • New JMS Servers or SAF Agents that are unrelated to your current application can be introduced by other applications, web services, or 3rd-party products.

    • In the future, your application may require different destinations and different JMS Servers or SAF Agents for scalability or management purposes.

  • Always use advanced targeting when configuring Web Services deployments and error queues, this includes both development and production environments.

  • To use an error destination within a distributed queue, it must be targeted to the same subdeployment as its parent destination.

  • In most cases, you can use default targeting with connection factories as default targeting causes the resource to inherit the module's target. For connection factories that are only used by remote clients, use the module's subdeployment target.

  • Although it does not support all WebLogic JMS features (such as Unit-of-Order, singleton destinations, and Store-and-Forward Agents), consider using Clustered JMS Servers to simply configuration and allow applications to more easily scale WebLogic Messaging resources. See Simplified JMS Cluster and High Availability Configuration.

Integration and Multi-Domain Best Practices

The following section provides best practice information for integration and multi-domain environments using WebLogic Server:

  • For server side applications that communicate with destinations in a remote WebLogic cluster or server, see "Integrating Remote JMS Providers" in Developing JMS Applications for Oracle WebLogic Server.

  • Interoperating WebLogic Server domains have the following restrictions:

    • Domain names must be unique.

    • WebLogic server names must be unique, even if they are in two different domains.

    • JMS server names must be unique, even if they are in two different domains.

    • Interoperating domains may have special Security considerations.

Understanding WebLogic JMS Client Options

For client applications (applications that have a runtime environment independent of WebLogic Server) there are multiple JMS client options, including: Java, .NET, and C clients. See "JMS Clients" in Developing Stand-alone Clients for Oracle WebLogic Server.


WebLogic JMS clients do not directly support foreign transaction managers. Use the WebLogic TM if possible. For advanced users, the transaction subsystem Interposed Transaction Manager feature may be used as an XA resource.

Understanding WebLogic URLs

Applications that are communicating with a remote WebLogic Server instance or cluster must specify a URL when creating their JNDI InitialContext objects and/or setting application attributes in order to connect to a server or a cluster.

  • Do not specify URLs for applications that run on the same server or cluster as their JMS resources. When an initial context is created without specifying URLs, it automatically references the local server or cluster JNDI.

  • If a URL resolves to multiple addresses, WebLogic Server clients will randomly select an address in the list to start with and then automatically try each address in turn until one succeeds.

  • In production systems, consider using DNS round robin or a hardware load balancer for initial hostname resolution rather than using the multiple host/port URL notation shown in URL syntax.

URL syntax

The WebLogic URL syntax is:



  • address = hostlist : portlist

  • hostlist = hostname [,hostname]...

  • portlist = portrange [+portrange]...

  • portrange = port [-port]

Use port-port to indicate a port range, and + to separate multiple port ranges. For example, a simple address is typically something like t3://hostA:7001; the address t3://hostA,hostB:7001-7002 is equivalent to the following addresses.

  • t3://hostA,hostB:7001+7002

  • t3://hostA:7001-7002,hostB:7001-7002

  • t3://hostA:7001+7002,hostB:7001+7002

  • t3://hostA:7001,hostA:7002,hostB:7001,hostB:7002

Strict Message Ordering Best Practices

If strictly ordered message processing is required, then application design and configuration needs to carefully take this requirement into account.

The simplest and most capable option is to leverage the WebLogic JMS Unit-of-Order feature. This option normally requires minimal or even no changes to applications, plus it works with distributed destinations, scheduled messages, delayed messages, transactions, and store-and-forward. See "Using Message Unit-of-Order" in Developing JMS Applications for Oracle WebLogic Server.

High Availability Best Practices

If High Availability (HA) or scalability is a concern, develop applications so that they leverage clustered WebLogic features. This approach is best taken in the early configuration and application design stage as it is usually difficult process to change a non-clustered application into a clustered application.

In WebLogic JMS, a message is only available if its host JMS server for the destination is running. If a message is in a central persistent store, the only JMS server that can access the message is the server that originally stored the message. WebLogic includes features for automatically restarting and/or migrating a JMS server after a failure. It also includes features for clustering (distributing) a destination across multiple JMS servers within the same cluster.

HA is normally accomplished using both:

  • Distributed destinations

  • HA Servers/Services. JMS Servers can be automatically restarted and/or migrated using either Whole Server Migration or Automatic Service Migration.

Distributed Queues vs Distributed Topics

Distributed queues are generally fairly easy to apply to an arbitrary clustered queueing use case. Distributed topics are best applied when:

  • Subscribers are non-durable, or

  • You use MDBs to subscribe (direct durable subscribers have limitations and may require use of sophisticated extensions).

See "Configuring and Deploying MDBs Using JMS Topics" in Developing Message-Driven Beans for Oracle WebLogic Server and "Using Distributed Destinations" in Developing JMS Applications for Oracle WebLogic Server.

JMS Performance and Tuning

The following section provides a link to a checklist of items to consider when tuning WebLogic JMS: