15 Configuring Messaging

Creating a persistent store is a required step before configuring a JMS server, SAF agent, or path service. This is because resource group and resource group template-scoped JMS servers, SAF agents, and path services must reference an existing persistent store.

Creating a custom file or JDBC persistent store inside a resource group that is either scoped to a domain or to a partition is similar to creating a persistent store at the domain level. However, an additional step is that you must specify the scope. In the Oracle WebLogic Server Administration Console and Oracle Enterprise Manager Fusion Middleware Control, there is a Scope menu in the first step of the creation process that lists the available scopes in which to create a persistent store. Using WebLogic Scripting Tool (WLST), you must create the persistent store using the createPersistentStore command on the parent MBean (the MBean for the domain, resource group, or resource group template).

The following Distribution Policy and Migration Policy rules apply to all resource group and resource group template-scoped persistent stores:

• A resource group or resource group template-scoped store that will be used to host JMS server distributed destinations or SAF agent imported destinations must specify a Distributed Distribution Policy (the default). This setting instantiates a store instance per WebLogic Server instance in a cluster. Furthermore, a resource group or resource group template-scoped store with a Distributed Distribution Policy may optionally be configured with an On-failure or Always Migration Policy.

• A resource group or resource group template-scoped store that will be used by a path service or that will be used to host JMS server standalone (nondistributed) destinations must specify a Singleton Distribution Policy. This setting instantiates a single store instance in a cluster. Furthermore, a resource group or resource group template-scoped store with a Singleton Distribution Policy must have either On-failure or Always as its Migration Policy instead of Off. Off is the default.

• A cluster-targeted store with an On-failure or Always Migration Policy requires that the cluster be configured with either database leasing or cluster leasing where database leasing is recommended as a best practice.

These policies control the distribution and high availability behavior of stores and any JMS artifacts that target a cluster. For more information, see "Simplified JMS Cluster and High Availability Configuration" in Administering JMS Resources for Oracle WebLogic Server.

The following are the enforced configuration validation and targeting rules for both file and JDBC stores:

• A resource group or resource group template-level JMS server, SAF agent, or path service must reference a configured store; they cannot reference null.

• A resource group template-scoped JMS server, SAF agent, or path service may reference only a store that is defined in the same resource group template. It cannot reference a store defined at the child resource group level.

• A resource group-scoped JMS server, SAF agent, or path service may a reference only a store that is defined in the same resource group, or in the resource group template optionally referenced by the resource group.

• A domain-level JMS server, SAF agent, or path service may reference only a store in the domain scope.

The following are additional rules that are specific to JDBC stores.

• A resource group template-scoped JDBC store may reference only a data source that is in the same resource group template.

• A resource group-scoped JDBC store may reference only a data source that is in the same resource group, or in the resource group template, optionally referenced by the resource group.

• A domain-scoped JDBC store may reference only a data source in the domain scope.

Creating a JMS server that is scoped to a domain-level resource group or in a partition is similar to creating a JMS server at the domain level. One additional step is to specify the scope. In the WebLogic Server Administration Console and Fusion Middleware Control, there is a Scope menu in the first step of the creation process that lists the available scopes in which to create a JMS server. Using WLST, you must create the JMS server using the createJMSServer command on the parent MBean (the MBean for the domain, resource group, or resource group template).

Another required step is to configure the JMS server so that it references a persistent store that is configured in the same scope as the JMS server.

Finally, if the JMS server is going to be used to host distributed destinations, its store must be configured with a Distributed Distribution Policy. If the JMS server is going to host standalone (nondistributed) destinations, the store must be configured with a Singleton Distribution Policy.

Creating a Store-and-Forward (SAF) agent that is scoped to a domain-level resource group or in a partition is similar to creating a SAF agent at the domain level. One additional step is to specify the scope. In the WebLogic Server Administration Console and Fusion Middleware Control, there is a Scope menu in the first step of the creation process that lists the available scopes in which to create an SAF agent. Using WLST, you must create the SAF agent using the createSAFAgent command on the parent MBean (the MBean for the domain, resource group, or resource group template).

