The JMS API Programming Model

All JMS clients , both JMS senders and receivers, use the following basic steps to access a JMS server:

1. Look up a JMS ConnectionFactory in JNDI.

2. Use the ConnectionFactory to create a JMS Connection.

3. Use the Connection to create one or more Sessions.

4. Look up one or more Destinations (Queue or Topic ) in JNDI.

5. Use the Sessions and Destinations to create the MessageProducers and MessageConsumers.

6. Instruct the Connection to start the delivery of messages.

Figure 15.5 illustrates the preceding steps in the context of a JMS client.

Figure 15.5. The JMS API programming model.

The following section will describe each of these components in detail.

ConnectionFactory

A JMS Connection Factory is an abstraction that hides provider-specific connection configuration information from clients and enables JMS applications to create a Connection. Typically, it is the responsibility of the WebLogic Administrator to define and configure one or more uniquely named connection factories via the WebLogic Administration Console. Upon startup WebLogic Server binds the connection factories to the WebLogic JNDI namespace, which enables JMS clients the capability to look up a connection factory.

Note

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

WebLogic JMS defines one default connection factory that can be looked up using the JNDI name , weblogic.jms.ConnectionFactory . You only need to define a connection factory if this default provided by WebLogic JMS is not suitable for your application.

Caution

With WebLogic Server, you have no control over the JMS server on which the default connection factory may be deployed. However, you can create a new connection factory and specify the appropriate JMS server target(s).

The ConnectionFactory class does not itself define any messaging methods. For this reason its subclasses define methods for the respective messaging models (PTP and Pub/Sub) as follows :

• QueueConnectionFactory for PTP

• TopicConnectionFactory for Pub/Sub

Connections

A connection object encapsulates a virtual connection between an application and the JMS provider, and is used to create a Session for producing and consuming messages. Like connection factories, connections come in two formsthe QueueConnection (PTP) or the TopicConnection (Pub/Sub) interface. For example, after you have a QueueConnectionFactory or TopicConnectionFactory object, you can use it to create a connection.

Tip

Due to the resource overhead associated with establishing a connection (authenticating users and setting up communications), most applications establish a single connection for all their messaging requirements.

Sessions

Clients use a Session to send or receive messages. Sessions are single-threaded. The Session interfaces ( QueueSession and TopicSession ) provide methods to create MessageProducers and MessageConsumers. Sessions order the messages sent to them and also persist messages until they are delivered. In a non-transacted session, the application creating the session can select one of the following acknowledgement modes for its messages:

• Session.AUTO_ACKNOWLEDGE The acknowledgement is sent by the session after the consumer has finished processing the message.

• Session.CLIENT_ACKNOWLEDGE The acknowledgement has to be sent programmatically by the consumer of the message.

• Session.DUPS_OK_ACKNOWLEDGE The acknowledgement is sent by the session after the consumer has finished processing the message. This acknowledgement allows duplicate messages to be sent in case an acknowledgement is lost or if an initial attempt to deliver a message fails.

• Session.NO_ACKNOWLEDGE A message is removed from the destination after it is consumed. The session does not send any acknowledgements. This mode is supported for applications that do not want to incur the associated overhead of session acknowledgement.

• Session.MULTICAST_NO_ACKNOWLEDGE Messages sent to a MULTICAST_NO_ACKNOWLEDGE session share the same characteristics as NO_ACKNOWLEDGE mode.

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 and the acknowledgement mode is ignored. However, when a transaction commits, all the messages that the application received during the transaction are acknowledged by the messaging system. 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.

Because sessions represent resources, like MessageServer connections, it is important to invoke close() on a connection to ensure that critical resources are released before the garbage collector frees the associated object.

Destinations

A destination is the object a JMS client uses to specify the target of the messages it produces and the source of the messages it consumes. In a PTP messaging domain, destinations are called Queues, and in the Pub/Sub messaging domain, destinations are called Topics.

Similar to a connection factory, a WebLogic administrator defines and configures the destination and WebLogic Server adds it to the WebLogic JNDI namespace during startup.

The JMS API also enables you to create destinations ( TemporaryQueue and TemporaryTopic objects) that last only for the duration of the connection in which they are created. Temporary destinations are private to the application in which they are created. Any session created by the same connection as the temporary destination can create consumers for it. However, Sessions created by other connections cannot. If you close the connection that the temporary destination belongs to, the destination is closed and its contents are lost. If you create a temporary destination and specify it as the value of the JMSReplyTo message header field, the consumer of the message can use the JMSReplyTo field as the destination to which it sends a reply and can also reference the original request by setting the JMSCorrelationID header field of the reply message to the value of the JMSMessageID header field of the request.

JMS Queues and Topics extend javax.jms.Destination with the following Destination subclasses:

• Queue (PTP) The JMS PTP provider.

• TemporaryQueue (PTP) JMS PTP provider, and exists for the duration of the JMS connection in which the messages are created.

• Topic (Pub/Sub) The JMS Pub/sub provider.

• TemporaryTopic (Pub/Sub) The JMS PTP provider exists for the duration of the JMS connection in which the messages are created.

MessageProducer

MessageProducer is an interface that encapsulates the functionality necessary to send messages. There are two specialized versions of MessageProducer s for the two messaging domains.

The QueueSender interface extends MessageProducer . PTP clients use QueueSender to send messages. When a client creates a QueueSender it is bound to a queue. The interface also has several overloaded send() methods. TopicPublisher is the Pub/Sub version of MessageProducer .

MessageConsumer

Clients use the MessageConsumer interface to receive messages. PTP clients use the QueueReceiver interface and Pub/Sub clients use topic subscriber.

Because JMS is asynchronous, the MessageConsumer interface provides asynchronous and synchronous receive methods to give developers a degree of control over the way messages are consumed. Table 15.4 describes the four ways to receive a message in JMS.

Table 15.4. JMS Supported Message Types

Receive Mechanism	Description
Blocking receive (synchronous)	Clients invoke MessageConsumer.receive() in a thread. This method blocks until a message is received.
Blocking receive with timeout (synchronous)	Similar to blocking receive, client invokes MessageConsumer.receive(long timeout) in a thread. The thread blocks until either a message is received or the method times out.
Non-blocking receive (synchronous)	Clients call receiveNoWait() , which receives the next message if one is available, or returns null; in this case, the call does not block.
Asynchronous listener (asynchronous)	This mechanism requires clients to provide an object that implements MessageListener . Clients then register their listener with the MessageConsumer . The MessageListener interface has an onMessage() method. onMessage is invoked asynchronously whenever a message arrives.