Programming Objects

The objects used to implement JMS messaging remain essentially the same across programming domains: connection factories, connections, sessions, producers, consumers, messages, and destinations. These objects are shown in Figure 2–5. The figure shows, from the top down, how objects are derived, starting with the connection factory object.

Two of the objects, connection factories and destinations, are shown to reside in an object store. This is to underline the fact that these objects are normally created, configured, and managed as administered objects. We assume that connection factories and destinations are created administratively (rather than programmatically) throughout this chapter.

Figure 2–5 JMS Programming Objects

Table 2–2 summarizes the steps required to send and receive messages. Note that steps 1 through 6 are the same for senders and receivers.

Table 2–2 Producing and Consuming Messages.

Producing a Message	Consuming a Message
1. The administrator creates a connection factory administered object.
2. The administrator creates a physical destination and the administered object that refers to it.
3. The client obtains a connection factory object through a JNDI lookup.
4. The client obtains a destination object through a JNDI lookup.
5. The client creates a connection and sets any properties that are specific to this connection.
6. The client creates a session and sets the properties that govern messaging reliability.
7. The client creates a message producer	The client creates a message consumer
8. The client creates a message.	The client starts the connection.
9. The client sends a message.	The client receives a message.

The following sections describe the objects used by producers and consumers: connections, sessions, messages, and destinations. We will then complete the discussion of JMS objects by describing the production and consumption of messages.

Connection Factories and Connections

A client uses a connection factory object (ConnectionFactory) to create a connection. A connection object ( Connection) represents a client’s active connection to the broker. It uses the underlying connection service that is either started by default or is explicitly started by the administrator for this client.

Both allocation of communication resources and authentication of the client take place when a connection is created. It is a relatively heavyweight object, and most clients do all their messaging with a single connection. Connections support concurrent use: any number of producers and consumers can share a connection.

When you create a connection factory, you can configure the behavior of all connections derived from it by setting its properties. For Message Queue, these specify the following information:

• The name of the host on which the broker resides, the connection service desired, and the port through which the client wants to access that service.

• How automatic reconnection to the broker should be handled if the connection fails. (This feature reconnects the client to the same (or to a different broker) if a connection is lost. Data failover is not guaranteed: persistent messages and other state information can be lost when reconnecting to a different broker.)

• The ID of a client that needs the broker to track its durable subscription.

• The default name and password of the user attempting the connection. This information is used to authenticate the user and authorize operations if a password is not specified at connection time.

• Whether broker acknowledgements should be suppressed for those clients who are not concerned with reliability.

• How to manage the flow of control and payload messages between the broker and the client runtime.

• How queue browsing should be handled. (Java clients only.)

• Whether certain message header fields should be overridden.

It is possible to override connection factory properties from the command line used to start the client application. It is also possible to override properties for any given connection by setting properties for that connection.

You can use a connection object to create session objects, to set up an exception listener, or to obtain JMS version and provider information.

Sessions

If the connection represents a communication channel between the client and the broker, a session marks a single conversation between them. Mainly, you use a session object to create messages, message producers, and message consumers. When you create a session, you configure reliable delivery through a number of acknowledgement options or through transactions. For more information, see Reliable Messaging.

According to the JMS specification, a session is a single-threaded context for producing and consuming messages. You can create multiple message producers and consumers for a single session, but you are restricted to using them serially. The threading implementation varies slightly for Java and C clients. Consult the appropriate developer’s guide for additional information about threading implementation and restrictions.

You can also use a session object to do the following:

• Create and configure destinations for those clients that do not use administered objects to define destinations.

• Create and configure temporary topics and queues; these are used as part of the request-reply pattern. See The Request-Reply Pattern.

• Support transaction processing.

• Define a serial order for producing or consuming messages.

• Serialize the execution of message listeners for asynchronous consumers.

• Create queue browsers. (Java clients only.)

Messages

A message is composed of three parts: a header, properties, and a body. You must understand this structure in order to compose a message properly and to configure certain messaging behaviors.

Message Header

A header is required of every JMS message. The header contains ten predefined fields, which are listed and described in Table 2–3.

Table 2–3 JMS-Defined Message Header

