Configuring and Managing WebLogic Store-and-Forward

Configuring SAF for JMS Messages

The JMS Store-and-Forward feature builds on the WebLogic Store-and-Forward (SAF) service to provide highly-available JMS message production. For example, a JMS message producer connected to a local server instance can reliably forward messages to a remote JMS destination, even though that remote destination may be temporarily unavailable when the message was sent. JMS Store-and-forward is transparent to JMS applications; therefore, JMS client code still uses the existing JMS APIs to access remote destinations.

The following sections explain:

SAF Resources In a JMS Module

In this release, JMS configurations, such as queue, topics, 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-jmsmd.xsd schema. JMS modules also provide the configuration of SAF resources that allow WebLogic JMS to store-and-forward JMS messages. For more information on JMS modules, see "Understanding JMS Resource Configuration" in Configuring and Managing WebLogic JMS.

Once your JMS SAF resources are configured, a configured SAF sending agent forwards messages to the receiving side, re-transmits messages when acknowledgements do not come back in time, and, if message persistence is required, a stores messages to a persistent storage.

JMS store-and-forward is transparent to JMS applications. Existing JMS applications can take advantage of this feature without any code changes. In fact, you only need to configure imported JMS destinations within JMS modules, which then associate remote JMS destinations to local JNDI names. JMS client code still uses the existing JMS APIs to access the imported destinations. JMS store-and-forward is only for message production; therefore, JMS clients still need to consume messages directly from imported destinations.

When configuring SAF resources for a JMS module, you need to configure the following resources:

SAF Destinations

A SAF destination is a representation of a JMS queue or topic in a remote server instance or cluster that is imported into the local cluster or server instance, so that the local server instance or cluster can send messages to the remote server instance or cluster. All JMS destinations are automatically exported by default, unless the Export SAF Destination parameter on a destination is explicitly disabled.

A collection of imported SAF destinations is called SAF imported destinations. Each collection of imported destinations is associated with a SAF remote context. They can also share the same JNDI prefix, time-to-live default (message expiration time), and SAF error handling object.

When a JMS producer sends messages to a SAF destination, these messages are stored on the SAF destination for future delivery. A SAF agent forwards the messages to the remote JMS destination (that the imported destination represents) when the destination is reachable, using the SAF Remote Context.

SAF Remote Context

A remote SAF context defines the URL of the remote server instance or cluster where the JMS destination is exported from. It also contains the security credentials to be authenticated and authorized in the remote cluster or server. A SAF remote context configuration is required to use imported destinations. A remote SAF context can be re-used by multiple imported destination configurations.

SAF Error Handling

SAF error handling resources define the action to be taken when the SAF service fails to forward messages to a remote destination. Configuration options include an Error Handling Policy (Redirect, Log, Discard, or Always-Forward), a Log Format, and sending Retry parameters. SAF error handling resources are not required for imported destinations, but are recommended as a best practice.

Creating JMS SAF Resources

There are a number of ways to create SAF resources in a JMS module.

The WebLogic Server Administration Console enables you to configure, modify, target, monitor, and delete JMS system modules and JMS resources in your environment. For a road map of the JMS SAF resource configuration tasks, see "Create Store-and-Forward Agents" in the Administration Console Online Help.
The WebLogic Scripting Tool (WLST) enables you to create and manage JMS servers and JMS system resources. For more information, see "Using WLST to Manage JMS Servers and JMS System Resources" in Configuring and Managing WebLogic JMS.
WebLogic Java Management Extensions (JMX) enables you to access the JMSSystemResourceMBean and JMSRuntimeMBean MBeans to create and manage JMS destinations and connections. For more information see "Overview of WebLogic Server Subsystem MBeans" in Developing Custom Management Utilities with JMX.
JMS Module Helper Extension APIs enable you to locate JMS runtime MBeans, as well as methods to manage (locate/create/delete) JMS system module configuration resources in a given module. For more information, see "Using the JMS Module Helper to Manage Applications" in Programming WebLogic JMS or the JMSModuleHelper Javadoc.

Main Steps to Configure SAF In a JMS Module

These are the main steps when using the Administration Console to configure the SAF resources for forwarding JMS messages to remote destinations.

On the sending side, configure a SAF sending agent, as described in "Create Store-and-Forward agents" in the Administration Console Online Help.

If necessary, create JMS system modules on both the sending and receiving side to contain your JMS destination resources, as described in "Configure JMS system modules" in the Administration Console Online Help.

For more information, see "JMS System Resource Modules" in Configuring and Managing WebLogic JMS.

In the sending side JMS module, configure a new remote SAF context resource to define the URL of the receiving side where the remote queue or topic is exported from. For step-by-step instructions, see "Create SAF remote contexts" in the Administration Console Online Help.

In the sending side JMS module, optionally configure a SAF error handling configuration to define the action to be taken when the SAF service fails to forward messages to a remote destination. For step-by-step instructions, see "Create SAF error handling" in the Administration Console Online Help.