Another required step is to configure the SAF agent so that it references a persistent store that is configured in the same scope as the SAF agent. This store must be configured with a Distributed Distribution Policy (the default).

A path service must be configured in a resource group or resource group template if the resource group or resource group template also configures any distributed destinations that will be used to host Unit-of-Order (UOO) messages. In addition, such distributed destinations need to be configured with a Unit-of-Order routing policy set to PathService instead of Hash because hash-based UOO routing is not supported in a resource group or resource group template scope. Resource group or resource group template-scoped distributed destinations will only use a path service that is configured in the same resource group or resource group template for routing UOO messages. Attempts to send messages to a resource group or resource group template-scoped distributed destination that does not configure a PathService Unit-of-Order routing policy will fail with an exception.

Creating a path service that is scoped to a domain-level resource group or in a partition is similar to creating a path service at the domain level. One additional step is to specify the scope. In the WebLogic Server Administration Console and Fusion Middleware Control, there is a Scope menu in the first step of the creation process that lists the available scopes in which to create a path service. Using WLST, you must create the path service using the createPathService command on the parent MBean (the MBean for the domain, resource group, or resource group template).

Another required step is to configure the path service so that it references a persistent store that is configured in the same scope as the path service. This store must be configured with a Singleton Distribution Policy and an Always or On-Failure Migration Policy.

Creating a messaging bridge that is scoped to a domain-level resource group or in a partition is similar to creating a messaging bridge at the domain level. One additional step is to specify the scope. In the WebLogic Server Administration Console and Fusion Middleware Control, there is a Scope menu in the first step of the creation process that lists the available scopes in which to create a messaging bridge. Using WLST, you must create the messaging bridge using the createMessagingBridge command on the parent MBean (the MBean for the domain, resource group, or resource group template).

The following Distribution Policy and Migration Policy rules apply to all resource group or resource group template-scoped messaging bridges:

• Specify a Distributed Distribution Policy (the default) on a bridge to cause a cluster-targeted bridge to deploy an instance per server in a cluster. A messaging bridge with a Distributed Distribution Policy may optionally also configure an On-failure Migration Policy to add support for high availability.

• Specify a Singleton Distribution Policy on a bridge to cause a cluster-targeted bridge to limit itself to deploying one instance per cluster. A messaging bridge with a Singleton Distribution Policy must have an On-failure Migration Policy instead of Off. Off is the default.

• A cluster-targeted bridge with an On-failure Migration Policy requires that the cluster be configured with either database leasing or cluster leasing, where database leasing is recommended as a best practice.

These policies control the high availability behavior and distribution behavior of messaging bridges that target a cluster. For more information about distribution and migration policies, see "Simplified JMS Cluster and High Availability Configuration" in Administering JMS Resources for Oracle WebLogic Server.

The following are the configuration validation rules that are specific to a messaging bridge:

• A resource group template-scoped messaging bridge can reference only messaging bridge destinations in the same scope.

• A resource group-scoped messaging bridge can reference only messaging bridge destinations in the same resource group, or in the resource group template optionally referenced by the resource group.

• A domain-scoped messaging bridge may reference only messaging bridge destinations in the domain scope.

Creating a JMS system resource that is scoped to a domain-level resource group or in a partition is similar to creating a JMS system resource at the domain level. One additional step is to specify the scope. In the WebLogic Server Administration Console and Fusion Middleware Control, there is a Scope menu in the first step of the creation process that lists the available scopes in which to create a JMS system resource. Using WLST, you must create the JMS system resource using the createJMSSystemResource command on the parent MBean (the MBean for the domain, resource group, or resource group template).

Creating an application-scoped JMS module that has a domain-level resource group scope or is in a partition is similar to creating one for the domain level. An application deployment may contain a JMS module file, or an application EAR file that in turn contains JMS module files. One additional step is to specify the resource group or resource group template scope. For more information, see Deploying Applications.

