Programming WebLogic JMS

Introduction to WebLogic JMS

The following sections provide an overview of the Java Message Service (JMS) for BEA WebLogic Server:

Overview of WebLogic JMS

WebLogic JMS is an enterprise-class messaging system that is tightly integrated into the WebLogic Server platform. It fully supports the JMS Specification and also provides numerous WebLogic JMS Extensions that go above and beyond the standard JMS APIs.

What Is the Java Message Service?

An enterprise messaging system, also referred to as message-oriented middleware (MOM), enables applications to communicate with one another through the exchange of messages. A message is a request, report, and/or event that contains information needed to coordinate communication between different applications. A message provides a level of abstraction, allowing you to separate the details about the destination system from the application code.

The Java Message Service (JMS) is a standard API for accessing enterprise messaging systems. Specifically, JMS:

Enables Java applications sharing a messaging system to exchange messages
Simplifies application development by providing a standard interface for creating, sending, and receiving messages

The following figure illustrates WebLogic JMS messaging.

Figure 1-1 WebLogic JMS Messaging

WebLogic JMS Messaging

As illustrated in the figure, WebLogic JMS accepts messages from producer applications and delivers them to consumer applications.

Implementation of Java Specifications

WebLogic Server is compliant with the following Java specifications.

J2EE Specification

WebLogic Server is compliant with the Sun Microsystems J2EE 1.3 specification.

JMS Specification

WebLogic Server is fully compliant with version 1.0.2b of the JMS Specification, and can be used in production.

WebLogic JMS Features

WebLogic JMS provides numerous WebLogic JMS Extension APIs that go above and beyond the standard JMS APIs specified by the JMS Specification. Moreover, it is tightly integrated into the WebLogic Server platform, allowing you to build highly-secure J2EE applications that can be easily monitored and administered through the WebLogic Server console. In addition to fully supporting XA transactions, WebLogic JMS also features high availability through its clustering and service migration features, while also providing seamless interoperability with other versions of WebLogic Server and third-party messaging providers.

The following sections provide an overview of the unique features and powerful capabilities of WebLogic JMS.

Enterprise-Grade Reliability

Out-of-the-box transaction support:

Fully supports transactions, including distributed transactions, between JMS applications and other transaction-capable resources using the Java Transaction API (JTA), as described in Using Transactions with WebLogic JMS.
Fully-integrated Transaction Manager, as described in "Introducing Transactions" in Programming WebLogic JTA.

File or database persistent message storage (both fully XA transaction capable), as described in Configuring JMS in the Administration Console Online Help.
Supports connection clustering using multiple connection factories on multiple WebLogic Servers, as described in Configuring WebLogic JMS Clustering.
Distributed destinations that provide higher destination availability, load balancing, and failover support in a cluster, as described in Using Distributed Destinations.
Failed server migration for manually restarting JMS servers on another WebLogic Server instance in a cluster, as described in Recovering from a WebLogic Server Failure.
Redirects failed or expired messages to error destinations, as described in Managing Rolled Back, Recovered, Redelivered, or Expired Messages.
Provides three levels of load balancing: network-level, JMS connections, and distributed destinations.

Enterprise-Level Features

Message paging during peak load periods to free up virtual memory, as described in "Paging Out Messages To Free Up Memory" in the Administration Console Online Help.
Message flow control during peak load periods, including blocking overactive senders, as described in "Controlling the Flow of Messages on JMS Servers and Destinations" and "Avoiding Quota Exceptions by Blocking Message Producers" in the Administration Console Online Help.
Timer services available for scheduled message delivery, as described in Setting Message Delivery Times
Multicasting of messages for simultaneous delivery to many clients using IP multicast, as described in Using Multicasting.
Flexible expired message policies to handle expired messages, as described in "Handling Expired Messages" in the Administration Console Online Help.
Supports messages containing XML (Extensible Markup Language), as described in Defining XML Message Selectors Using XML Selector Method.
Thin application client .JAR that provides full WebLogic Server J2EE functionality, including JMS, yet greatly reduces the client-side WebLogic footprint, as described in WebLogic JMS Thin Client.
Automatic pooling of JMS client resources in server-side applications via JMS resource-reference pooling. Server-side applications use standard JMS APIs, but get automatic resource pooling, as described in Using JMS with EJBs and Servlets.

