4 Reliably Sending Messages Using the JMS SAF Client

Learn how to configure and use the JMS SAF client to reliably send JMS messages from standalone JMS clients to server-side JMS destinations.

This chapter includes the following sections:

Overview of Using Store-and-Forward with JMS Clients

The JMS SAF client extends the JMS store-and-forward service to standalone JMS clients. 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 consists of two main parts:

  • The JMS SAF client implementation, which writes messages directly to a client-side persistent store on the local file system.

  • A SAF forwarder, which takes the messages written to the store and sends them to a WebLogic Server instance.

An optional ClientSAF initialization API is also available that allows JMS SAF clients to turn the SAF forwarder mechanism on and off whenever necessary, as described in weblogic.jms.extensions. See The JMS SAF Client Initialization API.

Note:

For information about using server-side WebLogic JMS SAF for reliably sending JMS messages to potentially unavailable destinations. See Configuring SAF for JMS Messages in Administering the Store-and-Forward Service for Oracle WebLogic Server.

Configuring a JMS Client To Use Client-Side SAF

No configuration is required on the server-side, but running client-side SAF does require some configuration on each client. Learn how to configure a JMS client to use client-side SAF.

These sections describe how to configure a JMS client to use client-side SAF.

Generating a JMS SAF Client Configuration File

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

The ClientSAFGenerate utility creates entries for all connection factories, standalone 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).

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 Server domain. You can also generate a configuration file from an existing JMS SAF client configuration file, as described in ClientSAFGenerate Utility Syntax.

Note:

Running the ClientSAFGenerate utility on a client machine to generate a configuration file from an existing JMS SAF client configuration file requires using the install client (weblogic.jar) in the CLASSPATH instead of the thin T3 JMS client and JMS SAF clients. See Installing the JMS SAF Client JAR Files on Client Machines.

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

Note:

ClientSAF.xml is the default name expected in the current working directory of the JMS client, but you can explicitly specify a file name by passing an argument in the JMS client, as described in Modify Your JMS Client Applications To Use the JMS SAF Client's Initial JNDI Provider.

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  ]

Table 4-1 ClientSAFGenerate Arguments

Argument Definition

url

The URL of the WebLogic Server instance where the JMS SAF client instance should connect.

username

The name of a valid user that this JMS SAF client instance should use when forwarding messages.

existingClientFile

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.

moduleFile

The name of a JMS module configuration file and optional plan file.

outputFile

stdout.

ClientSAF.xml is the default name expected in the current working directory of the JMS client, but you can also explicitly specify a file name by passing an argument in the JMS client.

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 4-2 identifies the management MBean to which each top-level element in the schema corresponds.

Table 4-2 weblogic-client-saf Elements

weblogic-client-jms Element WebLogic Server Management Bean

connection-factory

JMSConnectionFactoryBean

saf-agent

SAFAgentMBean

saf-imported-destinations

SAFImportedDestinationsBean

saf-remote-context

SAFRemoteContextBean

saf-error-handling

SAFErrorHandlingBean

persistent-store

See Default Store Options for JMS SAF Clients.

Note:

You can only specify one persistent-store and saf-agent element in a JMS SAF client configuration file.

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

Table 4-3 Modified SAFAgentMBean Fields

Server-side SAF Fields Difference in JMS SAF Client Configuration File

PersistentStore

Not available. There is only one persistent store defined.

ServiceType

Not available. This can only be a sending agent.

BytesThresholdHigh

Threshold properties are not available.

BytesThresholdLow

Threshold properties are not available.

MessagesThresholdHigh

Threshold properties are not available.

MessagesThresholdLow

Threshold properties are not available.

ConversationIdleTimeMaximum

Not available. This field is only valid for receiving messages.

AcknowledgeInterval

Not available. Only valid for receiving messages.

IncomingPausedAtStartup

Not available. No way to unpause; same effect achieved by not setting the JMS SAF client property.

ForwardingPausedAtStartup

Not available. No way to unpause; same effect achieved by not setting the JMS SAF client property.

ReceivingPausedAtStartup

Not available. No way to unpause; same effect achieved by not setting the JMS SAF client property.

Note:

You can only specify one saf-agent element in a JMS SAF client configuration file.

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

Table 4-4 Modified JMSConnectionFactoryBean Fields

Server-side SAF Fields Difference in JMS SAF Client Configuration File

SubDeploymentName

Ignored. These connection factories are not targeted.

ClientParamsBean: MulticastOverrunPolicy

Ignored. This client cannot do multicast receives.

TransactionParamsBean: XAConnectionFactoryEnabled

Ignored. JMS SAF client cannot do XA transactions.

FlowControlParamsBean