In the sending-side JMS module, configure a SAF imported destination and associate it with the remote SAF context and SAF error handling resources you created in the module. For step-by-step instructions, see "Create SAF imported destinations" in the Administration Console Online Help.

Reopen the SAF imported destination you created, and configure a SAF queue and/or SAF topic to represent the remote queue and/or topic on the receiving side. The SAF queue or topic uses the same JNDI name as the remote queue or topic. For step-by-step instructions, see:

"Create SAF Queues" in the Administration Console Online Help
"Create SAF Topics" in the Administration Console Online Help

By default, all JMS destinations are available for access by SAF imported destinations. However, you can selectively specify not to export a destination by changing the destination's SAF Export Policy value to None. This way, remote users cannot send messages to a destination using store-and-forward.

Designing SAF for JMS Messages

Use the following information to help you design and configure a WebLogic SAF for forwarding JMS messages.

Selecting a Quality-of-Service (QOS) Level

Persistent JMS messages are always forwarded with Exactly-Once QOS provided by the SAF service. For non-persistent messages, three different QOS levels can be defined on imported SAF queues and topics:

Exactly-once—The highest QOS guarantees that a message is forwarded to the remote endpoint once and only once. With Exactly-once, messages survive server crashes and network down time, while guaranteeing one occurrence of each message at the endpoint.
At-least-once—Guarantees that a message is forwarded to the remote endpoint at least once, but with the possibility of duplicates. With At-least-once, multiple copies of a message might show up on the remote endpoint because of network failures or server crashes that occur when the message is in transit.
At-most-once—The lowest QOS guarantees that each message is forwarded to the remote endpoint only once, if at all. It does not guarantee that a message is forwarded to the endpoint. With At-most-once, messages may get lost because of network failures or server crashes. No duplicate messages will reach the endpoint.

How SAF Handles Delivery Modes

A SAF application can also specify a delivery mode for each message, as follows:

Persistent messages are saved in the persistent store on the sending side until they are successfully forwarded to and acknowledged by the receiving side.
Non-persistent messages are kept in memory on the sending side until the receiving side acknowledges them. This means that non-persistent messages can be lost if the sending side crashes.

Using Message Unit-of-Order

Within a cluster, a JMS producer can be associated with a message unit-of-order, which enables a stand-alone message producer, or a group of producers acting as one, to group messages into a single unit with respect to the processing order. For more information about JMS Unit-of-Order, see "Using Message Unit-of-Order" in Programming WebLogic JMS.

Imported SAF destinations can use either a Hash Map or a Path Service to group ordered messages in a cluster. However, as a best practice, you should configure a Path Service. The Path Service is a persistent map that can be used to store the mapping of a group of messages to a messaging resource such as a SAF agent. For more information about configuring a Path service, see "Using the WebLogic Path Service" in Configuring and Managing WebLogic JMS.

Transactional Messages

If an application message is in a transaction, saving the message in the persistent storage becomes part of the user transaction to preserve Exactly-Once semantics.

In particular, the message will be removed from the persistent storage as part of the transaction rollback if the application decides to rollback the transaction. However, forwarding is not part of the application transaction. The sending agent will not forward a transactional message until the transaction commits. Within a transaction, message ordering is preserved based on when the messages are sent.

Message Compression Across SAF Boundaries

JMS store-and-forward can compress messages when they are forwarded between different clusters. A message compression threshold can be set programmatically using a JMS API extension to the WLMessageProducer interface, or administratively by either specifying a Default Compression Threshold value on a connection factory or on a JMS remote SAF context.

For more information, on using message compression for JMS messages, see "Tuning WebLogic JMS" in Configuring and Managing WebLogic JMS.

When an uncompressed message that exceeds the remote SAF context's compression threshold value is about to be forwarded across the SAF boundary, it is compressed. The message stays compressed until it is received by the remote endpoint. If the message has already been compressed when it crosses the SAF boundary because the compression is turned on the connection factory, the message will stay compressed across SAF boundary no matter if the SAF compression is triggered or not.

SAF to a Distributed Destination

A remote endpoint can be a distributed destination. Messages to a remote distributed destination are stored and forwarded in the same way as messages that are forward to remote standalone destinations. The SAF sending agent routes the messages to a member of the distributed destination the same way as we do currently. For more information on configuring distributed destinations, see "Configuring Distributed Destinations" in Configuring and Managing WebLogic JMS.

Using the JMSReplyTo Field with SAF

Generally, JMS applications can use the JMSReplyTo header field to advertise its temporary destination name to other applications. However, the use of temporary destinations with a JMSReplyTo field is not supported for SAF imported destinations.

For more information on using JMS temporary destinations, see "Using Temporary Destinations" in Programming WebLogic JMS.

Securing JMS Messages

The following security measures apply to SAF imported destinations.

Secure roles and policies can be set on imported SAF queues and topics. For more information on configuring roles and policies, see the following sections in the Administration Console Online Help:

The SAF service does not preserve a message's JMSXUserID across SAF boundaries. A JMSXUserID is a system generated property that identifies the user sending the message. JMSXUserID is defined in the JMS Specification.