Tight Integration With WebLogic Server

JMS can be accessed locally by server-side applications without a network call because the destinations can exist on the same server as the application.
Uses same ports, protocols, and user identities as WebLogic Server (T3, IIOP, and HTTP tunnelling protocols, optionally with SSL).
Web Services, EJBs, and servlets supplied by WebLogic Server can work in close concert with JMS.
Can be configured and monitored by using the same Administration Console, as described in Configuring JMS, Tuning JMS, and Monitoring JMS, or by using the JMS API.
Complete JMX administrative and monitoring APIs, as described in Programming WebLogic Management Services with JMX.
Fully-integrated Transaction Manager, as described in "Introducing Transactions" in Programming WebLogic JTA.
Leverages sophisticated security model built into WebLogic Server (policy engine), as described in the Introduction to WebLogic Security and "JMS (Java Message Service) Resources" in Securing WebLogic Resources.

Interoperability with Other Messaging Services

Messages forwarded transactionally by the WebLogic Messaging Bridge to other JMS providers — as well as to other instances and versions of WebLogic JMS, as described in "WebLogic Messaging Bridge" in the Administration Console Online Help.
Supports mapping of other JMS providers so their objects appear in the WebLogic JNDI tree as local JMS objects. Can also reference remote instances of WebLogic Server in another cluster or domain in the local JNDI tree. For more information, see "Simple Access to Remote or Foreign JMS Providers" in the Administration Console Online Help.
Uses MDBs to transactionally receive messages from multiple JMS providers, as described in "Message-Driven EJBs" in Programming WebLogic Enterprise JavaBeans.
Reliable Web Services integration with JMS as a transport, as described in "Using JMS Transport to Invoke a WebLogic Web Service" in Programming WebLogic Web Services.
Automatic transaction enlistment of non-WebLogic JMS client resources in server-side applications via JMS resource-reference pooling. Server-side applications use standard JMS APIs, but get automatic transaction enlistment, as described in Using JMS with EJBs and Servlets.
Seamless integration with BEA Tuxedo messaging provided by WebLogic Tuxedo Connector as described in "How to Configure the Tuxedo Queuing Bridge" in the WebLogic Tuxedo Connector Administration Guide.

WebLogic JMS Architecture

The following figure illustrates the WebLogic JMS architecture.

Figure 1-2 WebLogic JMS Architecture

WebLogic JMS Architecture

Major Components

The major components of the WebLogic JMS Server architecture, as illustrated in Figure 1-2, include:

WebLogic JMS servers that implement the messaging facility. A JMS server defines a set of destinations (queues or topics) and any associated persistent storage that reside on a WebLogic Server instance. A JMS server manages connections and handles all message requests for its destinations on behalf of clients.
Client applications
JNDI (Java Naming and Directory Interface), which provides a server lookup facility
Persistent storage (disk-based file or JDBC-accessible database) for storing persistent message data

Clustering Features

The WebLogic JMS architecture implements clustering of multiple JMS servers by supporting cluster-wide, transparent access to JMS destinations from any server in the cluster. Although WebLogic Server supports distributing JMS destinations and connection factories throughout a cluster, JMS topics and queues are still managed by WebLogic Server instances in the cluster.

For more information about configuring clustering for WebLogic JMS, see Configuring WebLogic JMS Clustering. For detailed information about WebLogic Server clustering, see Using WebLogic Server Clusters.

The advantages of clustering include the following:

Load balancing of destinations across multiple servers in the cluster

An administrator can establish load balancing of destinations across multiple servers in the cluster by configuring multiple JMS servers and targeting them to the defined WebLogic Servers. Each JMS server is deployed on exactly one WebLogic Server instance and handles requests for a set of destinations.

Note: Load balancing is not dynamic. During the configuration phase, the system administrator defines load balancing by specifying targets for JMS servers.

An administrator can configure multiple physical destinations as members of a single distributed destination set within a cluster. Producers and consumers are able to send and receive to the distributed destination. In the event of a single server failure within the cluster, WebLogic JMS then distributes the load across all available members within the distributed destination set. For more information on distributed destinations, see "Distributed Destination Tasks" in the Administration Console Online Help.