All fields are ignored. JMS SAF client cannot receive messages.

LoadBalancingParamsBean

All fields are ignored. JMS SAF client cannot load balance because it is not connected to a server.

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

Table 4-5 Modified SAFImportedDestinationsBean Fields

Server-side SAF Fields Difference in JMS SAF Client Configuration File

SubDeploymentName

Ignored. These are targeted to the single SAF agent defined in this file.

UnitOfOrderRouting

Ignored. Message unit-of-order is not supported.

Default Store Options for JMS SAF Clients

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:

Table 4-6 persistent-store Elements

Element Name What it does

directory-path

Specifies the path to the directory on the file system where the file store is kept.

synchronous-write-policy

Defines how hard a file store will try to flush records to the disk. Values are: Direct-Write (default), Cache-Flush, and Disabled.

Note:

You can only specify one persistent-store element in a 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.

Encrypting Passwords for Remote JMS SAF Contexts

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 Server installation, which encrypts clear text strings for use with the JMS SAF client feature.

Note:

The existing weblogic.security.Encrypt command-line utility cannot be used because it expects access to the domain security files, which are not available on the client.

Steps to Generate Encrypted Passwords

The following steps demonstrate how to use ClientSAFEncrypt to generate encrypted passwords:

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

Table 4-7 ClientSAFEncrypt Arguments

Argument Definition

weblogic.management.allowPasswordEcho

Optional. Allows echoing characters entered on the command, weblogic.jms.extensions.ClientSAFEncrypt. Expects that no-echo is available; if no-echo is not available, set this property to true.

key-password

The key to use when encrypting all remote passwords needed for the remote contexts defined in the JMS SAF client configuration file.

If omitted from the command line, you will be prompted to enter a key-password.

remote-password

Clear text string to be encrypted. Multiple passwords for each remote context can be generated in one session.

If omitted from the command line, you are prompted to enter a remote-password.

Installing the JMS SAF Client JAR Files on Client Machines

WebLogic Server provides two JMS SAF client options:

The required JAR files are located in the WL_HOME\server\lib subdirectory of the WebLogic Server installation directory, where WL_HOME is the top-level installation directory for the entire WebLogic Server product installation (for example, c:\Oracle\Middleware\Oracle_Home\wlserver\server\lib).

Modify Your JMS Client Applications To Use the JMS SAF Client's Initial JNDI Provider

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.

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

Optional JNDI Properties for JMS SAF Clients

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.

JMS SAF Client Management Tools

Learn about the JMS SAF client initialization API and client-side store administration utility features, which are available for use with the JMS SAF client implementation.

The following management features are available for use with the JMS SAF client implementation:

The JMS SAF Client Initialization API

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

Client-Side Store Administration Utility

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. See Administering a Persistent Store in Administering the WebLogic Persistent Store.

JMS Programming Considerations with JMS SAF Clients

Learn about the JMS programming considerations while using the JMS SAF client.

The following JMS programming considerations apply when you use the JMS SAF client:

How the JMSReplyTo Field Is Handled In JMS SAF Client Messages

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, see Using Temporary Destinations in Developing JMS Applications for Oracle WebLogic Server.

No Mixing of JMS SAF Client Contexts and Server Contexts

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.

Using Transacted Sessions With JMS SAF Clients

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.

JMS SAF Client Interoperability Guidelines

The interoperability guidelines apply when using the JMS SAF client to forward messages to server-side WebLogic JMS destinations.

The topic has following sections:

Java Runtime

Each client machine must have Java SE 1.4 runtime or later installed.

WebLogic Server Versions

The WebLogic JMS SAF client system only works with WebLogic Server 9.2 and later.

On the client-side, the WebLogic 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 C API

Client-side SAF is usable from C environments using the JMS C API. This implementation of the JMS C API uses JNI in order to access a Java Virtual Machine (JVM). However, the JMS C API cannot use the weblogic.jms.extensions.ClientSAF interface because it is a non-standard JMS API.

To use SAF with the JMS C API, set the SAF context on the jndiFactory. By default, if you pass NULL as the jndiFactory you would get the normal WebLogic Server context. For example:

int JmsContextCreate(JmsString *uri, JmsString *jndiFactory, JmsString *username, JmsString *password, JmsContext **context, JMS64I flags)

See WebLogic C API in Developing JMS Applications for Oracle WebLogic Server.

Tuning JMS SAF Clients

JMS SAF clients can take advantage of the tuning parameters available with the server-side SAF service.

See Tuning WebLogic JMS Store-and-Forward in the Tuning Performance of Oracle WebLogic Server.

Limitations of Using the JMS SAF Client

