7 Reliably Sending Messages Using the JMS SAF Client

How the JMS SAF Client Configuration File Works

The JMS SAF client XML file conforms to the WebLogic Server weblogic-jms.xsd schema for JMS modules and contains the root element weblogic-client-jms. The weblogic-jms.xsd schema contains several top-level elements that correspond to server-side WebLogic JMS SAF features, 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 forwarder.

Steps to Generate a JMS SAF Client Configuration File from a JMS Module

Use the 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.

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, complete the following steps:

1. Navigate to the directory in the WebLogic domain containing the JMS module file that you want to use as the basis for the JMS SAF client configuration file:

   c:\Oracle\Middleware\wlserver_10.3\samples\domains\wl_server\config\jms 
   

2. From a Java command-line, run the ClientSAFGenerate utility:

   > java weblogic.jms.extensions.ClientSAFGenerate -url http://10.61.6.138:7001 -username weblogic -moduleFile examples-jms.xml -outputFile d:\temp\ClientSAF-jms.xml
   

   Table 7-1 lists and describes the valid ClientSAFGenerate arguments.

3. A configuration file named SAFClient-jms.xml is created in the current directory. The following is a representative example of its contents:

   <weblogic-client-jms xmlns="http://www.bea.com/ns/weblogic/100" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <connection-factory name="exampleTrader">
       <jndi-name>jms.connection.traderFactory</jndi-name>
       <transaction-params>
         <xa-connection-factory-enabled>false
         </xa-connection-factory-enabled>
       </transaction-params>
     </connection-factory>
     <saf-imported-destinations name="examples">
       <saf-queue name="exampleQueue">
         <remote-jndi-name>weblogic.examples.jms.exampleQueue
         </remote-jndi-name>
         <local-jndi-name>weblogic.examples.jms.exampleQueue
         </local-jndi-name>
       </saf-queue>
       <saf-topic name="quotes">
         <remote-jndi-name>quotes</remote-jndi-name>
         <local-jndi-name>quotes</local-jndi-name>
       </saf-topic>
     </saf-imported-destinations>
     <saf-remote-context name="RemoteContext0">
       <saf-login-context>
         <loginURL>t3://localhost:7001</loginURL>
         <username>weblogic</username>
       </saf-login-context>
     </saf-remote-context>
   </weblogic-client-jms>
   

   Tip:

   To include additional remote SAF connection factories and destinations from other JMS modules deployed in a cluster or domain, re-run the ClientSAFGenerate utility against these JMS module files and specify the same JMS SAF configuration file name in the -outputFile parameter. See ClientSAFGenerate Utility Syntax.

4. The generated configuration file does not contain any encrypted passwords for the SAF remote contexts used to connect to remote servers. To create encrypted passwords for the remote SAF contexts and add them to the configuration file, follow the directions in Encrypting Passwords for Remote JMS SAF Contexts.

5. Copy the generated configuration can file to the client machine(s) where you run your JMS SAF client applications. See Installing the JMS SAF Client JAR Files on Client Machines.

ClientSAFGenerate Utility Syntax

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  ]

Valid SAF Elements for JMS SAF Client Configurations

The weblogic-client-jms root element of the weblogic-jms.xsd schema contains several top-level elements that correspond to server-side WebLogic JMS SAF features. Table 7-2 identifies the management MBean to which each top-level element in the schema corresponds.

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 7-3 describes the differences between the standard SAFAgentMBean fields and the fields in the JMS SAF client configuration file.

Table 7-4 describes the differences between the standard JMSConnectionFactoryBean fields and the fields in the JMS SAF client configuration file.

Table 7-5 describes the differences between the standard SAFImportedDestinationsBean fields and the fields in the JMS SAF client configuration file.

Default Store Options for JMS SAF Clients

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.

Using the 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:

The following is an example of a customized JMS SAF client default store in a JMS SAF client configuration file:

<persistent-store>
    <directory-path>config/jms/storesdom</directory-path>
    <synchronous-write-policy>Disabled</synchronous-write-policy>
  </persistent-store>

For more information about using the Synchronous Write Policy for a file store, see "Using the WebLogic Persistent Store" in Configuring Server Environments for Oracle WebLogic Server.

