2 Using the Java API

Looking Up a Connection Factory With JNDI

Example 2-1 shows how to look up a connection factory object in the JNDI object store. The code example is explained in the procedure that follows.

//  Create the environment for constructing the initial JNDI 
//  naming context.
    
    Hashtable  env = new Hashtable();
    
    
//  Store the environment attributes that tell JNDI which initial context
//  factory to use  and where to find the provider.// 
    
    env.put(Context.INITIAL_CONTEXT_FACTORY, 
                    "com.sun.jndi.fscontext.RefFSContextFactory");
    env.put(Context.PROVIDER_URL, "file:///C:/imq_admin_objects");
    
    
//  Create the initial context.
    
    Context  ctx = new InitialContext(env);
    
    
//  Look up the connection factory object in the JNDI object store.
    
    String  CF_LOOKUP_NAME = "MyConnectionFactory";
    ConnectionFactory  myFactory = (ConnectionFactory) ctx.lookup
                                          (CF_LOOKUP_NAME);
    
               

Overriding Configuration Settings

It is recommended that you use a connection factory just as you receive it from a JNDI lookup, with the property settings originally configured by your Message Queue administrator. However, there may be times when you need to override the preconfigured properties with different values of your own. You can do this from within your application code by calling the connection factory's setProperty method. This method (inherited from the superclass AdministeredObject) takes two string arguments giving the name and value of the property to be set. The property names for the first argument are defined as static constants in the Message Queue class ConnectionConfiguration: for instance, the statement

myFactory.setProperty(ConnectionConfiguration.imqDefaultPassword,
                      "mellon");

sets the default password for establishing broker connections. See "Connection Factory Attributes" in Oracle GlassFish Server Message Queue Administration Guide for complete information on the available connection factory configuration attributes.

It is also possible to override connection factory properties from the command line, by using the -D option to set their values when starting your client application. For example, the command line

java -DimqDefaultPassword=mellon MyMQClient

starts an application named MyMQClient with the same default password as in the preceding example. Setting a property value this way overrides any other value specified for it, whether preconfigured in the JNDI object store or set programmatically with the setProperty method.

Instantiating a Connection Factory

Example 2-2 shows how to create a connection factory object by direct instantiation and configure its properties.

//  Instantiate the connection factory object.
    
    com.sun.messaging.ConnectionFactory
        myFactory = new com.sun.messaging.ConnectionFactory();
    
    
//  Set the connection factory's configuration properties.
    
    myFactory.setProperty(ConnectionConfiguration.imqAddressList,
                          "localhost:7676,broker2:5000,broker3:9999");

The following procedure explains each program satement in the previous code sample.

To Look Up a Destination With JNDI

1. Create the environment for constructing the initial JNDI naming context.

   How you create the initial context depends on whether you are using a file-system object store or a Lightweight Directory Access Protocol (LDAP) server for your Message Queue administered objects. The code shown here assumes a file-system store; for information about the corresponding LDAP object store attributes, see "LDAP Server Object Stores" in Oracle GlassFish Server Message Queue Administration Guide.

   The constructor for the initial context accepts an environment parameter, a hash table whose entries specify the attributes for creating the context:

   Hashtable env = new Hashtable();
   

   You can also set an environment by specifying system properties on the command line, rather than programmatically. For instructions, see the README file in the JMS example applications directory.

2. Store the environment attributes that tell JNDI which initial context factory to use and where to find the JMS provider.

   The names of these attributes are defined as static constants in class Context:

   env.put(Context.INITIAL_CONTEXT_FACTORY,
           "com.sun.jndi.fscontext.RefFSContextFactory");
   env.put(Context.PROVIDER_URL, "file:///C:/imq_admin_objects");
   

   Note:

   The directory represented by C:/imq_admin_objects must already exist; if necessary, you must create the directory before referencing it in your code.

3. Create the initial context.

   Context ctx = new InitialContext(env);
   

   If you use system properties to set the environment, omit the environment parameter when creating the context:

   Context ctx = new InitialContext();
   

4. Look up the destination object in the administered object store and typecast it to the appropriate class:

   String DEST_LOOKUP_NAME = "MyDest";
   Destination MyDest = (Destination) ctx.lookup(DEST_LOOKUP_NAME);
   

   The lookup name you use, DEST_LOOKUP_NAME, must match the name used when the object was stored. Note that the actual destination object returned from the object store will always be either a (point-to-point) queue or a (publish/subscribe) topic, but that either can be assigned to a variable of the generic unified-domain class Destination.

   Note:

   For topic destinations, a symbolic lookup name that includes wildcard characters can be used as the lookup string. See "Supported Topic Destination Names" in Oracle GlassFish Server Message Queue Administration Guide.

   You can now proceed to send and receive messages using the destination, as described under Sending Messages and Receiving Messages.