Cluster-wide, transparent access to destinations from any server in the cluster

An administrator can establish cluster-wide, transparent access to destinations from any server in the cluster by either enabling 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 Server instances.
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. If requests for destinations are sent to a WebLogic Server instance that is hosting a connection factory, but which is not hosting a JMS server or destinations, the requests are forwarded by the connection factory to the appropriate WebLogic Server instance that is hosting the JMS server and destinations.
Connection factories are described in more detail in WebLogic JMS Fundamentals.

Scalability is provided by:

Load balancing of destinations across multiple servers in the cluster, as described previously.
Distribution of application load across multiple JMS servers through connection factories, thus reducing the load on any single JMS server and enabling session concentration by routing connections to specific servers.
Optional multicast support, reducing the number of messages required to be delivered by a JMS server. The JMS server forwards only a single copy of a message to each host group associated with a multicast IP address, regardless of the number of applications that have subscribed.

Migratability

As an "exactly-once" service, WebLogic JMS takes advantage of the migration framework implemented in WebLogic Server for clustered environments. This allows WebLogic JMS to respond properly to migration requests and to 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.

Server affinity for JMS Clients

When configured for the cluster, load balancing algorithms (round-robin-affinity, weight-based-affinity, or random-affinity), provide server affinity for JMS client connections. If a JMS application has a connection to a given server instance, JMS attempts to establish new JMS connections to the same server instance. For more information on server affinity, see "Load Balancing in a Cluster" in Using WebLogic Server Clusters.

Note: Automatic failover is not supported by WebLogic JMS for this release. For information about performing a manual failover, refer to Recovering from a WebLogic Server Failure.

WebLogic JMS Public API Extensions

In addition to the API specified by the Sun Microsystems JMS Specification, WebLogic JMS provides a public API, weblogic.jms.extensions, which includes classes and methods for the extensions described in the following table.

Table 1-1 WebLogic JMS Public API Extensions

Class	Function	For more information, see. . .
XMLMessage	Create XML messages	Step 6a: Create the Message Object (Message Producers)
WLSession	Define a session exception listener	Defining a Session Exception Listener
WLSession	Set or display the maximum number of pre-fetched asynchronous messages allowed on a multicast session	Dynamically Configuring Multicasting Configuration Attributes
WLSession	Set or display the multicast session overrun policy that is applied when the message maximum is reached	Dynamically Configuring Multicasting Configuration Attributes
JMSHelper	Dynamically create permanent queues or topics	Creating Destinations Dynamically
JMSHelper	Dynamically delete permanent queues or topics	Deleting Destinations Dynamically
JMSHelper	Dynamically create and delete a distributed destination (DD). These methods will also create or delete the DD queue or topic members on each specified JMS server instance, as well as a JMS template that will be used for all the member destinations.	"JMS Helper" Javadoc.
WLSession	Set a redelivery delay for messages	Setting a Redelivery Delay for Messages
WLMessageProducer	Set a message delivery time for producers	Setting a Delivery Time on Producers
WLMessage	Set a delivery time for messages	Setting a Delivery Time on Messages
Class Schedule	Set a scheduled delivery time for messages	Setting a Scheduled Time-to-Deliver Override
ServerSessionPoolFactory	Create server session pools, an optional application server facility described in the JMS specification	Defining Server Session Pools

This API also supports NO_ACKNOWLEDGE and MULTICAST_NO_ACKNOWLEDGE acknowledge modes, and extended exceptions, including throwing an exception:

To the session exception listener (if set), when one of its consumers has been closed by the server as a result of a server failure, or administrative intervention.
From a multicast session when the number of messages received by the session, but not yet delivered to the message listener, exceeds the maximum number of messages allowed for that session.
From a multicast consumer when it detects a sequence gap (message received out of sequence) in the data stream.

JMS Enhancements in WebLogic Server 8.1

The following JMS enhancements are new to this release of WebLogic Server.

JMS Thin Client

At approximately 400KB, the JMS thin application client (wljmsclient.jar) file provides full WebLogic JMS functionality, yet greatly reduces the client-side WebLogic footprint by using a smaller library that contains only the set of supporting files required by client-side programs. The JMS thin client also requires using the standard WebLogic thin application client JAR (wlclient.jar), around 300KB, which contains the base client support for clustering, security, and transactions, and failover. See WebLogic JMS Thin Client.

