Skip navigation.

eDocs Home > BEA WebLogic Server 8.1 Documentation > Programming WebLogic JMS > Managing WebLogic JMS

Programming WebLogic JMS

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents Index View as PDF   Get Adobe Reader

Managing WebLogic JMS

The WebLogic Server Administration Console provides an interface for easily enabling, configuring, and monitoring the features of the WebLogic Server, including JMS. To invoke the Administration Console, refer to the procedures described in "Starting and Stopping Servers" in the Administration Console Online Help.

The following sections provide an overview of configuring and monitoring WebLogic JMS:

 

Configuring WebLogic JMS

Using the Administration Console, you define configuration attributes to:

Modifying Default Values for Configuration Attributes

WebLogic JMS provides default values for some configuration attributes; you must provide values for all others. If you specify an invalid value for any configuration attribute, or if you fail to specify a value for an attribute for which a default does not exist, WebLogic Server will not boot JMS when you restart it. To see the default values for all configurable JMS attributes, see "Attributes and Console Screen Reference for JMS" in the Administration Console Online Help.

A sample examplesJMSServer configuration is provided with the product in the Examples Server. For more information about starting the Examples Server, see "Starting and Stopping Servers: Quick Reference" in the Administration Guide.

To configure WebLogic JMS attributes, follow the procedures described in the "Configuring JMS" section of the Administration Console Online Help, to create and configure the JMS objects. Once WebLogic JMS is configured, applications can send and receive messages using the JMS API. For more information about developing WebLogic JMS applications, refer to Developing a WebLogic JMS Application.

When migrating from a previous release of Weblogic Server, the configuration information is converted automatically, as described in Porting Existing Applications.

Starting WebLogic Server and Configuring JMS

The following sections review how to start WebLogic Server and the Administration Console, as well as provide a procedure for configuring a basic WebLogic JMS implementation.

Starting the Default WebLogic Server

The default role for a WebLogic Server is the Administration Server. If a domain consists of only one WebLogic Server, that server is the Administration Server. If a domain consists of multiple WebLogic Server instances, you must start the Administration Server first, and then you start the Managed Servers.

For complete information about starting the Administration Server, see "Starting and Stopping Servers" in the Administration Console Online Help.

Starting the Administration Console

The Administration Console is the Web-based administrator front-end (administrator client interface) to WebLogic Server. You must start the server before you can access the Administration Console for a server.

For complete details about using the Administration Console to configure a WebLogic Server instance, see "Starting and Using the Administration Console" in Configuring and Managing a WebLogic Server.

Manually Configuring a Basic JMS Implementation

