BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
| WebLogic Server Doc Home | Programming WebLogic JMS | Previous Topic | Next Topic | Contents | Index | View as PDF

WebLogic JMS Fundamentals

The following sections describe WebLogic JMS components and features:

- Messaging Models

- WebLogic JMS Classes

- ConnectionFactory

- Connection

- Session

- Destination

- MessageProducer and MessageConsumer

- ServerSessionPoolFactory

- ServerSessionPool

- ServerSession

- ConnectionConsumer

Note: For more information on the JMS classes described in this section, access the latest JMS Javadoc, including the latest JMS API Errata, which is supplied on the Sun Microsystems Java Web site at the following locations:

>     http://www.javasoft.com/products/jms/Javadoc-102a/index.html

and

>     http://www.javasoft.com/products/jms/errata_051801.html

Messaging Models

JMS supports two messaging models: point-to-point (PTP) and publish/subscribe (Pub/sub). The messaging models are very similar, except for the following differences:

- PTP messaging model enables the delivery of a message to exactly one recipient.

- Pub/sub messaging model enables the delivery of a message to multiple recipients.

Each model is implemented with classes that extend common base classes. For example, the PTP class javax.jms.Queue and the Pub/sub class javax.jms.Topic both extend the class javax.jms.Destination.

Each message model is described in detail in the following sections.

Note: The terms producer and consumer are used as generic descriptions of applications that send and receive messages, respectively, in either messaging model. For each specific messaging model, however, unique terms specific to that model are used when referring to producers and consumers.

Point-to-Point Messaging

The point-to-point (PTP) messaging model enables one application to send a message to another. PTP messaging applications send and receive messages using named queues. A queue sender (producer) sends a message to a specific queue. A queue receiver (consumer) receives messages from a specific queue.

The following figure illustrates PTP messaging.

Figure 2-1 Point-to-Point (PTP) Messaging

Multiple queue senders and queue receivers can be associated with a single queue, but an individual message can be delivered to only one queue receiver.

If multiple queue receivers are listening for messages on a queue, WebLogic JMS determines which one will receive the next message on a first come, first serve basis. If no queue receivers are listening on the queue, messages remain in the queue until a queue receiver attaches to the queue.

Publish/Subscribe Messaging

The publish/subscribe (Pub/sub) messaging model enables an application to send a message to multiple applications. Pub/sub messaging applications send and receive messages by subscribing to a topic. A topic publisher (producer) sends messages to a specific topic. A t opic subscriber (consumer) retrieves messages from a specific topic.

The following figure illustrates Pub/sub messaging.

Figure 2-2 Publish/Subscribe (Pub/Sub) Messaging

Unlike with the PTP messaging model, the Pub/sub messaging model allows multiple topic subscribers to receive the same message. JMS retains the message until all topic subscribers have received it.

The Pub/sub messaging model supports durable subscribers, allowing you to assign a name to a topic subscriber and associate it with a user or application. For more information about durable subscribers, see Setting Up Durable Subscriptions.

Message Persistence

As per the "Message Delivery Mode" section of the JMS Specification, messages can be specified as persistent or non-persistent:

- A persistent message is guaranteed to be delivered once-and-only-once. This means a message cannot be lost and cannot be delivered twice. It is not considered sent until it has been safely written to a file or database. WebLogic JMS writes persistent messages to a persistent backing store (disk-base file or JDBC-accessible database) assigned to each JMS server during configuration.

- Non-persistent messages are not stored. They are guaranteed to be delivered at-most-once, unless there is a system failure, in which case messages may be lost. If a connection is closed or recovered, all non-persistent messages that have not yet been acknowledged will be redelivered. Once a non-persistent message is acknowledged, it will not be redelivered.

WebLogic JMS Classes

To create a JMS applications, use the javax.jms API. The API allows you to create the class objects necessary to connect to the JMS, and send and receive messages. JMS class interfaces are created as subclasses to provide queue- and topic-specific versions of the common parent classes.

The following table lists the JMS classes described in more detail in subsequent sections. For a complete description of all JMS classes, see the javax.jms, weblogic.jms.ServerSessionPoolFactory, or weblogic.jms.extensions Javadoc.

