Using Connections

Once you have obtained a connection factory, you can use it to create a connection to the message service. The factory’s createConnection method takes a user name and password as arguments:

Connection
      myConnection = myFactory.createConnection("mithrandir", "mellon");

Before granting the connection, Message Queue authenticates the user name and password by looking them up in its user repository. As a convenience for developers who do not wish to go to the trouble of populating a user repository during application development and testing, there is also a parameterless form of the createConnection method:

Connection  myConnection = myFactory.createConnection();

This creates a connection configured for the default user identity, with both user name and password set to guest.

This unified-domain createConnection method is part of the generic JMS ConnectionFactory interface, defined in package javax.jms; the Message Queue version in com.sun.messaging adds corresponding methods createQueueConnection and createTopicConnection for use specifically with the point-to-point and publish/subscribe domains.

The following table shows the methods defined in the Connection interface.

The main purpose of a connection is to create sessions for exchanging messages with the message service:

myConnection.createSession(false, Session.AUTO_ACKNOWLEDGE);

The first argument to createSession is a boolean indicating whether the session is transacted; the second specifies its acknowledgment mode. Possible values for this second argument are AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, and DUPS_OK_ACKNOWLEDGE, all defined as static constants in the standard JMS Session interface, javax.jms.Session ; the extended Message Queue version of the interface, com.sun.messaging.jms.Session , adds another such constant, NO_ACKNOWLEDGE. See Acknowledgment Modes and Transacted Sessions for further discussion.

If your client application will be using the publish/subscribe domain to create durable topic subscriptions, it must have a client identifier to identify itself to the message service. In general, the most convenient arrangement is to configure the client runtime to provide a unique client identifier automatically for each client. However, the Connection interface also provides a method, setClientID, for setting a client identifier explicitly, and a corresponding getClientID method for retrieving its value. See Assigning Client Identifiers and Client Identifier in Sun Java System Message Queue 4.2 Administration Guide for more information.

You should also use the setExceptionListener method to register an exception listener for the connection. This is an object implementing the JMS ExceptionListener interface, which consists of the single method onException:

void  onException (JMSException  exception)

In the event of a problem with the connection, the message broker will call this method, passing an exception object identifying the nature of the problem.

A connection’s getMetaData method returns a ConnectionMetaData object, which in turn provides methods for obtaining various items of information about the connection, such as its JMS version and the name and version of the JMS provider.

The createConnectionConsumer and createDurableConnectionConsumer methods (as well as the session methods setMessageListener and getMessageListener, listed in Table 2–3) are used for concurrent message consumption; see the Java Message Service Specification for more information.

In order to receive incoming messages, you must 7start the connection by calling its start method:

myConnection.start();

It is important not to do this until after you have created any message consumers you will be using to receive messages on the connection. Starting the connection before creating the consumers risks missing some incoming messages before the consumers are ready to receive them. It is not necessary to start the connection in order to send outgoing messages.

If for any reason you need to suspend the flow of incoming messages, you can do so by calling the connection’s stop method:

myConnection.stop();

To resume delivery of incoming messages, call the start method again.

Finally, when you are through with a connection, you should close it to release any resources associated with it:

myConnection.close();

This automatically closes all sessions, message producers, and message consumers associated with the connection and deletes any temporary destinations. All pending message receives are terminated and any transactions in progress are rolled back. Closing a connection does not force an acknowledgment of client-acknowledged sessions.