Learn about the non-supported features and exceptions while using the JMS SAF Client.

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:

  • The JMS Message Unit-of-Order and Unit-of-Work JMS Message Group features are not supported.

  • A destination consumer of an imported SAF destination is not supported. An exception is thrown if you attempt to create such a consumer in JMS SAF client environment.

  • A destination browser of an imported SAF destination is not supported. An exception is thrown if you attempt to create such a browser in JMS SAF client environment.

  • Transacted sessions are supported, but not user (XA) transactions. Client SAF operations do not participate in any global transactions. See Using Transacted Sessions With JMS SAF Clients.

  • JMS SAF clients are not supported in Java Applets.

  • You can only specify one persistent-store and saf-agent element in a JMS SAF client configuration file.

  • The WebLogic Server CMP 2.x extension that allows users to return a java.sql.ResultSet to a client is not supported.

Behavior Change in JMS SAF Client Message Storage

In the Weblogic JMS SAF client, messages are kept in local storage before being forwarded to the remote destinations. Each remote destination corresponds to a local storage unit, which is called a kernel queue. In releases prior to Oracle WebLogic Server 10.3.3.0, a JMS SAF client instance used a different kernel queue each time it closed and reopened. This behavior allowed multiple kernel queues to correspond to a destination.

Note:

  • If the destination was a single remote destination, under some circumstances a JMS SAF client may not have forwarded messages or may have forwarded them out of order.

  • If the destination was a distributed destination, under some circumstances some messages could be permanently lost or duplicate messages could be sent.

In this release, the same kernel queue is used for a remote destination regardless of how many times the JMS SAF client is opened and closed. For application environments in which a JMS client SAF instance is opened only once, there is no change in behavior.

The Upgrade Process, Tools, and System Properties

The following sections provide information on process, tools, and system properties used to upgrade JMS SAF clients to use one kernel queue for each destination, regardless of how many times the client opens and closes the kernel queue.

  • If your application environment opens a JMS SAF client only once, no action is required.

  • New JMS SAF clients require no changes.

  • If your application environment opens and close a JMS SAF client more than once, existing messages can be located in multiple kernel queues in the client. Oracle provides a user-tunable process to migrate messages from multiple kernel queues to a single kernel queue when a JMS SAF client starts for the first time after being upgraded. Although the migration ensures messages are not lost, there is a small possibility that message duplication can occur. Any message that is migrated retains its normal SAF QoS. You can opt out of migrating existing messages by either removing the local store or specifying weblogic.jms.safclient.MigrateExistingMessages=false. See JMS SAF Client Migration Properties. If the message migration fails for any reason, the JMS SAF client does not start.

JMS SAF Client Discovery Tool

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:

Option Description

-help

Print usage information.

-clientSAFRootDir client-saf-root-directory

Optional. Defaults to current directory.

Specifies the root directory of the target SAF client to discover. Any relative paths in the SAF client configuration file are relative to this directory.

-configurationFile config-file

Optional. Defaults to ClientSAF.xml.

Specifies the location of the configuration file used by the targeted JMS SAF client. This option is required if the clientSAFRootDir option is specified. If the clientSAFRootDir option or this option is specified, the ClientSAF.xml file under the current working directory is used. If the specified configuration file does not exist, an exception is thrown.

-cutoffFormat pattern

Optional. Defaults to yyyy-MM-dd'T'HH:mm:ss.SSSZ.

Specifies the date and time pattern for the optional cutoff time used. See http://docs.oracle.com/javase/8/docs/api/java/text/DateFormat.html .

-cutoffTime cutoff-time

Optional. Defaults to null set.

Prints data on messages that are discarded during upgrade if weblogic.jms.safclient.MigrationCutoffTime is set. No messages are discarded. The cutoff time format depends on the value of the -cutoffFormat property. An exception is thrown if the specified cutoff time does not match the cutoffFormat pattern. If a cutoff time is not specified, no messages are discarded and no messages are printed.

-discoveryFile discovery-file

Optional. Defaults to SAF_DISCOVERY.

Specifies the file that contains the output generated by the JMS SAF client discovery tool. The output is placed relative to the root directory unless an absolute path is specified. If the specified file already exists, it is deleted and a new file is created.

Example

If you created a JMS SAF CLient using:

ClientSAFFactory.getClientSAF(new File("c:\\foo"), new FileInputStream("c:\\ClientSAF-jms.xml"));

You can survey the existing messages using the ClientSAFDiscover tool before upgrading the JMS SAF client. For example:

java weblogic.jms.client.ClientSAFDiscover -clientSAFRootDir c:\foo -configurationFile c:\ClientSAF-jms.xml

The discovery information will be written to the default location at c:\foo\SAF_DISCOVERY.

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