Table 2-1 JMS Classes

JMS Class | Description
--- | ---
ConnectionFactory | Encapsulates connection configuration information. A connection factory is used to create connections. You look up a connection factory using JNDI.
Connection | Represents an open communication channel to the messaging system. A connection is used to create sessions.
Session | Defines a serial order for the messages produced and consumed.
Destination | Identifies a queue or topic, encapsulating the address of a specific provider. Queue and topic destinations manage the messages delivered from the PTP and Pub/sub messaging models, respectively.
MessageProducer and MessageConsumer | Provides the interface for sending and receiving messages. Message producers send messages to a queue or topic. Message consumers receive messages from a queue or topic.
Message | Encapsulates information to be sent or received.
ServerSessionPoolFactory 1 | Encapsulates configuration information for a server-managed pool of message consumers. The server session pool factory is used to create server session pools.
ServerSessionPool1 | Provides a pool of server sessions that can be used to process messages concurrently for connection consumers.
ServerSession1 | Associates a thread with a JMS session.
ConnectionConsumer1 | Specifies a consumer that retrieves server sessions to process messages concurrently.

1 Supports an optional JMS interface for processing multiple messages concurrently.

For information about configuring JMS objects, see Managing WebLogic JMS. The procedure for setting up a JMS application is presented in Setting Up a JMS Application.

ConnectionFactory

A ConnectionFactory object encapsulates connection configuration information, and enables JMS applications to create a Connection. A system administrator configures connection factories to create connections with predefined attributes.

A system administrator defines and configures one or more connection factories, and the WebLogic Server adds them to the JNDI space during startup. The application then retrieves a connection factory using WebLogic JNDI.

The system administrator can also establish cluster-wide, transparent access to destinations from any server in the cluster by configuring multiple connection factories and using targets to assign them to WebLogic Servers. Each connection factory can be deployed on multiple WebLogic Servers. For more information on JMS clustering, refer to Configuring WebLogic JMS Clustering.

WebLogic JMS defines one default connection factory. It can be looked up using the JNDI name, weblogic.jms.ConnectionFactory. You only need to define a connection factory if the one provided by WebLogic JMS is not suitable for your application. For information on configuring connection factories, see "Managing JMS" in the Administration Guide.

Notes: For backwards compatibility, WebLogic JMS still supports two deprecated default connection factories. The JNDI names for these factories are: javax.jms.QueueConnectionFactory and javax.jms.TopicConnectionFactory.

For information on migrating to a new default or user-defined connection factory from a deprecated connection factory, refer to Migrating WebLogic JMS Applications.

The ConnectionFactory class does not define methods; however, its subclasses define methods for the respective messaging models. A connection factory supports concurrent use, enabling multiple threads to access the object simultaneously.

The following table describes the ConnectionFactory subclasses.

Table 2-2 ConnectionFactory Subclasses

Subclass. . . | In Messaging Model. . . | Is Used to Create. . .
--- | --- | ---
QueueConnectionFactory | PTP | QueueConnection to a JMS PTP provider.
TopicConnectionFactory | Pub/sub | TopicConnection to a JMS Pub/sub provider.

To learn how to use the ConnectionFactory class within an application, see Developing a WebLogic JMS Application, or the javax.jms.ConnectionFactory Javadoc.

Connection

A Connection object represents an open communication channel between an application and the messaging system, and is used to create a Session for producing and consuming messages. A connection creates server-side and client-side objects that manage the messaging activity between an application and JMS. A connection may also provide user authentication.

A Connection is created by a ConnectionFactory, obtained through a JNDI lookup.

Due to the resource overhead associated with authenticating users and setting up communications, most applications establish a single connection for all messaging. In the WebLogic Server, JMS traffic is multiplexed with other WebLogic services on the client connection to the server. No additional TCP/IP connections are created for JMS. Servlets and other server-side objects may also obtain JMS Connections.

By default, a connection is created in stopped mode. For information about how and when to start a stopped connection, see Starting, Stopping, and Closing a Connection.

Connections support concurrent use, enabling multiple threads to access the object simultaneously.

The following table describes the Connection subclasses.

Table 2-3 Connection Subclasses

