This section introduces the general procedures for interacting with the Message Queue API to produce and consume messages. The basic steps shown here are elaborated in greater detail in Chapter 2, Using the Java API The procedures for producing and consuming messages have a number of steps in common, which need not be duplicated if the same client is performing both functions.
Get a connection factory.
A Message Queue ConnectionFactory object encapsulates all of the needed configuration properties for creating connections to the Message Queue message service. You can obtain such an object either by direct instantiation.
ConnectionFactory myFctry = new com.sun.messaging.ConnectionFactory(); |
or by looking up a predefined connection factory using the Java Naming and Directory Interface (JNDI). In the latter case, all of the connection factory’s properties will have been preconfigured to the appropriate values by your Message Queue administrator. If you instantiate the factory object yourself, you may need to configure some of its properties explicitly: for instance,
myFctry.setProperty(ConnectionConfiguration.imqAddressList, "localhost:7676, broker2:5000, broker3:9999"); myFctry.setProperty(ConnectionConfiguration.imqReconnectEnabled, "true"); |
See Obtaining a Connection Factory for further discussion.
A Connection object is an active connection to the Message Queue message service, created by the connection factory you obtained in Developing a Client Application:
Connection myConnection = myFactory.createConnection(); |
See Using Connections for further discussion.
Create a session for communicating with the message service.
A Session object represents a single-threaded context for producing and consuming messages. Every session exists within the context of a particular connection and is created by that connection’s createSession method:
Session mySession = myConnection.createSession(false, Session.AUTO_ACKNOWLEDGE); |
The first (boolean) argument specifies whether the session is transacted. The second argument is the acknowledgment mode, such as AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, or DUPS_OK_ACKNOWLEDGE; these are defined as static constants in the JMS Session interface. See Acknowledgment Modes and Transacted Sessions for further discussion.
Get a destination to which to send messages.
A Destination object encapsulates provider-specific naming syntax and behavior for a message destination, which may be either aqueue or a point-to-point publish/subscribe topic (see Messaging Domains). You can obtain such an object by direct instantiation
Destination myDest = new com.sun.messaging.Queue("myDest"); |
or by looking up a predefined destination using the JNDI API. See Working With Destinations for further discussion.
Create a message producer for sending messages to this destination.
A MessageProducer object is created by a session and associated with a particular destination:
MessageProducer myProducer = mySession.createProducer(myDest); |
See Sending Messages for further discussion.
A Session object provides methods for creating each of the six types of message defined by JMS: text, object, stream, map, bytes, and null messages. For instance, you can create a text message with the statement
TextMessage outMsg = mySession.createTextMessage(); |
See Composing Messages for further discussion.
Set the message’s content and properties.
Each type of message has its own methods for specifying the contents of the message body. For instance, you can set the content of a text message with the statement
outMsg.setText("Hello, World!"); |
You can also use the property mechanism to define custom message properties of your own: for instance,
outMsg.setStringProperty("MagicWord", "Shazam"); |
See Working With Messages for further discussion.
The message producer’s send method sends a message to the destination with which the producer is associated:
myProducer.send(outMsg); |
See Sending Messages for further discussion.
When there are no more messages to send, you should close the session
mySession.close(); |
allowing Message Queue to free any resources it may have associated with the session. See Working With Sessions for further discussion.
When all sessions associated with a connection have been closed, you should close the connection by calling its close method:
myConnection.close(); |
See Using Connections for further discussion.
Get a connection factory.
A Message Queue ConnectionFactory object encapsulates all of the needed configuration properties for creating connections to the Message Queue message service. You can obtain such an object either by direct instantiation
ConnectionFactory myFctry = new com.sun.messaging.ConnectionFactory(); |
or by looking up a predefined connection factory using the Java Naming and Directory Interface (JNDI). In the latter case, all of the connection factory’s properties will have been preconfigured to the appropriate values by your Message Queue administrator. If you instantiate the factory object yourself, you may need to configure some of its properties explicitly: for instance,
myFctry.setProperty(ConnectionConfiguration.imqAddressList, "localhost:7676, broker2:5000, broker3:9999"); myFctry.setProperty(ConnectionConfiguration.imqReconnectEnabled,"true"); |
See Obtaining a Connection Factory for further discussion.
A Connection object is an active connection to the Message Queue message service, created by the connection factory you obtained in Developing a Client Application:
Connection myConnection = myFactory.createConnection(); |
See Using Connections for further discussion.
Create a session for communicating with the message service.
A Session object represents a single-threaded context for producing and consuming messages. Every session exists within the context of a particular connection and is created by that connection’s createSession method:
Session mySession = myConnection.createSession(false, Session.AUTO_ACKNOWLEDGE); |
The first (boolean) argument specifies whether the session is transacted. The second argument is the acknowledgment mode, such as AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, or DUPS_OK_ACKNOWLEDGE; these are defined as static constants in the JMS Session interface. See Acknowledgment Modes and Transacted Sessions for further discussion.
Get a destination from which to receive messages.
A Destination object encapsulates provider-specific naming syntax and behavior for a message destination, which may be either a point-to-point queue or a publish/subscribe topic (see Messaging Domains). You can obtain such an object by direct instantiation
Destination myDest = new com.sun.messaging.Queue("myDest"); |
or by looking up a predefined destination using the JNDI API. See Working With Destinations for further discussion.
Create a message consumer for receiving messages from this destination.
A MessageConsumer object is created by a session and associated with a particular destination:
MessageConsumer myConsumer = mySession.createConsumer(myDest); |
See Receiving Messages for further discussion.
In order for a connection’s message consumers to begin receiving messages, you must start the connection by calling its start method:
myConnection.start(); |
See Using Connections for further discussion.
The message consumer’s receive method requests a message from the destination with which the consumer is associated:
Message inMsg = myConsumer.receive(); |
This method is used for synchronous consumption of messages. You can also configure a message consumer to consume messages asynchronously, by creating a message listener and associating it with the consumer. See Receiving Messages for further discussion.
Retrieve the message’s content and properties.
Each type of message has its own methods for extracting the contents of the message body. For instance, you can retrieve the content of a text message with the statements
TextMessage txtMsg = (TextMessage) inMsg; String msgText = txtMsg.getText(); |
In addition, you may need to retrieve some of the message’s header fields: for instance,
msgPriority = inMsg.getJMSPriority(); |
You can also use message methods to retrieve custom message properties of your own: for instance,
magicWord = inMsg.getStringProperty("MagicWord"); |
See Processing Messages for further discussion.
When there are no more messages to consume, you should close the session
mySession.close(); |
allowing Message Queue to free any resources it may have associated with the session. See Working With Sessions for further discussion.
When all sessions associated with a connection have been closed, you should close the connection by calling its close method:
myConnection.close(); |
See Using Connections for further discussion.