The WebLogic SAF client provides a mechanism to enable standalone clients to 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 (for example, a temporary blip or a network failure). While a SAF client is disconnected, messages sent by that client are stored locally, and then are forwarded to server-side JMS destinations when the client is reconnected. See Reliably Sending Messages Using the JMS SAF Client in Developing Standalone Clients for Oracle WebLogic Server.
SAF Resources in a JMS Module
weblogic-jmsmd.xsdschema. JMS modules also provide the configuration of SAF resources that allow WebLogic Server to store and forward JMS messages. See Understanding JMS Resource Configuration in Administering JMS Resources for Oracle WebLogic Server.
The following topics explain how to configure the SAF resources for a JMS module:
Once your JMS SAF resources are configured, a configured SAF sending agent forwards messages to the receiving side; retransmits messages when acknowledgements do not come back in time; and, if message persistence is required, temporarily stores messages in persistent storage. 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.
Imported SAF 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.
Remote SAF 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:
<URL> t3://126.96.36.199:7001 </URL>
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:
<URL> t3://188.8.131.52:7001,184.108.40.206:7002,220.127.116.11:7003 </URL>
For more information about specifying the initial point of contact with a WebLogic Cluster, see Using WebLogic JNDI in a Clustered Environment in Developing JNDI Applications for Oracle WebLogic Server.
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. SAF error handling resources are not required for imported SAF destinations, but are recommended as a best practice.
Configuration options include the following parameters:
Error Handling Policy:
Discard – By default, expired messages are simply removed from the system. The removal is not logged and the message is not redirected to another location.
Log – Removes expired messages and writes an entry to the server log file indicating that the messages were removed from the system. You define the actual information that will be logged in the Log Format field.
Redirect – Moves expired messages from their current location into the Error Destination defined for imported SAF destinations.
Always-Forward – Ignores the SAF Default Time-to-Live value set on the imported destination and the expiration time set on the message, and so forwards the message to a remote destination even after it has expired. This options is useful for situations where an application has expiration policies set up on the remote destination, and they want that messages still go through the expiration process on the remote destination.
Log Format – If you selected the Log policy in previous step, use this field to define what information about the message is logged.
Error Destination – If you select the Redirect policy, use this field to select a local SAF destination where you want expired messages to be redirected.
The SAF JMS Picture
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.
Figure 3-1 Store-and-Forward JMS Messages
Description of "Figure 3-1 Store-and-Forward JMS Messages"
Creating JMS SAF Resources
The WebLogic Server Administration Console enables you to configure, modify, target, monitor, and delete JMS system modules and JMS system resources in your environment. For a road map of the JMS SAF resource configuration tasks, see Configure JMS SAF in the Oracle WebLogic Server Administration Console Online Help.
The WebLogic Scripting Tool (WLST) enables you to create and manage JMS servers and JMS system resources. See Using WLST to Manage JMS Servers and JMS System Module Resources in Administering JMS Resources for Oracle WebLogic Server.
WebLogic Java Management Extensions (JMX) enables you to access the
SAFErrorHandlingBeanmanagement MBeans to create and manage the SAF resources in JMS modules. See Overview of WebLogic Server Subsystem MBeans in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.
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. See Using JMS Module Helper to Manage Applications in Developing JMS Applications for Oracle WebLogic Server or
JMSModuleHelperin the Java API Reference for Oracle WebLogic Server.
Configuring Store-and-Forward Agents for JMS Destinations - Main Steps
Store-and-forward (SAF) agents are responsible for storing and forwarding messages between local sending and remote receiving endpoints. The JMS SAF feature builds on the WebLogic SAF service to provide highly available JMS message production. JMS SAF requires only a SAF agent that is configured with sending capabilities.
The main steps for using the WebLogic Server Administration Console to configure the SAF resources for forwarding JMS messages to remote destinations are:
- On the local sending side domain, configure a SAF sending agent, as described in Create Store-and-Forward agents in the Oracle WebLogic Server 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 Oracle WebLogic Server Administration
Console Online Help.
See JMS System Modules in Administering JMS Resources for Oracle WebLogic Server.
- 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 Oracle WebLogic Server 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 resources in the Oracle WebLogic Server 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 JMS system modules in the Oracle WebLogic Server 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:
- 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
When you design and configure WebLogic SAF for storing and forwarding JMS messages, you should give careful consideration the specific settings for quality-of-service, message delivery modes, message unit-of-order, transaction rollback, load balancing, and so on, that are appropriate for your operational environment.
The following topics explain how to design and configure WebLogic SAF for storing and 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. See Using Message Unit-of-Order in Developing JMS Applications for Oracle WebLogic Server.
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. See Using the WebLogic Path Service in Administering JMS Resources for Oracle WebLogic Server.
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 Compressing Messages in the Tuning Performance of Oracle WebLogic Server.
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. In general, messages to a remote distributed destination are stored and forwarded using the same model as messages that are forwarded to remote standalone destinations. However, load balancing is handled differently than other distributed destinations, see SAF Load Balancing.
See Configuring Distributed Destinations in Administering JMS Resources for Oracle WebLogic Server.
SAF Load Balancing
Load balancing determines the message route taken by a message when it is sent to an imported SAF destination or forwarded to a remote destination. There are two situations to consider when configuring WebLogic Server to determine a message route for SAF messages:
Sending Messages to an Imported Destination
Messages sent by a JMS client are load balanced to an imported destination using one of the following message routes:
For a single SAF agent, load balancing is handled in the same manner as sending to a regular JMS destination.
For multiple SAF agents, the imported destination behaves similarly to a distributed destination. The connection factory load balancing setting load balances messages among the SAF agents. See Connections and ConnectionFactories.
SAF Agent Forwarding Messages to a Remote Destination
When forwarding messages, each SAF agent forwards messages independently. In this case, SAF agents forwarding messages are not load balanced, the message route is determined by the destination type:
If the destination is a regular non-distributed destination, there is no load balancing or fail over.
If the target destination is a distributed destination, the message route and failover behavior is determined by the configuration of the SAF agent for a non-Unit -of-Order
Exactly-oncemessage, where the message is either
non-persistentwith a QoS of
ExactlyOnce. The message route is determined by round-robin load balancing messages among a list of available distributed destination members. If a member becomes unavailable, that member is removed dynamically from the list. If a member becomes available, it is dynamically added to the list.
From a single message perspective, there is no failover. If the SAF agent fails to deliver a message to a member destination, there is no attempt to redeliver to another member; instead, the SAF agent periodically retries delivery to the original member. The message "sticks" to its target member to preserve the
For all other message types, the message route is determined by the settings of the default connection factory (
Default JMS connection factory settings cannot be changed or overridden.
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.
See Using Temporary Destinations in Developing JMS Applications for Oracle WebLogic Server.
Securing SAF Destinations
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 Oracle WebLogic Server Administration Console Online Help:
The SAF service does not preserve a message's
JMSXUserIDacross SAF boundaries. A
JMSXUserIDis a system generated property that identifies the user sending the message.
JMSXUserIDis defined in the JMS Specification, published at
Connections and ConnectionFactories
JMS messages route from a client, through its connection host, and then on to a JMS destination instance hosted by a WebLogic JMS server or SAF Agent. Clients use JNDI to obtain a connection factory, and then use the connection factory to create a JMS connection to WebLogic. Each connection instance is pinned to a particular WebLogic server (the "connection host").
A connection factory defines configuration parameters for a client connections, and must be hosted on the same server or cluster as the client's destinations. WebLogic JMS provides default connection factories, and custom connection factories. Default connection factories are not configurable, while custom connection factories are configurable but cannot be configured with the same JNDI name as a default connection factory. A connection factory can be hosted on one or more servers in a WebLogic cluster:
Default connection factories are always hosted on every server in their cluster.
Custom connection factory hosts are set based on their target configuration.
A client's connection factory instance is actually a WebLogic RMI replica-aware stub that implicitly keeps track of all active servers that host the connection factory. As servers become available and unavailable in a cluster, the connection factory instance is automatically updated with this information. When a client creates a connection using a connection factory instance, one of these servers becomes the client's connection host, and the connection host stays the same for the life of the connection.
There are two connection factory settings that tune distributed and imported destination producer load balancing behavior:
Server Affinity— Specifies whether send requests load balance only among members local to the connection host when present, instead of all distributed or imported destination members. Defaults to enabled.
Load Balancing—Specifies whether or not non-anonymous producers are load-balanced among members on a per-call basis. If enabled, messages are load-balanced across all members on every
publish(). If disabled, a load-balance decision is made on the
publish()and all subsequent messages are sent to the same destination. Defaults to enabled.
Server Affinity and
Load Balancing are ignored when:
producing to regular destinations.
used with Unit-of-Order and Unit-of-Work messages to honor a strict ordering quality of service.