1 Understanding WebLogic JMS

Learn about the different Java Message Service (JMS) concepts and features, and understand how they work with other application objects and WebLogic Server.

It is assumed that you are familiar with Java programming and JMS 1.1 and JMS 2.0 concepts and features.

• Overview of the Java Message Service and WebLogic JMS

• Understanding the Messaging Models

• Value-Added Public JMS API Extensions

• Understanding the JMS API

Overview of the Java Message Service and WebLogic JMS

WebLogic JMS is an enterprise-class messaging system that is tightly integrated into the WebLogic Server platform.

WebLogic JMS fully supports the JMS Specification, described at http://www.oracle.com/technetwork/java/jms/index.html, 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 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 nation 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

Figure 1-1 illustrates WebLogic JMS messaging.

Figure 1-1 WebLogic JMS Messaging

Description of "Figure 1-1 WebLogic JMS Messaging"

As shown 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.

• WebLogic Server is compliant with the Java Platform, Enterprise Edition (Java EE) Version 7.0 specification, described at http://docs.oracle.com/javaee/7/api/.

• WebLogic Server is fully compliant with the JMS 2.0 and JMS 1.1 specifications, at http://www.oracle.com/technetwork/java/jms/index.html, and can be used in production.

WebLogic JMS Architecture

Figure 1-2 illustrates the WebLogic JMS architecture.

Figure 1-2 WebLogic JMS Architecture

Description of "Figure 1-2 WebLogic JMS Architecture"

The major components of the WebLogic JMS Server architecture include:

• JMS server: a managed message container for a set of JMS queues and topics. Destination configuration is located in JMS XML modules that can target one or more JMS servers, and a single logical destination can be distributed across multiple JMS servers. A JMS server's primary responsibility for its targeted destinations is to maintain information on what persistent store is used for any persistent messages that arrive on the destinations, and to maintain the states of durable subscribers created on the destinations. You can configure one or more JMS servers per domain, multiple JMS servers may run on the same WebLogic server, and a JMS server can manage one or more JMS modules.
• JMS connection hosts and connection factories: any WebLogic server in a cluster can act as a JMS connection host for JMS applications. A JMS application gains access to WebLogic JMS by (a) obtaining a connection factory reference from JNDI, (b) obtaining a connection from this factory, and finally (c) using the connection to send or receive messages. JMS messages flow from an application, through its connection host, and then to any destination on a JMS server that is in the same cluster as the connection host. An application can use either default connection factories or custom connection factories that are configured using a JMS module.
• JMS destinations: hold JMS messages and are hosted on JMS servers. WebLogic JMS applications typically obtain JMS destination references via JNDI and then send and receive messages to these destinations using their respective JMS connections. A single logical WebLogic destination can be configured to be distributed across multiple JMS servers within the same cluster. A WebLogic JMS client can transparently communicate with any WebLogic JMS destination that is hosted in the same cluster as the client's connection host.
• JMS modules: contain configuration resources, such as standalone queue and topic destinations, distributed destinations, and connection factories, and are defined by XML documents that conform to the http://xmlns.oracle.com/weblogic/weblogic-jms/1.4/weblogic-jms.xsd schema.
• Client JMS applications: either produce messages to destinations or consume messages from destinations.
• JNDI (Java Naming and Directory Interface): provides a lookup facility for JMS connection factories and destinations.
• WebLogic persistent storage: a server instance's default store, a user-defined file store, or a user-defined JDBC-accessible store for storing persistent message data.

Understanding the Messaging Models

JMS supports two messaging models: point-to-point (PTP) and publish/subscribe.

The messaging models are similar, except for the following differences:

• The PTP messaging model enables the delivery of a message to exact one recipient.