Message Header

Every message must have a header containing identifying and routing information. The header consists of a set of standard fields, which are defined in the Java Message Service Specification and summarized in Table 2-4. Some of these are set automatically by Message Queue in the course of producing and delivering a message, some depend on settings specified when a message producer sends a message, and others are set by the client on a message-by-message basis.

The JMS Message interface defines methods for setting the value of each header field: for instance,

outMsg.setJMSReplyTo(replyDest);

Table 2-5 lists all of the available header specification methods.

The message identifier (JMSMessageID) is a string value uniquely identifying the message, assigned and set by the message broker when the message is sent. Because generating an identifier for each message adds to both the size of the message and the overhead involved in sending it, and because some client applications may not use them, the JMS interface provides a way to suppress the generation of message identifiers, using the message producer method setDisableMessageID (see Sending Messages).

The JMSDestination header field holds a Destination object representing the destination to which the message is directed, set by the message broker when the message is sent. There is also a JMSReplyTo field that you can set to specify a destination to which reply messages should be directed. Clients sending such a reply message can set its JMSCorrelationID header field to refer to the message to which they are replying. Typically this field is set to the message identifier string of the message being replied to, but client applications are free to substitute their own correlation conventions instead, using either the setJMSCorrelationID method (if the field value is a string) or the more general setJMSCorrelationIDAsBytes (if it is not).

The delivery mode (JMSDeliveryMode) specifies whether the message broker should log the message to stable storage. There are two possible values, PERSISTENT and NON_PERSISTENT, both defined as static constants of the JMS interface DeliveryMode: for example,

outMsg.setJMSDeliveryMode(DeliveryMode.NON_PERSISTENT);

The default delivery mode is PERSISTENT, represented by the static constant Message.DEFAULT_DELIVERY_MODE.

The choice of delivery mode represents a tradeoff between performance and reliability:

• In persistent mode, the broker logs the message to stable storage, ensuring that it will not be lost in transit in the event of transmission failure; the message is guaranteed to be delivered exactly once.

• In nonpersistent mode, the message is not logged to stable storage; it will be delivered at most once, but may be lost in case of failure and not delivered at all. This mode does, however, improve performance by reducing the broker's message-handling overhead. It may thus be appropriate for applications in which performance is at a premium and reliability is not.

The message's priority level (JMSPriority) is expressed as an integer from 0 (lowest) to 9 (highest). Priorities from 0 to 4 are considered gradations of normal priority, those from 5 to 9 of expedited priority. The default priority level is 4, represented by the static constant Message.DEFAULT_PRIORITY.

The Message Queue client runtime sets the JMSTimestamp header field to the time it delivers the message to the broker, expressed as a long integer in standard Java format (milliseconds since midnight, January 1, 1970 UTC). The message's lifetime, specified when the message is sent, is added to this value and the result is stored in the JMSExpiration header field. (The default lifetime value of 0, represented by the static constant Message.DEFAULT_TIME_TO_LIVE, denotes an unlimited lifetime. In this case, the expiration time is also set to 0 to indicate that the message never expires.) As with the message identifier, client applications that do not use a message's time stamp can improve performance by suppressing its generation with the message producer method setDisableMessageTimestamp (see Sending Messages).

The header field JMSType can contain an optional message type identifier string supplied by the client when the message is sent. This field is intended for use with other JMS providers; Message Queue clients can simply ignore it.