The following are the configuration validation and targeting rules associated with resources in a resource group or resource group template-scoped JMS module.

An application that is running in a partition on a WebLogic Server instance can access JMS resources in its own local partition simply by creating a local initial context without specifying any provider URL. This approach is the best practice for creating locally scoped contexts.

If a context URL matches a virtual host URL or URI that is configured for a partition, then JNDI creates the context for that partition and all requests from the context are delegated to the partition's JNDI name space.

A JMS application can therefore access a WebLogic Server JMS resource that is running in a different JVM or WebLogic Server cluster using the t3 or HTTP protocol by supplying a URL of the form:

• t3://virtualhost:port

• t3://host:port/URI

It is possible to dedicate a specific port or address to a channel in a partition, in which case the URL format becomes t3://host:port.

This is the only supported method for clients prior to release 12.2.1 to interoperate with partition-scoped resources.

For more information, see Configuring Virtual Targets.

An application in one partition can access another partition on the same WebLogic Server instance or in the same cluster using one of the URLs described in the previous section.

However, to support access across partitions that reside on the same server more efficiently without a need to specify a specific host, port, or URI, an application has the following options.

• Create a context with a local: protocol URL:

  • local:// Creates the context on the current partition, which can be either a partition or the domain.

  • local://?partitionName=DOMAIN Creates the context on the domain.

  • local://?partitionName=partition_name Creates the context on the partition partition_name.

• Create a context without specifying a URL, and then prefix an explicit scope when specifying a JNDI name:

  • domain:<JNDIName> Looks up the JNDI entry in the domain level.

  • partition:<partition_name>/<JNDIName> Looks up the JNDI entry in the specified partition.

JMS client connections and JMS contexts are permanently associated with the partition from which their connection factory was obtained, and will not change their partition based on the partition associated with the current thread.

When JMS pushes messages or exceptions to an asynchronous listener, or similarly pushes events to a destination availability listener or an asynchronous send completion listener, the listener's local partition ID (instead of the destination's partition) will be associated with the callback thread. The local partition ID is the partition associated with the thread that created the asynchronous listener.

A connection factory can interact only with a destination defined in the same partition as the connection factory. For example a QueueBrowser, MessageConsumer/JMSConsumer, TopicSubscriber, or MessageProducer/JMSProducer client object can communicate with a destination only if the connection factory that was used to create these client objects was defined in the same partition as the destination. Furthermore, a connection factory can interact with a destination only if it is obtained from the same cluster or server JVM as the connection factory.

Prior to the 12.2.1 release, JMS servers could be deployed only at the domain level and a temporary destination could be hosted only by JMS servers that both:

• Set Hosting Temporary Destinations to true (the default).

• Are hosted on the same WebLogic Server instance or in the same cluster as the connection factory used to create the temporary destination.

The behavior for creating a temporary destination in WebLogic Server MT is:

• As in non-MT WebLogic Server, a temporary destination can be hosted only by any JMS server that has Hosting Temporary Destinations enabled and that is hosted on the same WebLogic Server instance or in the same cluster as the connection factory used to create the temporary destination.

• If a JMS connection was created using a connection factory that is configured in a resource group or resource group template scope (including domain resource groups), then its temporary destinations will be hosted only by a JMS server that is configured in the same scope.

• If a JMS connection was created using a nonresource group or resource group template-scoped partition-level connection factory, then it is allowed to create temporary destinations on any JMS server from the same partition as the connection factory. The nonresource group or resource group template-scoped partition-level connection factories are simply the default connection factories, for example the connection factories with JNDI names weblogic.jms.ConnectionFactory or weblogic.jms.XAConnectionFactory.

• If a JMS connection was created using a nonresource group or resource group template-scoped domain-level connection factory, then it is allowed to create temporary destinations on any JMS server at the domain level including JMS servers that are scoped to domain-level resource groups.

If there is no qualified JMS server found within the allowed scope, then an attempt to create a temporary destination returns an exception.

