Programming 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:
Using the Administration Console, you define configuration attributes to:
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.
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.
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.
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.
This section describes how to configure a basic JMS implementation using the Administration Console.
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.
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.
For more information on configuring a JMS template, see "JMS Template Tasks" in the Administration Console Online Help.
For more information on configuring a JMS server, see "JMS Server Tasks" in the Administration Console Online Help.
For more information on configuring a JMS destination, see "JMS Destination Tasks" in the Administration Console Online Help.
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.
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.
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.
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.
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.
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.
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.
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.
In order to use WebLogic JMS in a clustered environment, follow these guidelines:
For more information about these connection factory configuration attributes, see "JMS Connection Factory Tasks" in the Administration Console Online Help.
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.
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.
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.
In order to make a JMS server a migratable service in a clustered environment, you must do the following:
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.
Note: When a migratable target server boots, the JMS server automatically boots as well on the user-preferred server in the cluster.
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 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:
For more information about configuring a JMS JDBC store, see "Configuring JDBC Stores" in the Administration Console Online Help.
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();
}
}
}
The following sections explain how to get the most out of your applications by implementing the administrative performance tuning features available with WebLogic JMS.
For more information, see "Improving JMS File Store Performance" in the Administration Console Online Help.
For more information, see "Paging Out Messages to Free Up Memory" in the Administration Console Online Help.
For more information, see "Controlling the Flow of Messages on JMS Servers and Destinations" in the Administration Console Online Help.
For more information, see "Avoiding Quota Exceptions by Blocking Message Producers" in the Administration Console Online Help.
For more information, see "Handling Expired Messages" in the Administration Console Online Help.
For more information, see "Tuning Distributed Destinations" in the Administration Console Online Help.
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.
The following sections describe how to terminate a JMS application gracefully if a server fails and how to migrate JMS data after server failure.
You may want to program your JMS application to terminate gracefully in the event of a WebLogic Server failure. For example:
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
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. |
|
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.
![]() ![]() |
![]() |
![]() |