This section describes how to configure a basic JMS implementation using the Administration Console.

  1. Under the Services node in the navigation tree, expand the JMS node.
  2. For storing persistent messages in a disk-based file, you must create a JMS file store. If your are using the JMS Paging feature, you must also configure an additional "paging" JMS file store for temporarily swapping message bodies out to memory.
    1. Create a directory on the file system where the JMS file store will be kept.
    2. Expand the JMS —> Stores node, and then click the Configure a new JMS File Store link in the right pane.
    3. On the General tab, give the store a name, specify the pathname to the file store directory, and optionally, select a Synchronous Write policy to determine how the JMS file store writes data to disk.
    4. Click Create.
    5. Repeat these steps to create a "paging" JMS file store.

    For more information on configuring a JMS file store and a paging file store, see "JMS File Store Tasks" in the Administration Console Online Help.

  3. For storing persistent messages in a JDBC-accessible database, you must create a JMS JDBC store. (If you need to create a JDBC connection pool, then first complete steps A-C; otherwise, you can skip to step D.)
    1. Click to expand the Services and JDBC nodes.
    2. Right-click the Connection Pools node and select Configure a New JDBC Connection Pool. The JDBC Connection Pool Assistant opens in the right pane.
    3. Follow the directions in "Using the JDBC Connection Pool Assistant" to configure a connection pool.
    4. Expand the JMS —> Stores node, and then click the Configure a new JMS JDBC Store link in the right pane.
    5. Give the JDBC Store a name, select a connection pool, and enter a prefix name.
    6. Click Create.

      7. Note: For more information on configuring JDBC connections pools and JMS JDBC stores, see "JMS JDBC Store Tasks", "JDBC Connection Pools," "JDBC Multipools," and "JDBC DataSources" in the Administration Console Online Help.

  4. Optionally, you can create a JMS Template to define multiple destinations with similar attribute settings. You also need a JMS Template to create temporary queues.
    1. Click the Templates node in the left pane, and then click the Configure a new JMS Template link in the right pane.
    2. On the General tab, give the template a name, and then click Create.
    3. Fill in the Thresholds & Quotas, Override, Expiration Policy, and Redelivery tabs, as appropriate. Click Apply on each tab when you are done making changes.

    For more information on configuring a JMS template, see "JMS Template Tasks" in the Administration Console Online Help.

  5. Configure a JMS Server, as follows:
    1. Expand the Server node, and then click the Configure a new JMS Server link in the right pane.
    2. On the General tab, give the server a name, select a Store if you created one, select a Paging Store if you created one, and select a Template if you created one. Then click Create.
    3. Fill in the Thresholds & Quotas tab, as appropriate. Click Apply when you are done making changes.
    4. On the Target and Deploy tab, target an independent WebLogic Server instance or a Migratable Target server on which to deploy the JMS server by selecting the appropriate check box, and then click Apply.

    For more information on configuring a JMS server, see "JMS Server Tasks" in the Administration Console Online Help.

  6. Create the JMS Destinations, which are queues (Point-To-Point) or topics (Publish/Subscribe):
    1. Under the Servers node, click the new JMS server instance to expand the list, and then click the Destinations node.
    2. Click either the Configure a new JMS Queue or Configure a new JMS Topic link in the right pane.
    3. On the General tab, give the destination a name and a JNDI name. Fill in the other attributes, as appropriate, and then click Create.
    4. Fill in the Thresholds & Quotas, Override, Redelivery, Expiration Policy, and Multicast (for topics only) tabs, as appropriate. Click Apply on each tab when you are done making changes.

    For more information on configuring a JMS destination, see "JMS Destination Tasks" in the Administration Console Online Help.

  7. If the default connection factories provided by WebLogic JMS are not suitable for your application, create a new Connection Factory to enable your JMS clients to create JMS connections:
    1. Click to the expand the Connection Factory node and in the left pane, and then click the Configure a new JMS Connection Factory link in the right pane.
    2. On the General tab, give the connection factory a name and a JNDI name. Fill in the other attributes, as appropriate, and then click Create.
    3. Fill in the Transactions and Flow Control tabs, as appropriate. Click Apply on each tab when you are done making changes.
    4. On the Target and Deploy tab, target an independent WebLogic Server instance or a server cluster on which to deploy the connection factory by selecting the appropriate check box, and then click Apply.

    For more information about using the default connection factories, see Using the Default Connection Factories. For more information on configuring a Connection Factory, see "JMS Connection Factory Tasks" in the Administration Console Online Help.

  8. As messages arrive on a destination, by default they are sorted in FIFO (first-in, first-out) order, which sorts ascending based on each message's unique JMSMessageID. However, if you want to configure a different sorting scheme, use the Destination Keys node to define another sort order (like LIFO, last-in, first-out). For more information, see "JMS Destination Key Tasks" in the Administration Console Online Help.
  9. Optionally, use the Distributed Destinations node to make your physical destinations part of a single distributed destination set within a server cluster for higher availability and load balancing. For more information, see "Distributed Destinations Tasks" in the Administration Console Online Help.
  10. Optionally, create JMS Session Pools, which enable your applications to process messages concurrently, and Connection Consumers (queues or topics) that retrieve server sessions and process messages. For more information, see "JMS Session Pools Tasks" and "JMS Connection Consumers Tasks" in the Administration Console Online Help.

Using the Configuration Wizard to Configure JMS

The Configuration Wizard is a Java application that creates WebLogic Server administration domain and server configurations. You can use the Configuration Wizard to configure such resources as JMS, database connectivity (JDBC), and security groups, security roles, and user accounts. You can also use the Configuration Wizard to modify existing domains. For more information, see "Configuring a Java Messaging Service" in Creating WebLogic Configurations Using the Configuration Wizard.

 

Configuring WebLogic JMS Clustering

A WebLogic Server cluster is a group of servers in a domain that work together to provide a more scalable, more reliable application platform than a single server. A cluster appears to its clients as a single server but is in fact a group of servers acting as one. A cluster provides four key features above a single server:

For more information about the features and benefits of using WebLogic clusters, see "Introduction to WebLogic Server Clusters" in Using WebLogic Server Clusters.

Obtain a Clustered JMS Licence

In order to implement JMS clustering, you must have a valid clustered JMS license, which allows a connection factory and a destination to be on different WebLogic Server instances. A clustered JMS license is also required to use the Foreign JMS Providers feature, as described in "Simple Access to Remote or Foreign JMS Providers" in the Administration Console Online Help. If you do not have a valid clustered JMS license, contact your BEA sales representative.