All existing messaging runtime MBeans are supported for monitoring and controlling partition-scoped JMS configuration and deployments and are accessible to JMX-based management clients. Partition-scoped JMS runtime MBeans are located under their corresponding ParititionRuntimeMBean instances.

For example:

• The JMSServer, Connection, and PooledConnection runtime MBeans are placed in the runtime MBean hierarchy under serverRuntime/PartitionRuntimes/partition/JMSRuntime.

• The SAF runtime MBeans are placed in the runtime MBean hierarchy under serverRuntime/PartitionRuntimes/partition/SAFRuntimeMBean.

• The messaging bridge and path service runtime MBeans are placed in the runtime MBean hierarchy directly under serverRuntime/PartitionRuntimes/partition.

For more information, see Monitoring and Debugging Partitions.

Security roles and policy definitions related to partition messaging configuration is the responsibility of the WebLogic Server system administrator.

WebLogic Server MT expands upon the traditional WebLogic Server security support in two significant ways:

• Multiple realms: WebLogic Server MT supports multiple active security realms and allows each partition to execute against a different realm.

• Identity domains: An identity domain is a logical namespace for users and groups, typically representing a discrete set of users and groups in the physical data store. Identity domains are used to identify the users associated with particular partitions.

Otherwise, configuring security for partition-scoped messaging is similar to setting up security for domain-level messaging. For more information, see Configuring Security.

All JTA transactions in a JVM are serviced by a single JTA transaction manager regardless of scope. Partition-scoped XA resource manager names are automatically qualified with their partition name so that the resource managers are uniquely identified to the transaction manager and are managed independently. One example of a resource manager is a persistent store.

For more information about transaction configuration and restrictions, see Configuring Transactions.

A JMS artifact that is associated with a partition or resource group can be started and shut down by starting and shutting down its partition or resource group. Permissions to perform these operations are automatically supplied to the WebLogic Server system administrator and operator.

The messaging component does not support the ability to scope a diagnostic image to a partition. For more information, see Configuring Partition-Scoped Diagnostic Image Capture.

Partition-scoped JMS log messages are qualified with the partition ID and name when the domain log format is not configured. For more information about logging, see Monitoring and Debugging Partitions.

Optionally enabled, JMS server and SAF agent message lifecycle logging is placed in locations that are different when these services are scoped to a partition. The logging files are in their partition's directory. Furthermore, the log file names of different runtime JMS server and SAF agent instances of a cluster-targeted JMS server or SAF agent are guaranteed to be replaced with a single interpretation.

The expected new log locations are summarized below when configuring an absolute path, a relative path, or the default.

* Note that partition-scoped configuration treats absolute paths as relative paths.

<domain-log> = <domain>/servers/<wl-server-name>

<partition-log> = <domain>/partitions/<partition-name>/system/servers/<wl-server-name>

<log-suffix> = logs/jmsservers/<configured-name> (for JMS servers)

<log-suffix> = logs/safagents/<configured-name> (for SAF agents)

<instance> =

• <configured-name>, when JMS server or SAF agent is single-server targeted.

• <configured-name>_<wl-server-name>, when cluster-targeted and the data store's Distribution Policy=Distributed.

  (Note that an instance keeps its old name even as it migrates from one WebLogic Server instance to another.)

• <configured-name>_01, when cluster-targeted and the data store's Distribution Policy=Singleton.

There are two JMS-specific Java administration programming utilities that provide helper methods for configuring and monitoring JMS resources.

The JMSModuleHelper utility contains helper methods for locating JMS runtime MBeans (for monitoring) as well as methods to manage (locate/create/delete) JMS module configuration entities (descriptor beans) in a given module.

The JMSRuntimeHelper utility provides convenient methods for obtaining the corresponding JMX runtime MBean given a JMS object such as a connection, destination, session, message producer, or message consumer.

In release 12.2.1, the enhanced version of the helpers are provided to handle both domain-scoped and resource group or resource group template-scoped JMS resources.

The existing JMSRuntimeHelper utility is enhanced to be partition-aware. When calling a runtime helper method, it is required that the specified JNDI context and the specified JMS object must belong to the same partition (otherwise an exception is thrown).

