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.

Use the ClientSAFGenerate utility to generate a JMS SAF client configuration file from a JMS module configuration file in a WebLogic Server 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.

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

   $DOMAIN_HOME/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 myusername -moduleFile examples-jms.xml -outputFile d:\temp\ClientSAF-jms.xml
   

   Table 3-1 explains the valid ClientSAFGenerate arguments.

3. A configuration file named SAFClient-jms.xml is created in the current directory. Here 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 file to the client machines where you will run your JMS SAF client applications. See Installing the JMS SAF Client JAR Files on Client Machines.

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

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

Table 3-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, that 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 on using the Synchronous Write Policy for a file store, see Using the WebLogic Persistent Store in Administering the WebLogic Persistent Store.

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.

The weblogic.jms.extensions.ClientSAFEncrypt utility encrypts clear text 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 ]

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

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

The JMS SAF client discovery tool is a Java program packaged in the WebLogic Server JMS client library that can be used to survey existing local SAF messages before upgrading. This tool:

1. Reviews the client configuration, including checking each remote destination and the corresponding kernel queues.

2. Prints the number of messages in each kernel queue.

3. Prints select 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.

You can use the results of the survey to tune upgraded system properties. See JMS SAF Client Migration Properties.

Usage: java weblogic.jms.extensions.ClientSAFDiscover options

In the preceding syntax, options represents one or more of the values described in the following table:

• Example
  

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 set to false, this property prevents the migration of messages from multiple queues to a single queue. The default is true.

• weblogic.jms.safclient.MigrationCutoffTime—Use this property to specify a time after which messages are migrated to a single kernel queue. Any remaining messages are discarded. If this property is not specified, all existing messages are upgraded. Use this property in conjunction with the weblogic.jms.safclient.MigrationCutoffTimeFormatproperty to specify the time format.

  For example, if the cutoff time 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, then 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.