Subclass. . . | In Messaging Model. . . | Is Used to Create. . .
--- | --- | ---
QueueConnection | PTP | QueueSessions, and consists of a connection to a JMS PTP provider created by QueueConnectionFactory.
TopicConnection | Pub/sub | TopicSessions, and consists of a connection to a JMS Pub/sub provider created by TopicConnectionFactory.

To learn how to use the Connection class within an application, see Developing a WebLogic JMS Application, or the javax.jms.Connection Javadoc.

Session

A Session object defines a serial order for the messages produced and consumed, and can create multiple message producers and message consumers. The same thread can be used for producing and consuming messages. If an application wants to have a separate thread for producing and consuming messages, the application should create a separate session for each function.

A Session is created by the Connection.

Note: A session and its message producers and consumers can only be accessed by one thread at a time. Their behavior is undefined if multiple threads access them simultaneously.

The following table describes the Session subclasses.

Table 2-4 Session Subclasses

Subclass. . . | In Messaging Model. . . | Provides a Context for. . .
--- | --- | ---
QueueSession | PTP | Producing and consuming messages for a JMS PTP provider. Created by QueueConnection.
TopicSession | Pub/sub | Producing and consuming messages for a JMS Pub/sub provider. Created by TopicConnection.

To learn how to use the Session class within an application, see Developing a WebLogic JMS Application, or the javax.jms.Session and weblogic.jms.extensions.WLSession javadocs.

Non-transacted Session

In a non-transacted session, the application creating the session selects one of the five acknowledge modes defined in the following table.

Table 2-5 Acknowledge Modes Used for Non-Transacted Sessions

Acknowledge Mode | Description
--- | ---
AUTO_ACKNOWLEDGE | The Session object acknowledges receipt of a message once the receiving application method has returned from processing it.
CLIENT_ACKNOWLEDGE | The Session object relies on the application to call an acknowledge method on a received message. Once the method is called, the session acknowledges all messages received since the last acknowledge. This mode allows an application to receive, process, and acknowledge a batch of messages with one call. Note: In the Administration Console, if the Acknowledge Policy attribute on the connection factory is set to Previous, but you want to acknowledge all received messages for a given session, then use the last message to invoke the acknowledge method. For more information on the Acknowledge Policy attribute, see "JMS Connection Factories" in the Administration Console Online Help.
DUPS_OK_ACKNOWLEDGE | The Session object acknowledges receipt of a message once the receiving application method has returned from processing it; duplicate acknowledges are permitted. This mode is most efficient in terms of resource usage. Note: You should avoid using this mode if your application cannot handle duplicate messages. Duplicate messages may be sent if an initial attempt to deliver a message fails.
NO_ACKNOWLEDGE | No acknowledge is required. Messages sent to a NO_ACKNOWLEDGE session are immediately deleted from the server. Messages received in this mode are not recovered, and as a result messages may be lost and/or duplicate message may be delivered if an initial attempt to deliver a message fails. This mode is supported for applications that do not require the quality of service provided by session acknowledge, and that do not want to incur the associated overhead. Note: You should avoid using this mode if your application cannot handle lost or duplicate messages. Duplicate messages may be sent if an initial attempt to deliver a message fails.
MULTICAST_NO_ACKNOWLEDGE | Multicast mode with no acknowledge required. Messages sent to a MULTICAST_NO_ACKNOWLEDGE session share the same characteristics as NO_ACKNOWLEDGE mode, described previously. This mode is supported for applications that want to support multicasting, and that do not require the quality of service provided by session acknowledge. For more information on multicasting, see Using Multicasting. Note: You should avoid using this mode if your application cannot handle lost or duplicate messages. Duplicate messages may be sent if an initial attempt to deliver a message fails.

Transacted Session

In a transacted session, only one transaction is active at any given time. Any messages sent or received during a transaction are treated as an atomic unit.

When you create a transacted session, the acknowledge mode is ignored. When an application commits a transaction, all the messages that the application received during the transaction are acknowledged by the messaging system and messages it sent are accepted for delivery. If an application rolls back a transaction, the messages that the application received during the transaction are not acknowledged and messages it sent are discarded.