How JMS Clustering Works

An administrator can establish cluster-wide, transparent access to JMS destinations from any server in the cluster, either by using the default connection factories for each server instance in the cluster, or by configuring one or more connection factories and targeting them to one or more server instances in the cluster. This way, each connection factory can be deployed on multiple WebLogic Servers. However, each user-defined connection factory must be uniquely named to be successfully deployed on multiple WebLogic Servers. For information on configuring and deploying connection factories, or about using the default connection factories, see "JMS Connection Factory Tasks" in the Administration Console Online Help.

The administrator can also configure multiple JMS servers on the various server instances in the cluster—as long as the JMS servers are uniquely named—and can then assign JMS destinations to the various JMS servers. The application uses the Java Naming and Directory Interface (JNDI) to look up a connection factory and create a connection to establish communication with a JMS server. Each JMS server handles requests for a set of destinations. Requests for destinations not handled by a JMS server are forwarded to the appropriate WebLogic Server instance. For information on configuring and deploying JMS servers, see "JMS Server Tasks" in the Administration Console Online Help.

JMS Clustering Naming Requirements

The following guidelines apply when configuring WebLogic JMS to work in a clustered environment in a single domain or multi-domain environment.

For more information about JMS resource naming rules in single domain and multi-domain environments, see "JMS Resource Naming Rules for Domain Interoperability" in the Administration Console Online Help.

JMS Distributed Destination Within a Cluster

A distributed destination is a set of physical destinations that are called under a single JNDI name so they appear to be a single, logical destination to a client, when the members of the set are actually distributed across multiple servers within a cluster, with each destination member belonging to a separate JMS server. This way, WebLogic JMS supports high availability and load balancing of among physical destinations within a cluster. When one member becomes unavailable due a server failure, traffic is then redirected toward other available members. For more information on configuring a distributed destination, see "Distributed Destination Tasks" in the Administration Console Online Help.

JMS As a Migratable Service Within a Cluster

WebLogic JMS takes advantage of the migration framework implemented in the WebLogic Server core for clustered environments. This allows WebLogic JMS to properly respond to migration requests and bring a JMS server online and offline in an orderly fashion. This includes both scheduled migrations as well as migrations in response to a WebLogic Server failure. For more information, see Configuring Migratable Targets for JMS Servers.

Configuration Guidelines for JMS Clustering

In order to use WebLogic JMS in a clustered environment, follow these guidelines:

  1. Configure your clustered environment as described in "Setting Up WebLogic Clusters" in Using WebLogic Server Clusters.
  2. Identify server targets for JMS connection factories using the Administration Console. For connection factories, you can identify either a single-server target or a cluster target, which are server instances that are associated with a connection factory to support clustering.

    3. For more information about these connection factory configuration attributes, see "JMS Connection Factory Tasks" in the Administration Console Online Help.

  3. Optionally, identify migratable server targets for JMS servers using the Administration Console. For JMS servers, you can identify either a single-server target or a migratable target, which is a set of server instances in a cluster that can host an "exactly-once" service like JMS in case of a server failure in the cluster.

    4. For more information on migratable JMS server targets, see Configuring Migratable Targets for JMS Servers. For more information about JMS server configuration attributes, see "JMS Server Tasks" in the Administration Console Online Help.

    Note: You cannot deploy the same destination on more than one JMS server. In addition, you cannot deploy a JMS server on more than one WebLogic Server.

  4. Optionally, you can configure the physical JMS destinations in a cluster as part of a distributed destination set, as discussed in JMS Distributed Destination Within a Cluster.

What About Failover?

For WebLogic Server instances that are part of a clustered environment, WebLogic JMS offers service continuity in the event of a single server failure by enabling you to configure multiple physical destinations (queues and topics) as part of a single distributed destination set. In addition, implementing the Migratable Service feature, will ensure that pinned "exactly-once" services, like JMS, do not introduce a single point of failure for dependent applications in the cluster,

However, automatic failover is not currently supported by WebLogic JMS. For information about performing a manual failover, refer to Recovering from a WebLogic Server Failure.

 

Configuring Migratable Targets for JMS Servers

As an exactly-once service, a JMS server is not active on all WebLogic Server instances in a cluster. It is instead "pinned" to a single server in the cluster to preserve data consistency. To ensure that pinned services do not introduce a single point of failure for dependent applications in the cluster, WebLogic Server can be configured to migrate exactly-once services to any server in the migratable target list.