The enhanced JMSModuleHelper utility is scope-aware and contains the following interface and classes:

• weblogic.jms.extensions.IJMSModuleHelper—an interface that defines all helper methods.

• weblogic.jms.extensions.JMSModuleHelper—the version prior to release 12.2.1 of the JMS module helper, which handles only domain-level JMS resources.

• weblogic.jms.extensions.JMSModuleHelperFactory—a factory that creates an instance of a JMS module helper that works in a specific scope given an initial context to the Administration Server, a scope type (domain, resource group or resource group template), and the name of the scope.

The following code demonstrates how to create a JMS module helper for each of the three different scopes:

   Context ctx = getContext(); // get an initial JNDI context
 
   JMSModuleHelperFactory factory = new JMSModuleHelperFactory();
 
      // create a JMS module helper for domain level
 
   IJMSModuleHelper domainHelper = factory.getHelper(ctx, IJMSModuleHelper.ScopeType.DOMAIN, null); 
 
      // create a JMS module helper for Resource Group "MyResourceGroup"
 
   IJMSModuleHelper rgHelper = factory.getHelper(ctx, IJMSModuleHelper.ScopeType.RG, "MyResourceGroup");
 
      // create a JMS module helper for Resource Group Template "MyResourceGroupTemplate"
 
   IJMSModuleHelper rgtHelper = factory.getHelper(ctx, IJMSModuleHelper.ScopeType.RGT, "MyResourceGroupTemplate");

After a JMS module helper instance is created, you can use it to create JMS resources that are scoped to the corresponding scope. For example, the following example code creates a JMS system resource with a JMS queue on JMS server, MyJMSServer, in the resource group, MyResourceGroup. (It assumes that the JMS server and resource group have already been created.)

   String jmsServer = "MyJMSServer";
 
   String jmsSystemModule = "MyJMSSystemModule";
 
   String queue = "MyQueue";
 
   String queueJNDI = "jms/myQueue";
 
   rgHelper.createJMSSystemResource(jmsSystemModule, null);
 
   rgHelper.createQueue(jmsSystemModule, jmsServer, queue, queueJNDI, null);

Persistent stores create a number of files in the file system for different purposes. Among them are file store data files, file store cache files (for file stores with a DirectWriteWithCache Synchronous Write Policy), and JMS server and SAF agent paging files.

The file location behavior prior to release 12.2.1 remains the same for the domain-scoped persistent stores. This ensures that persistent data is recovered after an upgrade and that it is stored in the expected location. For partition-scoped configuration, these files are placed in isolated directories within the partition file system to prevent file collisions among same-named stores in different partitions.

The following summary shows of the location of various files used by the file store system in WebLogic Server MT, where partitionStem = partitions/<partitionName>/system.

The following summary shows how each of the prior store types configure their directory location.

The following sections describe procedures for non-clustered, cluster singleton, and distributed service handling of persistent data.

Store-and-forward messages involve two components, an SAF agent that stores and forwards messages and a final WebLogic JMS destination. These are often deployed to separate WebLogic server instances, clusters, or domains, and therefore, you can migrate the two components together or independently.

If you have a remote SAF agent that forwards with exactly-once QOS to a distributed destination, additional steps are required on the SAF agent when you migrate the remote distributed destination. This is because SAF messages may not be able to be forwarded after the migration, which may in turn block subsequent messages from being forwarded. To prevent this situation, Oracle recommends that you empty the SAF queue before migrating the remote distributed destination by doing the following:

1. Pause incoming new messages on the SAF agent. For more information, see "Controlling Message Operations on Destinations" in Administering JMS Resources for Oracle WebLogic Server.

2. Wait for all pending messages to be successfully forwarded.

If you are migrating an SAF agent itself that handles exactly-once forwarding, similar steps are recommended regardless of whether it is non-clustered or clustered. This is true even if the SAF agent handles only non-persistent messages. Oracle recommends that you empty the SAF agent's imported destinations (as described above), or delete all the store files or JDBC tables that are associated with the SAF agent before migrating it.