Header Field	Description
JMSDestination	Specifies the name of the destination object to which the message is sent. (Set by the provider.)
JMSDeliveryMode	Specifies whether the message is persistent. (Set by default by the provider or explicitly by the client for a producer or for an individual message.)
JMSExpiration	Specifies the time when the message will expire. (Set by default by the provider or by the client for a producer or for an individual message.)
JMSPriority	Specifies the priority of the message within a 0 (low) to 9 (high) range. (Set by default by the provider or set explicitly by the client for a producer or for an individual message.)
JMSMessageID	Specifies a unique ID for the message within the context of a provider installation. (Set by the provider.)
JMSTimestamp	Specifies the time when the provider received the message. (Set by the provider.)
JMSCorrelationID	A value that allows a client to define a correspondence between two messages. (Set by the client if needed.)
JMSReplyTo	Specifies a destination where the consumer should send a reply. (Set by the client if needed.)
JMSType	A value that can be evaluated by a message selector. (Set by the client if needed.)
JMSRedelivered	Specifies whether the message has already been delivered but not acknowledged. (Set by the provider.)

As you can see from reading through this table, message header fields serve a variety of purposes: identifying a message, configuring the routing of messages, providing information about message handling, and so on.

One of the most important fields, JMSDeliveryMode, determines the reliability of message delivery. This field indicates whether a message is persistent.

• Persistent messages. are guaranteed to be delivered and successfully consumed exactly once. Persistent messages are not lost if the message service fails.

• Non-persistent messages are guaranteed to be delivered at most once. Non-persistent messages can be lost if the message service fails.

Some message header fields are set by the provider (either the broker or the client runtime) and others are set by the client. Message producers may need to configure header values to obtain certain messaging behaviors; message consumers may need to read header values in order to understand how the message was routed and what further processing it might need.

The header fields (JMSDeliveryMode, JMSExpiration, and JMSPriority) can be set at three different levels:

• For messages issuing from every connection derived from a connection factory.

• For each message produced.

• For all messages issued by a specific message producer.

If these fields are set at more than one level, values set for the connection factory override those set for the individual message; values set for a given message override those set for the message’s producer.

Constant names for message header fields vary with the language implementation. See Sun Java System Message Queue 3.7 UR1 Developer’s Guide for Java Clients or Sun Java System Message Queue 3.7 UR1 Developer’s Guide for C Clients for more information.

Message Properties

A message can also include optional header fields, called properties, specified as property name and property value pairs. Properties allow clients and providers to extend the message header and can contain any information that the client or the provider finds useful to identify and process a message. Message properties allow a receiving client to ask that only those messages be delivered which fit a given criteria. For instance, a consuming client might indicate an interest for payroll messages concerning part-time employees located in New Jersey. The provider will not deliver messages that do not meet the specified criteria.

The JMS specification defines nine standard properties. Some of these are set by the client and some by the provider. Their names begin with the reserved characters “JMSX.” The client or the provider can use these properties to determine who sent a message, the state of the message, how often and when it was delivered. These properties are useful to the provider in routing messages and in providing diagnostic information.

Message Queue also defines message properties, these are used to identify compressed messages and how messages should be handled if they cannot be delivered. For more information see Managing Message Size in Sun Java System Message Queue 3.7 UR1 Developer’s Guide for Java Clients.

Message Body

The message body contains the data that clients want to exchange.

The type of a JMS message determines what the body may contain and how it should be processed by the consumer, as specified in Table 2–4. The Session object includes a create method for each type of message body.

Table 2–4 Message Body Types

Type	Description
StreamMessage	A message whose body contains a stream of Java primitive values. It is filled and read sequentially.
MapMessage	A message whose body contains a set of name-value pairs. The order of entries is not defined.
TextMessage	A message whose body contains a Java string, for example an XML message.
ObjectMessage	A message whose body contains a serialized Java object.
BytesMessage	A message whose body contains a stream of uninterpreted bytes.
Message	A message that contains a header and properties but no body.

Java clients can set a property to have the client runtime compress the body of a message being sent. The Message Queue runtime on the consumer side decompresses the message before delivering it.