WebLogic JMS takes advantage of the migration framework by allowing an administrator to specify a migratable target for a JMS server in the Administration Console. Once properly configured, a JMS server and all of its destinations can migrate to another WebLogic Server within a cluster.

This allows WebLogic JMS to properly respond to migration requests and bring a JMS server online and offline in an orderly fashion. This includes both scheduled migrations as well as migrations in response to a WebLogic Server failure within the cluster.

For more information about the migration of pinned services, see "Migration for Pinned Services" in Using WebLogic Server Clusters.

Configuration Steps for JMS Service Migration

In order to make a JMS server a migratable service in a clustered environment, you must do the following:

  1. Optionally, familiarize yourself with how server migration for pinned services works by reading "Migration for Pinned Services" in Using WebLogic Server Clusters.
  2. For JMS implementations that use persistent messaging, make sure that the JMS store is configured such that all the candidate servers in a migratable target share access to the store. For more information about migrating JMS stores, see JMS Store Migration.
  3. Configure a migratable target server for the cluster that can potentially host a JMS server, as described in "Configure Migratable Targets for Pinned Services" in Using WebLogic Server Clusters.

    4. Note: You must set a unique Listen Address value for the migratable target server instance that will host a migrated the JMS server; otherwise, the migration will fail.

  4. Identify a migratable target server instance on which to deploy a JMS server as described in "Deploying JMS to a Migratable Target Server Instance" in Using WebLogic Server Clusters.

    5. Note: When a migratable target server boots, the JMS server automatically boots as well on the user-preferred server in the cluster.

  5. You can also manually migrate a JMS server and all of its destinations before performing server maintenance or to a healthy server if the host server fails. For more information, see "Migrating a Pinned Service To a Target Service Instance" in Using WebLogic Server Clusters.

    6. Note: A JMS server's distributed destination members can migrate to another server instance within a cluster—even when the target server instance is already hosting a JMS server with its own distributed destination members. For more information about distributed destination failover, see Distributed Destination Failover.

Caution: When migrating a JMS service that solely participates in a global transaction, for the migration to work and not leave any pending transactions, you must migrate both the JMS and JTA services, and the JMS service migration must occur before the JTA service migration.

JMS Store Migration

JMS file stores cannot be migrated along with JMS servers; therefore, applications that need access to persistent stores from other physical machines after the migration of a JMS server must implement an alternative solution, as follows:

 

Configuring JMS using JMX

JMS servers are WebLogic Server managed resources. As a managed resource, JMs includes a set of attributes that can be configured and monitored for management purposes. For example, each JMS server includes attributes that define its name, the name of its destinations, thresholds, and delivery parameters. You can manage both Configuration MBeans and Runtime MBeans. For more information, see Programming WebLogic Management Services with JMX.

The following code provides an example of using JMX to configure a JMS queue.

Listing 3-1 Create a JMS Queue Using JMX

import java.util.Iterator;
import java.util.Set;
import javax.management.ObjectName;
import javax.management.QueryExp;
import javax.management.Attribute;
import javax.naming.Context;
import weblogic.jndi.Environment;
import weblogic.management.MBeanHome;
import weblogic.management.RemoteMBeanServer;
import weblogic.management.WebLogicObjectName;
import weblogic.management.configuration.JMSQueueMBean;
import weblogic.management.configuration.JMSServerMBean;
import weblogic.management.configuration.JMSDestinationMBean;
import weblogic.management.runtime.JMSServerRuntimeMBean;