Steps to Generate Encrypted Passwords

To use the ClientSAFEncrypt to generate encrypted passwords, complete the following steps:

1. From a Java command-line, run the ClientSAFEncrypt utility:

   > java -Dweblogic.management.allowPasswordEcho=true weblogic.jms.extensions.ClientSAFEncrypt [ key-password ] [ remote-password ]*
   

2. If the key-password or the remote-password fields are not specified, then you will be prompted for the key-password and the remote-password interactively.

3. The following is an example of obtaining an encrypted password:

   Password Key ("quit" to end):
   Password ("quit" to end):
   <password-encrypted>{Algorithm}PBEWithMD5AndDES{Salt}9IsTPAuZdcQ={Data}d6SSPp3GwPAfEXn8izyZA0IRCV/izT8H</password-encrypted>
   Password ("quit" to end):
   

4. Continue generating as many remote passwords as necessary for the remote contexts defined in the JMS SAF client configuration file.

5. Copy the encrypted remote password before the closing </saf-login-context> stanza in the JMS SAF client configuration file. For example:

   <saf-remote-context name="RemoteContext0">
   <saf-login-context>
   <loginURL>http://10.61.6.138:7001</loginURL>
   <username>weblogic</username>
   <password-encrypted>{Algorithm}PBEWithMD5AndDES{Salt}dWENfrgXh8U={Data}u8xZ968dElHckso/ZYm2LQ6xVNBPpBGQ</password-encrypted>
   </saf-login-context>
   </saf-remote-context>
   

   Use the 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 ClientSAFEncrypt utility.

6. Type quit to exit the ClientSAFEncrypt utility.

ClientSAFEncrypt Utility Syntax

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 ]  weblogic.jms.extensions.ClientSAFEncrypt [ key-password ]  weblogic.jms.extensions.ClientSAFEncrypt [ remote-password ]

Required JNDI Context Factory for JMS SAF Clients

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 java.naming.factory.initial is weblogic.jms.safclient.jndi.InitialContextFactoryImpl.

An example JNDI initial context factory could look as follows 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 interface, which allows the JMS client to control when the JMS SAF client system is in use. See The JMS SAF Client Initialization API.

Optional JNDI Properties for JMS SAF Clients

A JMS SAF client has two optional JNDI properties:

• Context.PROVIDER_URL – This must be a URL that points to your JMS SAF client configuration file. If one is not specified, it defaults to a file named ClientSAF.xml in 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 lookup(String) and close() APIs. All other APIs throw an exception stating that the functionality is not supported.

JMS SAF Client Discovery Tool

The discovery tool is a Java program packaged in the WLS JMS client library that can be used to survey existing local SAF messages before upgrading. The discovery tool reviews the client configuration (including checking each remote destination and the corresponding kernel queues), prints the number of messages in each kernel queue, and prints some header information from the first message in each kernel queue (for example: message id, correlation id, SAF sequence name, SAF sequence number and Unit-of-Order). The results of the survey can be used to tune upgrade system properties. See Chapter 7, "JMS SAF Client Migration Properties."

Usage: java weblogic.jms.extensions.ClientSAFDiscover options

The discovery tool options are described in the following table:

JMS SAF Client Migration Properties

Because message migration can be a complex issue even when automated, Oracle provides the following system properties to manage the process:

• weblogic.jms.safclient.MigrateExistingMessages—If false, this property prevents the migration of message from multiple queues to a single queue. The default is true.

• weblogic.jms.safclient.MigrationCutoffTime—Use to specify a time, the format specified by weblogic.jms.safclient.MigrationCutoffTimeFormat, after which messages are migrated to a single kernel queue. Any remaining messages are discarded. If not specified, all existing messages are upgraded.

  For example, if the cutoff format is the default, a valid cutoff time is 2009-12-16T10:34:17.887-0800. If the specified time does not match the format pattern, an exception is thrown and the JMS SAF client stops all message processing.

• weblogic.jms.safclient.MigrationCutoffTimeFormat—Specifies the format of the weblogic.jms.safclient.MigrationCutoffTime. The default is "yyyy-MM-dd'T'HH:mm:ss.SSSZ". See the description of the java.text.SimpleDateFormat class for more information.