When an MDB's source destination is a queue, the MDB can be safely migrated. Similarly, an MDB can be safely migrated when an MDB consumes from a topic and its subscription-durability is set to NonDurable.

Additional caution is required when you migrate an MDB that works with a topic and its subscription-durability is set to Durable, regardless of whether the MDB or topic is hosted on a cluster or a non-clustered server and regardless of whether the MDB's source destination is hosted in the same cluster or server location as the MDB itself.

In detail:

• You may be able to safely migrate such a durable subscription topic MDB only if it is configured with TopicMessagesDistributionMode=Compatibility mode and generate-unique-client-id=false, or it is configured with TopicMessagesDistributionMode=one-copy-per-application mode. For more information, see "Deployment Elements and Annotations for MDBs" in Developing Message-Driven Beans for Oracle WebLogic Server.

• For all other durable topic MDB use cases, TopicMessageDistributionMode=one-copy-per-server, or TopicMessageDistributionMode=Compatibility and generate-unique-client-id=true, the MDB's subscription name contains the local server name, and migrating such MDBs will cause their original durable subscriptions to be abandoned. Not only will the unprocessed messages that are associated with an abandoned durable subscription be lost, also an abandoned durable subscription will continue to accumulate messages, which consumes system memory and eventually may take the system down. As a result, migrating such a durable MDB requires additional caution even if it connects to a non-clustered, cluster singleton, distributed topic, or third party topic. Administrators must ensure that the subscriptions that were generated by such an MDB running at the original location are deleted during the migration.

When the destination that a MDB listens to is in a separate resource group or partition, you can perform a live migration of the MDB containing resource group but the above considerations for topic MDBs about abandoned durable subscriptions still apply.

Note that when a durable MDB listens to a distributed topic, the associated durable subscriptions may be abandoned when the distributed topic migrates even when the MDB does not migrate. For details about deleting such distributed topic state prior to completing a migration, see Migrating Persistent Data for a Cluster Distributed Service.

It is important to complete all pending, also known as "in doubt", transactions before migrating a Java EE application that integrates with a third party JMS provider. (In this case, a third party JMS provider is a provider that is neither WL JMS or AQ JMS).

When a Java EE application deployed on a WebLogic Server instance or cluster integrates a third party JMS provider with global transactions, an internal XA resource name is formed under which a foreign XA resource is registered with a WebLogic transaction manager. Those names often contain the local WebLogic Server instance name, which may change after such an application migrates as part of a resource group migration. This may cause in-doubt transactions that cannot be resolved after a migration because the transaction managers will try to resolve them using the original name.

In order to work seamlessly with remote JMS resources that can migrate with their containing resource group, JMS client code needs to follow the known best practice of closing all JMS and JNDI connections and reconnecting to JMS after a JMS failure. For more information, see "Best Practices for JMS Beginners and Advanced Users" in Administering JMS Resources for Oracle WebLogic Server. Note that certain containers and services can do this automatically on a client's behalf, namely MDBs, in-bound SOA JMS adapters, and messaging bridges. In addition, such a JMS client needs to ensure that the reconnection logic uses a URL that will resolve to the new location.

When a JMS resource is migrated in a resource group migration, a client may get an exception via exception listener callbacks, or get an exception on a sync call. The client then needs to reestablish connectivity using a new URL that points to the new location of the resource, or using the original URL if an address remapping capability is used during the migration. Examples of DNS remapping include a direct change to a DNS mapping or by using Oracle Traffic Director TCP proxy. When re-establishing, the client will need to retrace the steps it used when establishing its initial connectivity: namely obtaining the initial context, destination lookup, connection factory lookup, connection creation, session creation, producer creation, and finally consumer creation.

Note that JMS client failover behaviors described in the following sections apply to not only standalone clients, but remote or local Java EE applications, such as MDB, and SOA JMS adapter, and messaging bridge as well.