public class JMSAddQueue {

// The name of the WebLogic domain, please change this to match the //
// name of your installation specific domain name                   // 
private static String weblogicDomain = "mydomain";

// The name of the WebLogic server, please change this to match the //
// name of your installation specific server name                   //
private static String weblogicServer = "myserver";

// The name of the new JMSQueue you are creating                    //
private static String jmsQueue = "JMSQueue-7";


public static void main(String[] args) {

try {

   Environment env = new Environment();
   env.setProviderUrl("t3://localhost:7001");
   env.setSecurityPrincipal("weblogic");
   env.setSecurityCredentials("weblogic");
   Context ctx = env.getInitialContext();
   MBeanHome home = (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
   ctx.close();

   WebLogicObjectName aObjectName = new
   WebLogicObjectName("JMSServer1",
                      "JMSServer",
                       weblogicDomain);

   JMSServerMBean jmsServer = (JMSServerMBean)home.getMBean(aObjectName);

   // Create a new JMSQueueMBean
   JMSDestinationMBean destination = (JMSQueueMBean)
      home.createAdminMBean(jmsQueue,"JMSQueue");
   destination.setJNDIName("JNDINAME-"+jmsQueue);
   destination.setParent(jmsServer);
   jmsServer.addDestination(destination); 

   // Query the MBean Server to find the Queue we just created
   QueryExp query = null;
   RemoteMBeanServer bSvr = home.getMBeanServer();
   Set queueNames = bSvr.queryNames(new    ObjectName(weblogicDomain+":Type=JMSQueue,Name="+jmsQueue+",*"),query);
   ObjectName name = (ObjectName)queueNames.iterator().next();

   System.out.println("QUEUE MBEAN RETRIEVED: " + name);

   // Set the BytesMaximum attribute to something other
   // than the default value
   bSvr.setAttribute(name,new Attribute("BytesMaximum",new Long(10000))); 
   } catch (Exception e) {
   e.printStackTrace();
   }
  }
}

 

Tuning WebLogic JMS

The following sections explain how to get the most out of your applications by implementing the administrative performance tuning features available with WebLogic JMS.

 

Monitoring WebLogic JMS

Statistics are provided for the following JMS objects: JMS servers, connections, sessions, destinations, durable subscribers, message producers, message consumers, and server session pools. You can monitor JMS statistics using the Administration Console.

JMS statistics continue to increment as long as the server is running. Statistics can only be reset when the server is rebooted. For more information on configuring and monitoring WebLogic JMS, see "Monitoring JMS" in the Administration Console Online Help.

Once WebLogic JMS has been configured, applications can begin sending and receiving messages through the JMS API, as described in Developing a WebLogic JMS Application.

 

Recovering from a WebLogic Server Failure

The following sections describe how to terminate a JMS application gracefully if a server fails and how to migrate JMS data after server failure.

Programming Considerations

You may want to program your JMS application to terminate gracefully in the event of a WebLogic Server failure. For example:

Table 3-1 Programming Considerations for Server Failures

If a WebLogic Server Instance Fails and...

Then...

You are connected to the failed WebLogic Server instance

A JMSException is delivered to the connection exception listener. You must restart the application once the server is restarted or replaced.

A JMS Server is targeted on the failed WebLogic Server instance

A ConsumerClosedException is delivered to the session exception listener. You must re-establish any message consumers that have been lost.


 

Migrating JMS Data to a New Server

WebLogic JMS uses the migration framework implemented in the WebLogic Server core, which allows WebLogic JMS respond properly to migration requests and bring a WebLogic JMS server online and offline in an orderly fashion. This includes both scheduled migrations as well as migrations in response to a WebLogic Server failure.

Once properly configured, a JMS server and all of its destinations can migrate to another WebLogic Server within a cluster.

You can recover JMS data from a failed WebLogic Server by starting a new server and doing one or more of the tasks in Table 3-2.

Note: There are special considerations when you migrate a service from a server instance that has crashed or is unavailable to the Administration Server. If the Administration Server cannot reach the previously active host of the service at the time you perform the migration, see Migrating a Service When Currently Active Host is Unavailable.

Table 3-2 Migration Task Guide

If Your JMS Application Uses. . .

Perform the Following Task. . .

Persistent messaging—JDBC Store

  • If the JDBC database store physically exists on the failed server, migrate the database to a new server and ensure that the JDBC connection pool URL attribute reflects the appropriate location reference.

  • If the JDBC database does not physically exist on the failed server, access to the database has not been impacted, and no changes are required.

Persistent messaging—File Store

Migrate the file to the new server, ensuring that the pathname within the WebLogic Server home directory is the same as it was on the original server.

Transactions

To facilitate recovery after a crash, WebLogic Server provides the Transaction Recovery Service, which automatically attempts to recover transactions on system startup. The Transaction Recovery Service owns the transaction log for a server.

For detailed instructions on recovering transactions from a failed server, see "Transaction Recovery After a Server Fails" in the Administration Console Online Help.

Note: JMS persistent stores can increase the amount of memory required during initialization of WebLogic Server as the number of stored messages increases. When rebooting WebLogic Server, if initialization fails due to insufficient memory, increase the heap size of the Java Virtual Machine (JVM) proportionally to the number of messages that are currently stored in the JMS persistent store and try the reboot again.

For information about starting a new WebLogic Server, see "Starting and Stopping Servers" in the Administration Console Online Help. For information about recovering a failed server, refer to Recovering Failed Servers in the Configuring and Managing WebLogic Domains guide.

For more information about defining migratable services, see "Migration for Pinned Services" in Using WebLogic Server Clusters.

 

Skip navigation bar  Back to Top Previous Next