When a message already delivered must be delivered again because of a failure, the broker indicates this by setting the JMSRedelivered flag in the message header to true. This can happen, for instance, when a session is recovered or a transaction is rolled back. The receiving client can check this flag to avoid duplicate processing of the same message (such as when the message has already been successfully received but the client's acknowledgment was missed by the broker).

See the Java Message Service Specification for a more detailed discussion of all message header fields.

Message Properties

A message property consists of a name string and an associated value, which must be either a string or one of the standard Java primitive data types (int, byte, short, long, float, double, or boolean). The Message interface provides methods for setting properties of each type (see Table 2-6). There is also a setObjectProperty method that accepts a primitive value in objectified form, as a Java object of class Integer, Byte, Short, Long, Float , Double, Boolean, or String . The clearProperties method deletes all properties associated with a message; the message header and body are not affected.

The JMS specification defines certain standard properties, listed in Table 2-7 . By convention, the names of all such standard properties begin with the letters JMSX; names of this form are reserved and must not be used by a client application for its own custom message properties. Similarly, property names beginning with JMS_SUN are reserved for provider-specific properties defined by Message Queue itself; these are discussed in Message Queue Clients: Design and Features.

Message Body

The actual content of a message is contained in the message body. JMS defines six classes (or types) of message, each with a different body format:

• A text message (interface TextMessage) contains a Java string.

• A stream message (interface StreamMessage) contains a stream of Java primitive values, written and read sequentially.

• A map message (interface MapMessage) contains a set of name-value pairs, where each name is a string and each value is a Java primitive value. The order of the entries is undefined; they can be accessed randomly by name or enumerated sequentially.

• An object message (interface ObjectMessage) contains a serialized Java object (which may in turn be a collection of other objects).

• A bytes message (interface BytesMessage) contains a stream of uninterpreted bytes.

• A null message (interface Message) consists of a header and properties only, with no message body.

Each of these is a subinterface of the generic Message interface, extended with additional methods specific to the particular message type.

Composing Text Messages

You create a text message with the session method createTextMessage. You can either initialize the message body directly at creation time

TextMessage outMsg = mySession.createTextMessage("Hello, World!");

or simply create an empty message and then use its setText method (see Table 2-9 ) to set its content:

TextMessage outMsg = mySession.createTextMessage();
outMsg.setText("Hello, World!");

Composing Stream Messages

The session method createStreamMessage returns a new, empty stream message. You can then use the methods shown in Table 2-10 to write primitive data values into the message body, similarly to writing to a data stream: for example,

StreamMessage outMsg = mySession.createStreamMessage();
outMsg.writeString("The Meaning of Life");
outMsg.writeInt(42);

As a convenience for handling values whose types are not known until execution time, the writeObject method accepts a string or an objectified primitive value of class Integer, Byte, Short, Long, Float, Double , Boolean, or Character and writes the corresponding string or primitive value to the message stream: for example, the statements

Integer meaningOfLife = new Integer(42);
outMsg.writeObject(meaningOfLife);

are equivalent to

outMsg.writeInt(42);

This method will throw an exception (MessageFormatException) if the argument given to it is not of class String or one of the objectified primitive classes.

Once you've written the entire message contents to the stream, the reset method

outMsg.reset();

puts the message body in read-only mode and repositions the stream to the beginning, ready to read (see Processing Messages). When the message is in this state, any attempt to write to the message stream will throw the exception MessageNotWriteableException. A call to the clearBody method (inherited from the superinterface Message) deletes the entire message body and makes it writeable again.

Composing Map Messages

Table 2-11 shows the methods available in the MapMessage interface for adding content to the body of a map message. Each of these methods takes two arguments, a name string and a primitive or string value of the appropriate type, and adds the corresponding name-value pair to the message body: for example,

StreamMessage outMsg = mySession.createMapMessage();
outMsg.setInt("The Meaning of Life", 42);

Like stream messages, map messages provide a convenience method (setObject) for dealing with values whose type is determined dynamically at execution time: for example, the statements

Integer meaningOfLife = new Integer(42);
outMsg.setObject("The Meaning of Life", meaningOfLife);

are equivalent to

outMsg.setInt("The Meaning of Life", 42);

The object supplied must be either a string object (class String) or an objectified primitive value of class Integer, Byte , Short, Long, Float, Double, Boolean, or Character; otherwise an exception (MessageFormatException) will be thrown.

Composing Object Messages

The ObjectMessage interface provides just one method, setObject (Table 2-12 ), for setting the body of an object message:

ObjectMessage outMsg = mySession.createObjectMessage();
outMsg.setObject(bodyObject);

The argument to this method can be any serializable object (that is, an instance of any class that implements the standard Java interface Serializable). If the object is not serializable, the exception MessageFormatException will be thrown.

As an alternative, you can initialize the message body directly when you create the message, by passing an object to the session method createObjectMessage:

ObjectMessage outMsg = mySession.createObjectMessage(bodyObject);

Again, an exception will be thrown if the object is not serializable.

Composing Bytes Messages

The body of a bytes message simply consists of a stream of uninterpreted bytes; its interpretation is entirely a matter of agreement between sender and receiver. This type of message is intended primarily for encoding message formats required by other existing message systems; Message Queue clients should generally use one of the other, more specific message types instead.

Composing a bytes message is similar to composing a stream message (see Composing Stream Messages). You create the message with the session method createBytesMessage, then use the methods shown in Table 2-13 to encode primitive values into the message's byte stream: for example,

BytesMessage outMsg = mySession.createBytesMessage();
outMsg.writeUTF("The Meaning of Life");
outMsg.writeInt(42);

As with stream and map messages, you can use the generic object-based method writeObject to handle values whose type is unknown at compilation time: for example, the statements

Integer meaningOfLife = new Integer(42);
outMsg.writeObject(meaningOfLife);

are equivalent to

outMsg.writeInt(42);

The message's reset method

outMsg.reset();

puts the message body in read-only mode and repositions the byte stream to the beginning, ready to read (see Processing Messages). Attempting to write further content to a message in this state will cause an exception (MessageNotWriteableException). The inherited Message method clearBody can be used to delete the entire message body and make it writeable again.

Creating Message Consumers

The session method createConsumer creates a generic consumer that can be used to receive messages from either a (point-to-point) queue or a (publish/subscribe) topic:

MessageConsumer myConsumer = mySession.createConsumer(myDest);

If the destination is a queue, the consumer is called a receiver for that queue; if it is a topic, the consumer is a subscriber to that topic.

A subscriber created for a topic destination with the createConsumer method is always nondurable, meaning that it will receive only messages that are sent (published)to the topic while the subscriber is active. If you want the broker to retain messages published to a topic while no subscriber is active and deliver them when one becomes active again, you must instead create a durable subscriber, as described in Durable Subscribers.

Table 2-15 shows the methods defined in the MessageConsumer interface, which are discussed in detail in the relevant sections below.

String mySelector = "/* Text of selector here */";
MessageConsumer myConsumer = mySession.createConsumer(myDest, mySelector);

String mySelector = myConsumer.getMessageSelector();

String mySelector = "/* Text of selector here */";
MessageConsumer
        myConsumer = mySession.createConsumer(myDest, mySelector, true);

MessageConsumer
        myConsumer = mySession.createDurableSubscriber(myDest, "mySub");

String mySelector = "/* Text of selector here */";
MessageConsumer myConsumer
                    = mySession.createDurableSubscriber(myDest, "mySub",
                                                        mySelector, true);

mySession.unsubscribe("mySub");

Receiving Messages Synchronously

Once you have created a message consumer for a session, using either the createConsumer orcreateDurableSubscriber method, you must start the session's connection to begin the flow of incoming messages:

myConnection.start();

(Note that it is not necessary to start a connection in order to produce messages, only to consume them.) You can then use the consumer's receive method to receive messages synchronously from the message broker:

Message inMsg = myConsumer.receive();

This returns the next available message for this consumer. If no message is immediately available, the receive method blocks until one arrives. You can also provide a timeout interval in milliseconds:

Message inMsg = myConsumer.receive(1000);

In this case, if no message arrives before the specified timeout interval (1 second in the example) expires, the method will return with a null result. An alternative method, receiveNoWait, returns a null result immediately if no message is currently available:

Message inMsg = myConsumer.receiveNoWait();

Receiving Messages Asynchronously

If you want your message consumer to receive incoming messages asynchronously, you must create a message listener to process the messages. This is a Java object that implements the JMS MessageListener interface. The procedure is as follows:

Acknowledging Messages

If you have specified client-acknowledge as your session's acknowledgment mode (see Acknowledgment Modes), it is your client application's responsibility to explicitly acknowledge each message it receives. If you have received the message synchronously, using a message consumer's receive (or receiveNoWait) method, you should process the message first and then acknowledge it; if you have received it asynchronously, your message listener's onMessage method should acknowledge the message after processing it. This ensures that the message broker will not delete the message from persistent storage until processing is complete.

Table 2-16 shows the methods available for acknowledging a message. The most general is acknowledge, defined in the standard JMS interface javax.jms.Message:

inMsg.acknowledge();

This acknowledges all unacknowledged messages consumed by the session up to the time of call. You can use this method to acknowledge each message individually as you receive it, or you can group several messages together and acknowledge them all at once by calling acknowledge on the last one in the group.

The Message Queue version of the Message interface, defined in the package com.sun.messaging.jms, adds two more methods that provide more flexible control over which messages you acknowledge. The acknowledgeThisMessage method just acknowledges the single message for which it is called, rather than all messages consumed by the session; acknowledgeUpThroughThisMessage acknowledges the message for which it is called and all previous messages; messages received after that message remain unacknowledged.

Browsing Messages

If the destination from which you are consuming messages is a point-to-point queue, you can use a queue browser to examine the messages in the queue without consuming them. The session method createBrowser creates a browser for a specified queue:

QueueBrowser myBrowser = mySession.createBrowser(myDest);

The method will throw an exception (InvalidDestinationException) if you try to pass it a topic destination instead of a queue. You can also supply a selector string as an optional second argument:

String        mySelector = "/* Text of selector here */";
QueueBrowser  myBrowser  = mySession.createBrowser(myDest, mySelector);

Table 2-17 shows the methods defined in the QueueBrowser interface. The getQueue and getMessageSelector methods return the browser's queue and selector string, respectively.

The most important queue browser method is getEnumeration, which returns a Java enumeration object that you can use to iterate through the messages in the queue, as shown in Example 2-4.

Enumeration  queueMessages = myBrowser.getEnumeration();
Message      eachMessage;

while ( queueMessages.hasMoreElements() )
  { eachMessage = queueMessages.nextElement();
    /* Do something with the message */
  }

The browser's close method closes it when you're through with it:

myBrowser.close();

Closing a Consumer

As a matter of good programming practice, you should close a message consumer when you have no further need for it. Closing a session or connection automatically closes all consumers associated with it; to close a consumer without closing the session or connection to which it belongs, you can use its close method:

myConsumer.close();

For a consumer that is a nondurable topic subscriber, this terminates the flow of messages to the consumer. However, if the consumer is a queue receiver or a durable topic subscriber, messages will continue to be accumulated for the destination and will be delivered the next time a consumer for that destination becomes active. To terminate a durable subscription permanently, call its session's unsubscribe method with the subscriber name as an argument:

mySession.unsubscribe("mySub");

Retrieving Message Header Fields

The standard JMS message header fields are described in Table 2-4. Table 2-18 shows the methods provided by the JMS Message interface for retrieving the values of these fields: for instance, you can obtain a message's reply destination with the statement

Destination replyDest = inMsg.getJMSReplyTo();

Retrieving Message Properties

Table 2-19 lists the methods defined in the JMS Message interface for retrieving the values of a message's properties (see Message Properties). There is a retrieval method for each of the possible primitive types that a property value can assume: for instance, you can obtain a message's time stamp with the statement

long  timeStamp = inMsg.getLongProperty("JMSXRcvTimestamp");

There is also a generic getObjectProperty method that returns a property value in objectified form, as a Java object of class Integer, Byte, Short, Long, Float , Double, Boolean, or String . For example, another way to obtain a message's time stamp, equivalent to that shown above, would be

Long  timeStampObject = (Long)inMsg.getObjectProperty("JMSXRcvTimestamp");
long  timeStamp = timeStampObject.longValue();

If the message has no property with the requested name, getObjectProperty will return null; the message method propertyExists tests whether this is the case.

The getPropertyNames method returns a Java enumeration object for iterating through all of the property names associated with a given message; you can then use the retrieval methods shown in the table to retrieve each of the properties by name, as shown in Example 2-5.

Enumeration  propNames = inMsg.getPropertyNames();
String       eachName;
Object       eachValue;

while ( propNames.hasMoreElements() )
  { eachName  = propNames.nextElement();
    eachValue = inMsg.getObjectProperty(eachName);
    /* Do something with the value */
  }
               

Processing the Message Body

The methods for retrieving the contents of a message's body essentially parallel those for composing the body, as described earlier under Composing Messages. The following sections describe these methods for each of the possible message types (text, stream, map, object, and bytes).

String textBody = inMsg.getText();

int intVal = inMsg.readInt();

Integer  intObject = (Integer) inMsg.readObject();
int      intVal    = intObject.intValue();

int meaningOfLife = inMsg.getInt("The Meaning of Life");

Integer  meaningObject = (Integer) inMsg.getObject("The Meaning of Life");
int      meaningOfLife = meaningObject.intValue();

if ( inMsg.itemExists("The Meaning of Life") )
  { /* Life is meaningful */
  }
else
  { /* Life is meaningless */
  }

Enumeration  mapNames = inMsg.getMapNames();
String       eachName;
Object       eachValue;

while ( mapNames.hasMoreElements() )
  { eachName  = mapNames.nextElement();
    eachValue = inMsg.getObject(eachName);
    /* Do something with the value */
  }
                  

Object messageBody = inMsg.getObject();

int intVal = inMsg.readInt();

int bodyLength = inMsg.getBodyLength();