The following sections describe how to configure and use the JMS SAF Client feature to reliably send JMS messages from standalone JMS clients to server-side JMS destinations:
The JMS SAF Client feature extends the JMS store-and-forward service introduced in WebLogic Server 9.0 to standalone JMS clients. Now JMS clients can reliably send messages to server-side JMS destinations, even when the client cannot reach a destination (for example, due to a temporary network connection failure). While disconnected from the server, messages sent by a JMS SAF client are stored locally on the client file system and are forwarded to server-side JMS destinations when the client reconnects.
The JMS SAF client feature consists of two main parts: the JMS SAF client implementation that writes messages directly to a client-side persistent store on the local file system and a SAF forwarder that takes the messages written to the store and sends them to a WebLogic Server instance. There is also an optional
SAFClient initialization API in
weblogic.jms.extensions that allows JMS SAF clients to turn the SAF forwarder mechanism on and off whenever necessary. For more information, see The JMS SAF Client Initialization API.
|Note:||For information on the server-side WebLogic JMS SAF for reliably sending JMS messages to potentially unavailable destinations, seein Configuring and Managing WebLogic Store-and-Forward.|
No configuration is required on the server-side, but running client-side SAF does require some configuration on each client. These sections describe how to configure a JMS client to use client-side SAF.
Each client machine requires a JMS SAF client configuration file that specifies information about the server-side connection factories and destinations needed by the JMS SAF client environment to operate. You generate the JMS SAF client configuration file from a specified JMS module’s configuration file by using the
ClientSAFGenerate utility bundled with your WebLogic installation.
ClientSAFGenerate utility creates entries for all connection factories, stand-alone destinations, and distributed destinations found in the source JMS configuration file, as described in Steps to Generate a JMS SAF Client Configuration File from a JMS Module. The generated file defines the connection factories and imported destinations that the JMS SAF client will interact with directly through the initial JNDI context described in Modify Your JMS Client Applications To Use the JMS SAF Client’s Initial JNDI Provider. However, the generated file will not contain entries for any foreign JMS destinations or SAF destinations in server-side JMS modules. Furthermore, only JMS destinations with their SAF Export Policy set to
All are added to the file (the default setting for destinations).
The JMS SAF client XML file conforms to the WebLogic Server 9.2
weblogic-jmsmd.xsd schema for JMS modules and contains the root element
weblogic-jmsmd.xsd schema contains several top-level elements that correspond to SAF-related features from WebLogic Server 9.2, as described in Valid SAF Elements for JMS SAF Client Configurations.
The top-level elements in the file describe the connection factory and imported destination elements that the JMS SAF client will interact with directly. The SAF sending agent, remote SAF context, and SAF error handling elements describe the function of the SAF forwarder. The persistent store element is used by both the JMS SAF client API and the SAF fowarder.
ClientSAFGenerate utility to generate a JMS SAF client configuration file from a JMS module configuration file in a WebLogic domain. You can also generate a configuration file from an existing JMS SAF client configuration file, as described in ClientSAFGenerate Utility Syntax.
These steps demonstrate how to use the
ClientSAFGenerate utility to generate a JMS SAF client configuration file from the examples-jms.xml module file bundled in WebLogic Server installations.
> java weblogic.jms.extensions.ClientSAFGenerate -url http://10.61.6.138:7001 -username weblogic -moduleFile examples-jms.xml -outputFile d:\temp\
Table 6-1 explains the valid
SAFClient-jms.xmlis created in the current directory. Here’s a representative example of its contents:
<weblogic-client-jms xmlns="http://www.bea.com/ns/weblogic/92" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
|Tip:||To include additional remote SAF connection factories and destinations from other JMS modules deployed in a cluster or domain, re-run the
The weblogic.jms.extensions.ClientSAFGenerate utility generates a JMS SAF client configuration file, using either a JMS module file or an existing JMS SAF client configuration file.
java [ weblogic.jms.extensions.ClientSAFGenerate ]
[ -url server-url ]
[ -username name-of-user ]
[ -existingClientFile file-path ]
[ -moduleFile file-path ['@' plan-path ]]*
[ -outputFile file-path ]
The name of an existing JMS SAF client configuration file. If this parameter is specified, then the existing file will be read and new entries will be added. If any conflicts are detected between items being added and items already in the JMS SAF client configuration file, a warning will be given and the new item will not be added. If a JMS SAF client configuration file is specified but the file cannot be found, then an error is printed and the utility exits.
The path to the generated output file. If a path is not specified, the utility sends its output to
weblogic-client-jms root element of the
weblogic-jmsmd.xsd schema contains several top-level elements that correspond to server-side SAF JMS features from WebLogic Server 9.2. Table 6-2 makes clear what the relationship between the top-level element in the schema and the corresponding WLS 9.2 management MBean.
For more information, see Default Store Options for JMS SAF Clients.
|Caution:||You can only specify one
All of the properties in these management MBeans work the same in the JMS SAF client implementation as they do in server-side SAF JMS configurations, except for those described in the following tables.
Table 6-3 describes the differences between the standard
SAFAgentMBean fields and the fields in the JMS SAF client configuration file.
|Caution:||You can only specify one
Table 6-4 describes the differences between the standard
JMSConnectionFactoryBean fields and the fields in the JMS SAF client configuration file.
Table 6-5 describes the differences between the standard
SAFImportedDestinationsBean fields and the fields in the JMS SAF client configuration file.
Each JMS SAF client has a default store that requires no configuration, and which can be shared by multiple JMS SAF clients. The default store is a file-based store that maintains its data in a group of files directly under the JMS SAF client configuration directory.
persistent-store element, you can specify another location for the default store and also change its default write policy by specifying the following elements in the JMS SAF client configuration file:
|Caution:||You can only specify one
Here’s an example of a customized JMS SAF client default store in a JMS SAF client configuration file:
For more information on using the Synchronous Write Policy for a file store, seein Configuring WebLogic Server Environments.
The generated SAF configuration file does not contain any encrypted passwords for its generated SAF remote contexts, regardless of whether any were configured in the source JMS module file. If security credentials are configured for the remote cluster or server contexts defined in the JMS SAF client configuration file, then encrypted passwords are required to connect to the remote servers or cluster.
To create encrypted passwords for your remote SAF contexts, you must use the
ClientSAFEncrypt utility bundled with your WebLogic installation, which encrypts cleartext strings for use with the JMS SAF client feature.
The following steps demonstrate how to use the
ClientSAFEncrypt to generate encrypted passwords:
> java -Dweblogic.management.allowPasswordEcho=true weblogic.jms.extensions.ClientSAFEncrypt [ key-password ] [ remote-password ]*
remote-passwordfields are not specified, then you will be prompted for the
Password Key ("quit" to end):
Password ("quit" to end):
Password ("quit" to end):
ClientSAFEncrypt utility for all passwords (with the same
key-password) required by the remote contexts defined in the JMS SAF client configuration file. When a client starts using the JMS SAF client, it must supply the same
key-password that was provided to the
quitto exit the
The weblogic.jms.extensions.ClientSAFEncrypt utility encrypts cleartext strings for use with JMS SAF clients in order to access remote SAF contexts.
java [ -Dweblogic.management.allowPasswordEcho=true ]
The key to use when encrypting all remote passwords needed for the remote contexts defined in the JMS SAF client configuration file.
Cleartext string to be encrypted. Multiple passwords for each remote context can be generated in one session.
How you install the JMS SAF client depends on whether your client machines require smaller
JAR files (thin clients) or whether they can accommodate using the single, higher-performing
weblogic.jar file, which contains all the necessary functionality and is also the recommended best practice.
The required WebLogic
JAR files are located in the
\server\lib subdirectory of the WebLogic Server installation directory, where
WL_HOME is the top-level installation directory for the entire WebLogic product installation (for example,
JAR sizes are required for thin clients, the JMS SAF client requires installing the following
JAR files to a directory on the client machine’s file system and added to its
wljmsclient.jar has a reference to the
wlclient.jar so it is only necessary to put one or the other
JAR in the client machine’s
Again, the recommended best practice is to use the larger, higher-performing
weblogic.jar, which must be installed to a directory on the client machine’s file system and added to its
CLASSPATH. Using the
weblogic.jar file also allows you to run the
ClientSAFGenerate utility on a client machine to generate a configuration file from an existing JMS SAF client configuration file, as described in Steps to Generate a JMS SAF Client Configuration File from a JMS Module.
For more information on deploying thin clients, see Developing a J2EE Application Client (Thin Client).
The JMS SAF client requires a special initial JNDI provider to look up the server-side JMS connection factories and destinations specified in the JMS SAF client configuration file that was generated during Steps to Generate a JMS SAF Client Configuration File from a JMS Module.
Modify your JMS client applications to use the JMS SAF client JNDI context factory in place of the standard server initial context. The name used for the JMS SAF client JNDI property
An example JNDI initial context factory could look like this in a JMS SAF client application:
public final static String JNDI_FACTORY="weblogic.jms.safclient.jndi.InitialContextFactoryImpl";
With the standard JNDI lookup, the JMS SAF client is started automatically and looks up the server-side JMS connection factories and destinations specified in the configuration file. For the configuration file,
ClientSAF.xml is the default name expected in the current working directory of the JMS client, but you can also explicitly specify a configuration file name by passing an argument in the JMS client.
Items returned from the initial context created with the JMS SAF client do not work in JMS calls from third-party JMS providers. Also, there can be no mixing of JMS SAF client initial contexts with server initial contexts, as described in No Mixing of JMS SAF Client Contexts and Server Contexts.
You can also update your JMS client applications to use the
weblogic.jms.extensions.ClientSAF extension class, which allows the JMS client to control when the JMS SAF client system is in use. See The JMS SAF Client Initialization API.
There are also two optional JMS SAF client JNDI properties:
Context.PROVIDER_URL– This must be an
URLthat points to your JMS SAF client configuration file. If one is not specified, it defaults to a file named
ClientSAF.xmlin the current working directory of the JVM.
Context.SECURITY_CREDENTIALS– If you are using security, specify a key password used to encrypt the remote context passwords in the configuration file.
The local JNDI provider only supports the
close() APIs. All other APIs throw an exception stating that the functionality is not supported.
The following management features are available for use with the JMS SAF client implementation.
weblogic.jms.extensions.ClientSAF extension class allows the JMS client to control when the JMS SAF client system is in use. JMS clients do not need to use this extension mechanism, but can do so in order to get finer control of the JMS SAF client system. For example, the
close() method can be used to stop a JMS client from forwarding messages.
The JMS SAF client provides a utility to administer the default file store used by JMS SAF clients. Similar to the server-side WebLogic Store utility, it enables you to troubleshoot a JMS SAF client store or extract its data. Run the utility from a Java command line or from the WebLogic Scripting Tool (WLST). The store utility operates only on a store that is not currently opened by a running JMS SAF client.
The most common uses-cases for store administration are for compacting a file store to reduce its size and for dumping the contents of a file store to an XML file for troubleshooting purposes. For more information, seein Configuring WebLogic Server Environments.
The following JMS programming considerations apply when you use the JMS SAF client.
Generally, JMS applications can use the
JMSReplyTo header field to advertise its temporary destination name to other applications. However, as with server-side JMS SAF imported destinations, the use of temporary destinations with a
JMSReplyTo field is not supported for JMS SAF clients.
For more information on using JMS temporary destinations, seein Programming WebLogic JMS.
When items returned from the JMS SAF client naming context are used in conjunction with items returned from a server initial context, the JMS API fails with a reasonable exception message. Likewise, when items returned from a server initial context is used in conjunction with items returned from the JMS SAF client naming context, the JMS API fails with a reasonable exception message.
Transacted sessions are supported with JMS SAF clients, but Client SAF operations do not participate in any global (XA) transactions. If there is an XA transaction, the message send operation is done outside the XA transaction and no exception is thrown.
The interoperability guidelines apply when using the JMS SAF client to forward messages to server-side WebLogic JMS destinations.
Each client machine must have J2SE 1.4 runtime or higher installed.
The JMS SAF client system only works with WebLogic Server 9.2 and later.
On the client-side, the JMS SAF client code must be running with WebLogic Server
JAR files that are release 9.2 or later. For more information on installing WebLogic Server
JAR files, see Installing the JMS SAF Client JAR Files on Client Machines.
JMS SAF clients can take advantage of the tuning parameters available with the server-side SAF service. For more information, seein the WebLogic Performance and Tuning Guide.
In addition to the field-level limitations discussed in Valid SAF Elements for JMS SAF Client Configurations, the following limitations apply to the JMS SAF client:
saf-agentelement in a JMS SAF client configuration file.