JMS can participate in distributed transactions with other Java services, such as EJB, that use the Java Transaction API (JTA). Transacted sessions do not support this capability as the transaction is restricted to accessing the messages associated with that session. For more information about using JMS with JTA, see Using JTA User Transactions.

Destination

A Destination object can be either a queue or topic, encapsulating the address syntax for a specific provider. The JMS specification does not define a standard address syntax due to the variations in syntax between providers.

Similar to a connection factory, an administrator defines and configures the destination and the WebLogic Server adds it to the JNDI space during startup. Applications can also create temporary destinations that exist only for the duration of the JMS connection in which they are created.

On the client side, Queue and Topic objects are handles to the object on the server. Their methods only return their names. To access them for messaging, you create message producers and consumers that attach to them.

A destination supports concurrent use, enabling multiple threads to access the object simultaneously.

JMS Queues and Topics extend javax.jms.Destination. The following table describes the Destination subclasses.

Table 2-6 Destination Subclasses

Subclass. . . | In Messaging Model. . . | Manages Messages for. . .
--- | --- | ---
Queue | PTP | JMS PTP provider.
TemporaryQueue | PTP | JMS PTP provider, and exists for the duration of the JMS connection in which the messages are created. A temporary queue can be consumed only by the queue connection that created it.
Topic | Pub/sub | JMS Pub/sub provider.
TemporaryTopic | Pub/sub | JMS PTP provider, and exists for the duration of the JMS connection in which the messages are created. A temporary topic can be consumed only by the topic connection that created it.

Note: An application has the option of browsing queues by creating a QueueBrowser object in its queue session. This object produces a snapshot of the messages in the queue at the time the queue browser is created. The application can view the messages in the queue, but the messages are not considered read and are not removed from the queue. For more information about browsing queues, see Browsing Header and Property Fields.

To learn how to use the Destination class within an application, see Developing a WebLogic JMS Application, or the javax.jms.Destination Javadoc.

MessageProducer and MessageConsumer

A MessageProducer object sends messages to a queue or topic. A MessageConsumer object receives messages from a queue or topic. Message producers and consumers operate independently of one another. Message producers generate and send messages regardless of whether a message consumer has been created and is waiting for a message, and vice versa.

A Session creates the MessageProducers and MessageConsumers that are attached to queues and topics.

The message sender and receiver objects are created as subclasses of the MessageProducer and MessageConsumer classes. The following table describes the MessageProducer and MessageConsumer subclasses.

Table 2-7 MessageProducer and MessageConsumer Subclasses

Subclass. . . | In Messaging Model. . . | Performs the Following Function. . .
--- | --- | ---
QueueSender | PTP | Sends messages for a JMS PTP provider.
QueueReceiver | PTP | Receives messages for a JMS PTP provider, and exists until the JMS connection in which the messages are created is closed.
TopicPublisher | Pub/sub | Sends messages for a JMS Pub/sub provider.
TopicSubscriber | Pub/sub | Receives messages for a JMS Pub/sub provider, and exists for the duration of the JMS connection in which the messages are created. Message destinations must be bound explicitly using the appropriate JNDI interface.

The PTP model, as shown in the figure Point-to-Point (PTP) Messaging, allows multiple sessions to receive messages from the same queue. However, a message can only be delivered to one queue receiver. When there are multiple queue receivers, WebLogic JMS defines the next queue receiver that will receive a message on a first-come, first-serve basis.

The Pub/sub model, as shown in the figure Publish/Subscribe (Pub/Sub) Messaging, allows messages to be delivered to multiple topic subscribers. Topic subscribers can be durable or non-durable, as described in Setting Up Durable Subscriptions.

An application can use the same JMS connection to both publish and subscribe to a single topic. Because topic messages are delivered to all subscribers, an application can receive messages it has published itself. To prevent clients from receiving messages that they publish, a JMS application can set a noLocal attribute on the topic subscriber, as described in Step 5: Create Message Producers and Message Consumers Using the Session and Destinations.

To learn how to use the MessageProducer and MessageConsumer classes within an application, see Setting Up a JMS Application, or the javax.jms.MessageProducer and javax.jms.MessageConsumer javadocs.

Message