• The publish/subscribe 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 (described at http://docs.oracle.com/javaee/7/api/javax/jms/Queue.html) and the publish/subscibe class javax.jms.Topic (described at http://docs.oracle.com/javaee/7/api/javax/jms/Topic.html) both extend the class javax.jms.Destination (described at http://docs.oracle.com/javaee/7/api/javax/jms/Destination.html).

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.

Figure 1-3 illustrates PTP messaging.

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

Description of "Figure 1-3 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, then 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, then messages remain in the queue until a queue receiver attaches to the queue.

Publish/Subscribe Messaging

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

Figure 1-4 illustrates publish/subscribe messaging.

Figure 1-4 Publish/Subscribe Messaging

Description of "Figure 1-4 Publish/Subscribe Messaging"

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

The publish/subscribe messaging model supports durable subscribers, enabling 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

The "Message Delivery Mode" section of the JMS Specification, described at http://www.oracle.com/technetwork/java/jms/index.html, messages can be specified as persistent or non persistent:

• A persistent message is guaranteed to be delivered once. The message cannot be lost due to a JMS provider failure, and it must not 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 WebLogic persistent store (disk-base file or JDBC-accessible database) that is optionally targeted by each JMS server during configuration.

• Non persistent messages are not stored. They are guaranteed to be delivered once-at-most-after, unless there is a JMS provider failure, in which case messages may be lost, and must not be delivered twice. If a connection is closed or recovered, then 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.

For information about using the system-wide, WebLogic Persistent Store, see Administering the WebLogic Persistent Store.

Value-Added Public JMS API Extensions

WebLogic JMS is tightly integrated into the WebLogic Server platform, enabling you to build highly secure Java EE 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.

For a detailed listing of these value-added features, see WebLogic Server Value-Added JMS Features in Administering JMS Resources for Oracle WebLogic Server.

WebLogic Server Value-Added JMS Features

In addition to the standard JMS APIs specified by the JMS Specification, WebLogic Server provides numerous weblogic.jms.extensions APIs, which includes the classes and methods described in the Table 1-1.For more information about these APIs, see Java API Reference for Oracle WebLogic Server.

Table 1-1 WebLogic JMS Public API Extensions

Interface/Class	Function
ConsumerInfo, DestinationInfo	Provides consumer and destination information to management clients in CompositeData format.
JMSMessageFactoryImpl, WLMessageFactory	Provides a factory and methods to: Create JMS messages Create JMS bytes messages Create JMS map messages Create JMS object messages CreateJMS stream messages Create JMS text messages Create JMS XML messages
JMSMessageInfo	Provides browsing and message manipulation using JMX
JMSModuleHelper, JMSNamedEntityModifier	Monitors JMS runtime MBeans and manages JMS Module configuration entities in a JMS module
JMSRuntimeHelper	Monitors JMS runtime JMX MBeans
MDBTransaction	Associates a message delivered to a MDB (message-driven bean) with a transaction
WLDestination	Determines if a destination is a queue or a topic
WLMessage	Sets a delivery time for messages, redelivery limits, and send timeouts
Java API Reference for Oracle WebLogic ServerWLMessageProducer	Sets a message delivery times for producers and Unit-of-Order names
WLJMSContext	Provides additional fields and methods that are not supported by javax.jms.JMSContext. WLJMSContext provides the same extension features as WLConnection and WLSession
WLJMSProducer	Provides additional methods that are not supported by javax.jms.JMSProducer.
WLQueueSession, WLSession, WLTopicSession	Provides additional fields and methods that are not supported by javax.jms.QueueSession, javax.jms.Session, and javax.jms.TopicSession
XMLMessage	Creates XML messages
Schedule	Sets a scheduled delivery times for messages
JMSHelper	Monitors JMS runtime MBeans. Deprecated in this release of WebLogic Server. Replaced by JMSModuleHelper.
ServerSessionPoolFactory, ServerSessionPoolListener	Provides interfaces for creating server session pools and message listeners Note: Session pool configuration objects are deprecated. They are not a required part of the Java EE specification, do not support JTA user transactions, and are largely superseded by message-driven beans (MDBs), which are a required part of Java EE. For more information on designing MDBs, see Developing Message-Driven Beans for Oracle WebLogic Server.

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.

Understanding the JMS API

The javax.jms API enables you to create the class objects necessary to connect to the JMS, and to send and receive messages.

To create a JMS application, use the javax.jms API at http://docs.oracle.com/javaee/7/api/javax/jms/package-summary.html. JMS class interfaces are created as subclasses to provide queue specific and topic specific versions of the common parent classes.

The Table 1-2 lists the JMS classes described in more detail in subsequent sections. For a complete description of all JMS classes, see javax.jms, at http://docs.oracle.com/javaee/7/api/javax/jms/package-summary.html, or in the weblogic.jms.extensions Javadoc.

Table 1-2 WebLogic 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.
JMSContext	Encapsulates the functionality of two objects, Connection and Session, in a single object.
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 publish/subscribe 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.
Messages	Encapsulates information to be sent or received.
ServerSessionPoolFactoryFoot 1	Encapsulates configuration information for a server-managed pool of message consumers. The server session pool factory is used to create server session pools.
ServerSessionPoolFoot 2	Provides a pool of server sessions that can be used to process messages concurrently for connection consumers.
ServerSessionFoot 3	Associates a thread with a JMS session.
ConnectionConsumerFoot 4	Specifies a consumer that retrieves server sessions to process messages concurrently.

^Footnote 1

Supports an optional JMS interface for processing multiple messages concurrently.

^Footnote 2

Supports an optional JMS interface for processing multiple messages concurrently.

^Footnote 3

Supports an optional JMS interface for processing multiple messages concurrently.

^Footnote 4

Supports an optional JMS interface for processing multiple messages concurrently.

For information about configuring JMS resources, see Configuring Basic JMS System Resources in Administering JMS Resources for Oracle WebLogic Server. The procedure for setting up a JMS application is presented in Setting Up a JMS Application.

ConnectionFactory

ConnectionFactory encapsulates connection configuration information, and enables JMS applications to create a Connection (see Connection). A connection factory supports concurrent use, enabling multiple threads to access the object simultaneously. You can use the pre configured default connection factories provided by WebLogic JMS, or you can configure one or more connection factories to create connections with predefined attributes that suit your application.

Using the Default Connection Factories

WebLogic Server supports the default connection factory as defined by the Java EE 7 specification. See Using the Default JMS Connection Factory Defined by Java EE 7 in Administering JMS Resources for Oracle WebLogic Server.

WebLogic JMS defines two default connection factories, which you can look up using the following JNDI names:

• weblogic.jms.ConnectionFactory

• weblogic.jms.XAConnectionFactory

You only need to create a user-defined a connection factory if the settings of the default factories are not suitable for your application. The main difference between the preconfigured settings for the default connection factories is the default value for the "XA Connection Factory Enabled" attribute which is used to enable JTA transactions, as shown in the following table.

Table 1-3 XA Transaction Settings for Default Connection Factories

Default Connection Factory	XA Connection Factory Enabled setting is
weblogic.jms.ConnectionFactory	False
weblogic.jms.XAConnectionFactory	True

An XA factory is required for JMS applications to use JTA user transactions, but is not required for transacted sessions. For more information about using transactions with WebLogic JMS, see Using Transactions with WebLogic JMS.

All other default factory configuration attributes are set to the same default values as a user-defined connection factory.

For more information about the XA Connection Factory Enabled attribute, and to see the default values for the other connection factory attributes, see JMS Connection Factory: Configuration: Transactions in the Oracle WebLogic Server Administration Console Online Help.

Another distinction when using the default connection factories is that you have no control over targeting the WebLogic Server instances where the connection factory may be deployed. However, you can disable the default connection factories on a per-server basis.

For more information about enabling or disabling the default connection factories, see Servers: Configuration: Services in the Oracle WebLogic Server Administration Console Online Help.

To deploy a connection factory on specific independent servers, on specific servers within a cluster, or on an entire cluster, you must configure a new connection factory and specify the appropriate target, as explained in Connection Factory Configuration in Administering JMS Resources for Oracle WebLogic Server.

Note:

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

Configuring and Deploying Connection Factories

A system administrator can define and configure one or more connection factories to create connections with predefined attributes and WebLogic Server will add them to the JNDI space during startup. The application then retrieves a connection factory using WebLogic JNDI. Any user-defined connection factories must be uniquely named.

For information about configuring connection factories, see Configure connection factories in the Oracle WebLogic Server Administration Console Online Help.

A system administrator establishes cluster-wide, transparent access to JMS destinations from any server in the cluster by targeting to the cluster or by targeting to one or more server instances in the cluster. This way, each connection factory can be deployed on multiple WebLogic Server instances. For more information about JMS clustering, refer to Configuring Advanced WebLogic JMS Resources in Administering JMS Resources for Oracle WebLogic Server.

The ConnectionFactory Class

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.

Note:

For this release, you can use the JMS version 1.1 specification connection factories or you can choose to use the subclasses.

Table 1-4 describes the ConnectionFactory subclasses.

Table 1-4 ConnectionFactory Subclasses

Subclass	In Messaging Model	Is Used to Create
QueueConnectionFactory	PTP	QueueConnection to a JMS PTP provider.
TopicConnectionFactory	Publish/Subscibe	TopicConnection to a JMS Publish/Subscibe provider.

To learn how to use the ConnectionFactory class within an application, see Developing a Basic JMS Application, or the javax.jms.ConnectionFactory Javadoc at http://docs.oracle.com/javaee/7/api/javax/jms/ConnectionFactory.html.

JMSContext

JMSContext is the main interface introduced in the simplified API for JMS 2.0. For more information about this interface, see New Interfaces in the Simplified JMS API.

Connection

A Connection represents an open communication channel between an application and the messaging system, and is used to create a Session (see 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 ConnectionFactory (see 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 can 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.

Note:

For this release, you can use the JMS Version 1.1 specification connection objects or you can choose to use the subclasses.

Table 1-5 describes the Connection subclasses.

Table 1-5 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 publish/subscribe provider created by TopicConnectionFactory.

To learn how to use the Connection class within an application, see Developing a Basic JMS Application, or the javax.jms.Connection Javadoc at http://docs.oracle.com/javaee/7/api/javax/jms/Connection.html.

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 you want an application to have a separate thread for producing and consuming messages, then the application should create a separate session for each function.

A Session is created by Connection (see Connection).

WebLogic JMS Session Guidelines

The JMS 1.1 Specification, at http://www.oracle.com/technetwork/java/jms/index.html, allows for a generic session to have a MessageConsumer for any type of Destination object. However, WebLogic JMS does not support having both types of MessageConsumer (QueueConsumer and TopicSubscriber) for a single session. In addition, having multiple consumers for a single session is not a common practice. The following commonly used scenarios are supported:

• Using a single session with both a QueueSender and a TopicSubscriber or: QueueConsumer and TopicPublisher.

• Multiple MessageProducers of any type.

  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.

Session Subclasses

Table 1-6 describes the Session subclasses.

Table 1-6 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 publish/subscribe provider. Created by TopicConnection.

To learn how to use the Session class within an application, see Developing a Basic JMS Application, or the javax.jms.Session at http://docs.oracle.com/javaee/7/api/javax/jms/Session.html, and the weblogic.jms.extensions.WLSession Javadoc.

Non-Transacted Sessions

In a non-transacted session, the application creating the session selects one of the five acknowledge modes defined in Table 1-7.

Table 1-7 Acknowledge Modes Used for Non-Transacted Sessions

Acknowledge Mode	Description
AUTO_ACKNOWLEDGE	The Session object acknowledges receipt of a message after 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. After 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 WebLogic Server 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 Factory: Configuration: General in the Oracle WebLogic Server Administration Console Online Help.
DUPS_OK_ACKNOWLEDGE	The Session object acknowledges receipt of a message after 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 acknowledgement 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 with WebLogic JMS. Note: Use only with topics. 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 Sessions

In a transacted session, only one transaction is active at any time. Any number of 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, then 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 because 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 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.

Note:

Administrators can also configure a distributed destination, which is a single set of destinations (queues or topics) that are accessible as a single, logical destination to a client. For more information, see Distributed Destinations.

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 Queue and Topic objects extend javax.jms.Destination method described at http://docs.oracle.com/javaee/7/api/javax/jms/Destination.html.

Note:

For this release, you can use the JMS version 1.1 specification destination objects or you can choose to use the subclasses.

Table 1-8 describes the Destination subclasses.

Table 1-8 Destination Subclasses

Subclass	Messaging Model	Manages Messages for
Queue	PTP	JMS point-to-point provider.
TemporaryQueue	PTP	JMS point-to-point 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 publish/subscribe provider
TemporaryTopic	Pub/sub	JMS publish/subscribe 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 Setting and Browsing Message Header and Property Fields.

To learn how to use the Destination class within an application, see Developing a Basic JMS Application, or the javax.jms.Destination Javadoc at http://docs.oracle.com/javaee/7/api/javax/jms/Destination.html.

Distributed Destinations

A distributed destination resource is a single set of destinations (queues or topics) that are accessible as a single, logical destination to a client (for example, a distributed topic has its own JNDI name). The members of the set are typically distributed across multiple servers within a cluster, with each member belonging to a separate JMS server. Applications that use a distributed destination are more highly available than applications that use standalone destinations because WebLogic JMS provides load balancing and failover for the members of a distributed destination in a cluster.

• For more information about using a distributed destination with your applications, see Using Distributed Destinations.

• For instructions about configuring a distributed queue destination, see Configure uniform distributed queues in the Oracle WebLogic Server Administration Console Online Help.

• For instructions about configuring a distributed topic destination, see Configure uniform distributed topics in the Oracle WebLogic Server Administration Console Online Help.

MessageProducer and MessageConsumer

A MessageProducer sends messages to a queue or topic. A MessageConsumer 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 (see 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.

Note:

For this release, you can use the JMS version 1.1 specification message producer and consumer objects or you can use the subclasses.

Table 1-9 describes the MessageProducer and MessageConsumer subclasses.

Table 1-9 MessageProducer and MessageConsumer Subclasses

Subclass	In Messaging Model	Performs this Function
QueueSender	PTP	Sends messages for a JMS point-to-point provider.
QueueReceiver	PTP	Receives messages for a JMS point-to-point provider
TopicPublisher	Publish/subscibe	Sends messages for a JMS Publish/subscibe provider
TopicSubscriber	Publish/subscibe	Receives messages for a JMS Publish/subscibe provider

The PTP model, as shown in the figure Figure 1-3, 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 Publish/subscibe model, as shown in the figure Figure 1-4, 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 topic. Because topic messages can be 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.

To learn how to use the MessageProducer and MessageConsumer classes within an application, see Setting Up a JMS Application, or the javax.jms.MessageProducer (at http://docs.oracle.com/javaee/7/api/javax/jms/MessageProducer.html), and javax.jms.MessageConsumer (at http://docs.oracle.com/javaee/7/api/javax/jms/MessageConsumer.html) Javadoc.

Messages

A Message encapsulates the information exchanged by applications. This information includes three components:

• Message Header Fields

• Message Property Fields

• Message Body

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 at http://docs.oracle.com/javaee/7/api/javax/jms/Message.html.

Table 1-10 describes the fields in the message headers and shows how values are defined for each field.

Table 1-10 Message Header Fields

Field	Description	Defined by
JMSCorrelationID	Specifies one of the following: a WebLogic JMSMessageID (field described later in this table), an application-specific string, or a byte[] array. The JMSCorrelationID field is used to correlate messages and is set directly on the message by the application before send(). 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.	Application
JMSDeliveryMode	Specifies PERSISTENT or NON_PERSISTENT messaging. This field is set on the producer or as parameter sent by the application before send(). When a persistent message is sent, it is stored in the WebLogic Persistent Store. 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 persistent store. 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. After a non persistent message is acknowledged, it will not be redelivered. This value is overwritten by a call to theproducer.send(), setting this value directly on the message has no effect. The values set by the producer can be queried using the message supplied to producer.send() or when the message is received by a consumer.	send() method
JMSDeliveryTime	Defines the earliest absolute time at which a message can be delivered to a consumer. This field is set by the application before send() and depends on timeToDeliver, which is set on the producer. 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. This field is set when creating producer or as parameter sent by the application before send(). This value is overwritten by a call to producer.send(), setting this value directly on the message has no effect. The values set by the producer can be queried using the message supplied to producer.send() or when the message is received by a consumer. 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. This field is set by the application before send(). Depends on timeToLive, which is set on the producer or as a parameter sent by the application to send(). 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, then the JMSExpiration value 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. This field is set internally by send(). All JMSMessageIDs start with an ID: prefix. This value is overwritten by a call to producer.send(), setting this value directly on the message has no effect. The values set by the producer can be queried using the message supplied to producer.send() or when the message is received by a consumer. When the message is received, it contains a provider-assigned value.	send() method
JMSPriority	Specifies the priority level. This field is set on the producer or as parameter sent by the application before send(). 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 Configure destination keys in the Oracle WebLogic Server Administration Console Online Help.	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. 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 directly on the message by the application before send(). This feature can be used with the JMSCorrelationID header field to coordinate request/response messages. Setting the JMSReplyTo field does not guarantee a response; it simply enables the receiving application to respond.	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 directly on the message by the application before send(). The JMS specification allows some flexibility with this field 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 at http://docs.oracle.com/javaee/7/api/javax/jms/Message.html. The following values are valid: boolean, byte, double, float, int, long, short, and String.

WebLogic Server supports the use of the following JMS (JMSX) defined properties as defined in the JMS 1.1. Specification, at http://www.oracle.com/technetwork/java/jms/index.html:

Table 1-11 JMSX Property

Type	Description
JMSXUserID	System generated property that identifies the user sending the message. See Using the JMSXUserID Property.
JMSXDeliveryCount	System generated property that specifies the number of message delivery attempts where first attempt is 1
JMSXGroupID	Identity of the message group
JMSXGroupSeq	Sequence number of a message within a group

Although message property fields may be used for application-specific purposes, JMS provides them primarily for use in message selectors. You determine how the JMS properties are used in your environment. You can include them in some messages and omit them from others depending upon your processing criteria. For more information, see:

• Setting and Browsing Message Header and Property Fields

• Filtering Messages

• JMS 1.1. Specification, described at http://www.oracle.com/technetwork/java/jms/index.html

Message Body

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

Table 1-12 describes the types of messages defined by JMS. All message types extend javax.jms.Message, at http://docs.oracle.com/javaee/7/api/javax/jms/Message.html, which consists of message headers and properties, but no message body.

Table 1-12 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. See http://docs.oracle.com/javaee/7/api/javax/jms/BytesMessage.html.
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. See http://docs.oracle.com/javaee/7/api/javax/jms/ObjectMessage.html.
javax.jms.StreamMessage	Similar to a BytesMessage, except that only Java primitive types are written to or read from the stream. See http://docs.oracle.com/javaee/7/api/javax/jms/StreamMessage.html.
javax.jms.TextMessage	Single String. The TextMessage can also contain XML content. See http://docs.oracle.com/javaee/7/api/javax/jms/TextMessage.html.
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 at http://docs.oracle.com/javaee/7/api/javax/jms/Message.html. 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

Note:

Session pool and connection consumer configuration objects are deprecated. They are not a required part of the Java EE specification, do not support JTA user transactions, and are largely superseded by message driven beans (MDBs), which are simpler, easier to manage, and more capable. For more information about designing MDBs, see Message-Driven EJBs in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.

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.extensions.ServerSessionPoolFactory:<name>, the <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.extnesions.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 (see ServerSessionPoolFactory) obtained through a JNDI lookup.

To learn how to use the server session pool within an application, see Defining Server Session Poolsor the javax.jms.ServerSessionPool application Javadoc at http://docs.oracle.com/javaee/7/api/javax/jms/ServerSessionPool.html.

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 application is created by a ServerSessionPool object, described in ServerSessionPool.

To learn how to use the server session within an application, see Defining Server Session Pools or the javax.jms.ServerSession Javadoc at http://docs.oracle.com/javaee/7/api/javax/jms/ServerSession.html.

ConnectionConsumer

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

To learn how to use the connection consumers within an application, see Defining Server Session Pools, or the javax.jms.ConnectionConsumer Javadoc at http://docs.oracle.com/javaee/7/api/javax/jms/ConnectionConsumer.html.

Note:

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