Simplified Access to Remote or Third-Party JMS Providers

Using the Foreign JMS Server node on the Administration Console, you can quickly map a foreign (non-WebLogic Server) JMS provider so that its connection factories and destinations appear in the WebLogic JNDI tree as local JMS objects. A Foreign JMS Server configuration can also be used to reference remote instances of WebLogic Server in another cluster or domain in the local WebLogic JNDI tree. See "Simple Access to Remote or Foreign JMS Providers" in the Administration Console Online Help.

Easier Access to JMS Through EJBs and Servlets

WebLogic Server now uses JMS wrappers that make it easier to use WebLogic JMS inside a J2EE component, such as an EJB or a servlet, while also providing a number of enhanced usability and performance features: automatic pooling of JMS connection and session objects (and some pooling of message producer objects as well); automatic transaction enlistment for WebLogic JMS implementations and for third-party JMS providers that support two-phase commit transactions (XA protocol); testing of the JMS connection, as well as re-establishment after a failure; and security credentials that are managed by the container. See Using JMS with EJBs and Servlets.

Better Expired Message Handling

Active message expiration ensures that expired messages are cleaned up immediately. Moreover, expired message auditing gives you the option of tracking expired messages, either by logging when a message expires or by redirecting expired messages to a special destination. For more information, see "Handling Expired Messages" in the Administration Console Online Help.

Improved Message Flow Control by Blocking Producers

The "Blocking Send" features help you avoid receiving message quota errors by temporarily blocking message producers from sending messages to a destination (queue or topic) when the destination has exceeded its specified maximum message quota. See "Avoiding Quota Exceptions by Blocking Message Producers" in the Administration Console Online Help.

Ordered Redelivery of Messages

As per the JMS Specification, all messages initially delivered to a consumer from a given producer are guaranteed to arrive at the consumer in the order in which they were produced. WebLogic JMS goes above and beyond this requirement by guaranteeing the correct ordering of redelivered messages as well. For more information, see Ordered Redelivery of Messages.

Dynamically Deleting Queue or Topic Destinations

New JMS Helper extension methods enable you to dynamically delete JMS destinations. The JMS server removes the deleted destination in real time; therefore, it is unnecessary to redeploy the JMS server for the deletion to take effect. See Deleting Destinations Dynamically.

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. See "Configuring WebLogic Platform."

JMS Deprecations in WebLogic Server 8.1

The following JMS deprecations occurred in this release of WebLogic Server.

ServerSessionPoolFactory Class in the weblogic.jms Package

The ServerSessionPoolFactory class in the weblogic.jms package is deprecated in WebLogic Server 8.1 and is replaced by the ServerSessionPoolFactory class in the weblogic.jms.extensions package. Although BEA recommends using the new version in the weblogic.jms.extensions package when binding a ServerSessionPoolFactory into JNDI. However, for release 8.1 you can still perform the JNDI lookup with either version. For more information about server session pool factories, see Defining Server Session Pools or the weblogic.jms.extensions.ServerSessionPoolFactory Javadoc.

Boot Flags for Disabling Synchronous Writes on JMS File Stores

The following command-line boot flags for disabling synchronous writes on JMS file stores are deprecated in WebLogic Server 8.1:

-Dweblogic.JMSFileStore.SynchronousWritesEnabled=false

-Dweblogic.JMSFileStore.store-name.SynchronousWritesEnabled=false

Instead, use JMS -> Stores node on the Administration Console or JMX to configure the JMS file store Synchronous Write Policy attribute. For more information about configuring the Synchronous Write Policy, see "Improving JMS File Store Performance" in the Administration Console Online Help.

JMS Connection Factory "User Transactions Enabled" and "Server Side XA Enabled" Attributes

The "User Transactions Enabled" and "Server Side XA Enabled" attributes are deprecated in WebLogic Server 8.1 for user-defined JMS connection factories. Therefore, to enable an XA connection factory for JTA user-transactions, you need only set the "XA Connection Factory Enabled" attribute. An XA factory is not required for transacted sessions. For more information about configuring a connection factory, see "Configuring a JMS Connection Factory" in the Administration Console Online Help.