The JMS SAF (store-and-forward) feature builds on the WebLogic 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 SAF is transparent to JMS applications; therefore, JMS client code still uses the existing JMS APIs to access remote destinations.
The following sections explain:
|Note:||The WebLogic SAF client provides a mechanism whereby standalone clients can reliably send JMS messages to server-side JMS destinations, even when the SAF client cannot reach the JMS destination due to a network connection failure (e.g., a temporary blip or a network failure). While disconnected, messages sent by a SAF client are stored locally on the client and are forwarded to server-side JMS destinations once the client is reconnected. Seein Programming Stand Alone Clients.|
JMS configuration resources 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 Server to store-and-forward JMS messages. For more information on JMS modules, see in Configuring and Managing WebLogic JMS.
When configuring SAF resources for a JMS module, you need to configure the following resources in a JMS system module or application module:
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, temporarily stores messages in persistent storage. For more information on configuring SAF agents, see Understanding the Store-and-Forward Service.
JMS SAF 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.
A SAF destination (queue or topic) is a local representation of a JMS destination (queue or topic) in a JMS module that is associated with a remote server instance or cluster. Such remote destinations are 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 the 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.
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 SAF imported destination configurations.
Here’s an example of an URL used when a remote SAF context defines a single, remote managed server from which it will import standalone JMS destinations:
To import a distributed destination from a remote cluster you need to supply a comma-delimited list of DNS Server names or IP addresses. Here’s an example of an URL used when a remote SAF context defines a remote cluster from which it will import distributed destination members:
For more information about specifying the initial point of contact with a WebLogic Cluster, see “” in Programming WebLogic JNDI.
SAF error handling resources define the action to be taken when the SAF service fails to forward messages to a remote destination. SAF error handling resources are not required for imported SAF destinations, but are recommended as a best practice.
Configuration options include the following parameters:
Figure 3-1 illustrates how JMS messages that are produced to the
QueueSend queue in
Domain1Module-jms.xml module in Domain1 are forwarded by a SAF agent to the
QueueReceive queue in the
Domain2Module-jms.xml module in remote Domain2.
There are a number of ways to create SAF resources in a JMS module.
SAFErrorHandlingBeanmanagement MBeans to create and manage the SAF resources in JMS modules. For more information, see “ ” in Developing Custom Management Utilities with JMX.
These are the main steps when using the Administration Console to configure the SAF resources for forwarding JMS messages to remote destinations.
Use the following information to help you design and configure a WebLogic SAF for storing and forwarding JMS messages.
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:
A SAF application can also specify a delivery mode for each message, as follows:
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 “” 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 “” in Configuring and Managing WebLogic JMS.
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.
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 “” in the WebLogic Performance and Tuning Guide.
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.
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 “” in Configuring and Managing WebLogic JMS.
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 “” in Programming WebLogic JMS.
The following security measures apply to SAF imported destinations.
JMSXUserIDacross SAF boundaries. A JMSXUserID is a system generated property that identifies the user sending the message. JMSXUserID is defined in the .