A Message object encapsulates the information exchanged by applications. This information includes three components: a set of standard header fields, a set of application-specific properties, and a message body. The following sections describe these components.

Message Header Fields

Every JMS message contains a standard set of header fields that is included by default and available to message consumers. Some fields can be set by the message producers.

For information about setting message header fields, see Setting and Browsing Message Header and Property Fields, or to the javax.jms.Message Javadoc.

The following table describes the fields in the message headers and shows how values are defined for each field.

Table 2-8 Message Header Fields

Field | Description | Defined by
--- | --- | ---
JMSCorrelationID | Specifies one of the following: a WebLogic JMSMessageID (described later in this table), an application-specific string, or a byte[] array. The JMSCorrelationID is used to correlate messages. There are two common applications for this field. The first application is to link messages by setting up a request/response scheme, as follows: When an application sends a message, it stores the JMSMessageID value assigned to it. When an application receives the message, it copies the JMSMessageID into the JMSCorrelationID field of a response message that it sends back to the sending application. The second application is to use the JMSCorrelationID field to carry any String you choose, enabling a series of messages to be linked with some application-determined value. All JMSMessageIDs start with an ID: prefix. If you use the JMSCorrelationID for some other application-specific string, it must not begin with the ID: prefix. | Application
JMSDeliveryMode | Specifies PERSISTENT or NON_PERSISTENT messaging. When a persistent message is sent, WebLogic JMS stores it in the JMS file or JDBC database. The send() operation is not considered successful until delivery of the message can be guaranteed. A persistent message is guaranteed to be delivered at least once. WebLogic JMS does not store non-persistent messages in the JMS database. This mode of operation provides the lowest overhead. They are guaranteed to be delivered at least once unless there is a system failure, in which case messages may be lost. If a connection is closed or recovered, all non-persistent messages that have not yet been acknowledged will be redelivered. Once a non-persistent message is acknowledged, it will not be redelivered. When a message is sent, this value is ignored. When the message is received, it contains the delivery mode specified by the sending method. | send() method
JMSDeliveryTime | Defines the earliest absolute time at which a message can be delivered to a consumer. This field can be used to sort messages in a destination and to select messages. For purposes of data type conversion, the JMSDeliveryTime is a long integer. | send() method
JMSDestination | Specifies the destination (queue or topic) to which the message is to be delivered. The application's message producer sets the value of this field when the message is sent. When a message is sent, this value is ignored. When a message is received, its destination value must be equivalent to the value assigned when it was sent. | send() method
JMSExpiration | Specifies the expiration, or time-to-live value, for a message. WebLogic JMS calculates the JMSExpiration value as the sum of the application's time-to-live and the current GMT. If the application specifies time-to-live as 0, JMSExpiration is set to 0, which means the message never expires. WebLogic JMS removes expired messages from the system to prevent their delivery. | send() method
JMSMessageID | Contains a string value that uniquely identifies each message sent by a JMS Provider. All JMSMessageIDs start with an ID: prefix. When a message is sent, this value is ignored. When the message is received, it contains a provider-assigned value. | send() method
JMSPriority | Specifies the priority level. This field is set before a message is sent. JMS defines ten priority levels, 0 to 9, 0 being the lowest priority. Levels 0-4 indicate gradations of normal priority, and level 5-9 indicate gradations of expedited priority. When the message is received, it contains the value specified by the method sending the message. You can sort destinations by priority by configuring a destination key, as described in Managing JMS in the Administration Guide. | send() method
JMSRedelivered | Specifies a flag set when a message is redelivered because no acknowledge was received. This flag is of interest to a receiving application only. If set, the flag indicates that JMS may have delivered the message previously because one of the following is true: The application has already received the message, but did not acknowledge it. The session's recover() method was called to restart the session beginning after the last acknowledged message. For more information about the recover() method, see Recovering Received Messages. | WebLogic JMS
JMSReplyTo | Specifies a queue or topic to which reply messages should be sent. This field is set by the sending application before the message is sent. This feature can be used with the JMSCorrelationID header field to coordinate request/response messages. Simply setting the JMSReplyTo field does not guarantee a response; it enables the receiving application to respond, if it so chooses. You may set the JMSReplyTo to null, which may have a semantic meaning to the receiving application, such as a notification event. | Application
JMSTimestamp | Contains the time at which the message was sent. WebLogic JMS writes the timestamp in the message when it accepts the message for delivery, not when the application sends the message. When the message is received, it contains the timestamp. The value stored in the field is a Java millis time value. | WebLogic JMS
JMSType | Specifies the message type identifier (String) set by the sending application. The JMS specification allows some flexibility with this field in order to accommodate diverse JMS providers. Some messaging systems allow application-specific message types to be used. For such systems, the JMSType field could be used to hold a message type ID that provides access to the stored type definitions. WebLogic JMS does not restrict the use of this field. | Application

Message Property Fields

The property fields of a message contain header fields added by the sending application. The properties are standard Java name/value pairs. Property names must conform to the message selector syntax specifications defined in the javax.jms.Message Javadoc. The following values are valid: boolean, byte, double, float, int, long, short, and String.

Although message property fields may be used for application-specific purposes, JMS provides them primarily for use in message selectors. For more information about message selectors, see Filtering Messages.

For information about setting message property fields, see Setting and Browsing Message Header and Property Fields, or to the javax.jms.Message Javadoc.

Message Body

A message body contains the content being delivered from producer to consumer.

The following table describes the types of messages defined by JMS. All message types extend javax.jms.Message, which consists of message headers and properties, but no message body.

Table 2-9 JMS Message Types

Type | Description
--- | ---
javax.jms.BytesMessage | Stream of uninterpreted bytes, which must be understood by the sender and receiver. The access methods for this message type are stream-oriented readers and writers based on java.io.DataInputStream and java.io.DataOutputStream.
javax.jms.MapMessage | Set of name/value pairs in which the names are strings and the values are Java primitive types. Pairs can be read sequentially or randomly, by specifying a name.
javax.jms.ObjectMessage | Single serializable Java object.
javax.jms.StreamMessage | Similar to a BytesMessage, except that only Java primitive types are written to or read from the stream.
javax.jms.TextMessage | Single String. The TextMessage can also contain XML content.
weblogic.jms.extensions.XMLMessage | XML content. Use of the XMLMessage type facilitates message filtering, which is more complex when performed on XML content shipped in a TextMessage.

For more information, see the javax.jms.Message Javadoc. For more information about the access methods and, if applicable, the conversion charts associated with a particular message type, see the Javadoc for that message type.

ServerSessionPoolFactory

A server session pool is a WebLogic-specific JMS feature that enables you to process messages concurrently. A server session pool factory is used to create a server-side ServerSessionPool.

WebLogic JMS defines one ServerSessionPoolFactory object, by default: weblogic.jms.ServerSessionPoolFactory:<name>, where <name> specifies the name of the JMS server to which the session pool is created. The WebLogic Server adds the default server session pool factory to the JNDI space during startup and the application subsequently retrieves the server session pool factory using WebLogic JNDI.

To learn how to use the server session pool factory within an application, see Defining Server Session Pools, or the weblogic.jms.ServerSessionPoolFactory Javadoc.

ServerSessionPool

A ServerSessionPool application server object provides a pool of server sessions that connection consumers can retrieve in order to process messages concurrently.

A ServerSessionPool is created by the ServerSessionPoolFactory object obtained through a JNDI lookup.

To learn how to use the server session pool within an application, see Defining Server Session Pools, or the javax.jms.ServerSessionPool Javadoc.

ServerSession

A ServerSession application server object enables you to associate a thread with a JMS session by providing a context for creating, sending, and receiving messages.

A ServerSession is created by a ServerSessionPool object.

To learn how to use the server session within an application, see Defining Server Session Pools, or the javax.jms.ServerSession Javadoc.

ConnectionConsumer

A ConnectionConsumer object uses a server session to process received messages. If message traffic is heavy, the connection consumer can load each server session with multiple messages to minimize thread context switching.

A ConnectionConsumer is created by a Connection object.

To learn how to use the connection consumers within an application, see Defining Server Session Pools, or the javax.jms.ConnectionConsumer Javadoc.

Note: Connection consumer listeners run on the same JVM as the server.

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.