Connections

Connections are created using factory methods provided by the connection factories. The PTP messaging model uses queue connections and the Pub/Sub messaging model uses topic connections. Queue connections are created using queue connection factories and topic connections are created using topic connection factories.

The basic methods used for JMS connections are defined in the interface javax.jms.Connection. Methods specific to the PTP messaging model are defined in the interface javax.jms.QueueConnection, and those specific to the Pub/Sub message model are defined in the interface javax.jms.TopicConnection. JMS providers provide implementation classes for these interfaces. Connections serve various purposes in writing JMS clients:

• Connection factories provide client authentication when connections are created

• Connection objects act as factories for creating JMS sessions

• Connections can be used to define identifiers for JMS clients

• Connections provide facilities to the JMS clients to be asynchronously notified by the provider of internal exceptions

Client Authentication

JMS clients are authenticated at the point of creating connections. Connection factories provide two overloaded methods for creating connections. The first one uses the default security credentials for the JMS client thread and the second one provides facility for specifying the user name and password. JMS doesn't define the specifics of security credentials and client authentication. Different JMS providers provide client authentication in vendor-specific manners.

Connection States

A typical JMS client first looks up the required Administered objects (connection factories and destinations) and uses the connection factories to create connections. These connections are used to create sessions and sessions are used to create message consumers and producers. When a connection is created using the connection factory it is created in the stopped mode. Even though connections in stopped mode can produce messages, they are not ready to consume messages. To enable message delivery the connection needs to be explicitly started. The interface javax.jms.Connection defines the method for starting connections:

     public void start() throws JMSException 

This method throws a JMSException if the provider fails to start message delivery to this connection due to any internal error.

Connections can be temporarily stopped. When a connection is stopped temporarily, message delivery to this connection is stopped. Calling the method to start the connection discussed above can restart message delivery. JMS clients can still use stopped connections for sending messages, but they can't use stopped connections for receiving messages. The method signature for stopping the connections temporarily is shown below:

     public void stop() throws JMSException 

This method doesn't return until the message delivery currently in progress is completed. This method throws a JMSException if the JMS provider fails to stop message delivery due to any internal server error.

Connection objects use expensive client-side resources. So it is better to free up these resources when the connection is not in use, by closing the connection. Closing a connection will close all the sessions, producers and consumers associated with the connection. The method signature for stopping the connections temporarily is shown below:

     public void close() throws JMSException 

This method doesn't return until all the message delivery currently in progress is completed. This method throws a JMSException if the JMS provider fails to close the connection. JMS clients trying to use a closed connection will get an exception.

Client Identifiers

Client identifiers are used for state management at the provider. Providers can use client identifiers to identify the connections and associated objects used by a particular client. There are two ways to assign an identifier to a JMS client. Client identifiers can be used to associate a client connection and related objects to a state maintained by the provider for a client.

The javax.jms.Connection interface defines two methods for managing client identifiers. The first method is used to set a client identifier with a connection:

     public void setClientID(java.lang.String clientID) throws JMSException 

This method explicitly sets a client identifier to the connection. This method throws a JMSException if the provider fails to set the client identifier and an InvalidClientIDException if the client ID is invalid or duplicate.

The second method is used for accessing the client identifier associated with a connection:

 public java.lang.String getClientID() throws JMSException 

This method throws a JMSException if the provider fails to return the client identifier due to any internal server error.

An alternative way of assigning client identifiers is to use client-specific connection factories. Connection factories can be configured such that all the connections created by a connection factory will be assigned a specific client identifier. Configuring connection factories to accomplish this task is specific to JMS providers.

Trying to set the client ID explicitly on a connection created with a pre-configured client ID will throw an IllegalStateException.

Exception Listeners

Connections can asynchronously notify JMS clients about internal problems with the provider. This is achieved using exception listeners. The javax.jms.Connection interface defines two methods for handling exception listeners with the connection. The first method is used for registering an exception listener with the connection:

     public void setExceptionListener(ExceptionListener listener)                                                   throws JMSException 

The second method provides access to the registered exception listener:

     public ExceptionListener getExceptionListener() throws JMSException 

javax.jms.ExceptionListener

Exception listeners enable JMS clients to be notified asynchronously about any serious problem with the connection. The implementation classes for exception listeners need to implement the method defined in this interface:

     public void onException(JMSException ex) 

Only those exceptions that cannot be notified to the JMS clients otherwise will be notified using this mechanism. For example, if a JMS method call throws a JMSException, the JMS client won't be notified about the exception using this mechanism. The JMS provider will try to resolve the error before the client is notified. This method is specifically useful for connections that only consume messages, as there is no other way to notify the client when its connection fails since the client doesn't make any synchronous method calls.

Specialized Connections

The javax.jms.Connection has specialized sub-interfaces used for different purposes. These specialized sub-interfaces are listed below:

• javax.jms.QueueConnection

  Queue connections are used in PTP messaging. Queue connections are used as factories to create queue sessions as well as other purposes.

• javax.jms.TopicConnection

  Topic connections are used in Pub/Sub messaging. Topic connections are used as factories to create topic sessions as well as other purposes.

• javax.jms.XAQueueConnection

  This interface is used for queue connections that are transacted by definition.

• javax.jms.XATopicConnection

  This interface is used for topic connections that are transacted by definition.

Note 

All the aforementioned interfaces are covered in the appropriate chapter: Chapter 5 for topics.

Connection Metadata

The interface javax.jms.Connection provides access to the metadata of the connection. The metadata information includes the JMS and provider versions and JMS properties supported by the connection. JMS properties are covered in detail in Chapter 3. The metadata for the connection is accessed using the interface javax.jms.ConnectionMetaData. The javax.jms.Connection interface provides the method for accessing the metadata interface:

     public ConnectionMetadata getMetaData() 

This method throws a JMSException if the provider fails to return the metadata due to any internal error.

javax.jms.ConnectionMetaData

javax.jms.ConnectionMetaData interface defines the methods required for accessing the connection's metadata information. The methods defined in this interface are listed below:

Method	Description
public int getJMSMajorVersion()	Returns the major version of JMS
public int getJMSMinorVersion()	Returns the minor version of JMS
public String get JMSProviderName()	Returns the name of the JMS provider
public String getJMSVersion()	Returns the version of JMS
public Enumeration getJMSXPropertyNames()	Returns an enumeration of the JMS properties supported by the connection
public int getProviderMajorVersion()	Returns the major version of JMS provider
public int getJMSProviderMinorVersion()	Returns the minor version of JMS provider
public String getJMSProviderVersion()	Returns the version of JMS provider

For example, if the returned version is 1.2, then the major version is 1 and the minor version is 2. JMS properties are explained in detail in the next chapter.

Obtaining Metadata Example

The code listing below shows a sample application to print the connection metadata with JMQ. We will be accessing the same Administered objects that we set up in the last example:

     import javax.naming.NamingException;     import javax.naming.Context;     import javax.naming.InitialContext;     import java.util.Properties;     import javax.jms.Queue;     import javax.jms.QueueConnectionFactory;     import javax.jms.QueueConnection;     import javax.jms.Topic;     import javax.jms.TopicConnectionFactory;     import javax.jms.TopicConnection;     import javax.jms.JMSException;     import javax.jms.ConnectionMetaData;     import java.util.Enumeration;     public class JMSMetaData {        //Initial context factory        public static final String CTX_FACT =           "com.sun.jndi.fscontext.RefFSContextFactory";        //Provider URL        public static final String PROV_URL = "file:C:\\temp";        //JNDI name for the queue connection factory        public static final String QCF_NAME = "QCFactory";        public static void main(String args[]) throws Exception { 

First, a JNDI initial context is created by specifying the initial context factory and the provider URL:

           //Properties for storing JNDI configuration info           Properties prop = new Properties();           //Add the initial context factory           prop. put (Context.INITIAL_CONTEXT_FACTORY, CTX_FACT);           //Add the provider URL           prop.put(Context.PROVIDER_URL, PROV_URL);           //Create the initial context           Context ctx = new InitialContext(prop); 

The queue connection factory is looked up and a queue connection is created. Then a reference to the queue connection's metadata is obtained:

           QueueConnectionFactory qcf =           (QueueConnectionFactory)ctx.lookup(QCF_NAME);           QueueConnection qConn = qcf.createQueueConnection();           ConnectionMetaData cmd = qConn.getMetaData(); 

Now the metadata for queue connection is printed to the standard output:

           System.out.println("\nJMS Version: " +              cmd.getJMSVersion());           System.out.println("JMS Major Version: " +              cmd.getJMSMajorVersion());           System.out.println("JMS Minor Version: " +              cmd.getJMSMinorVersion());           System.out.println("Provider Name: " +              cmd.getJMSProviderName());           System.out.println("Provider Version: " +              cmd.getProviderVersion());           System.out.println("Provider Major Version: " +              cmd.getProviderMajorVersion());           System.out.println("Provider Minor Version: " +              cmd.getProviderMinorVersion());           System.out.println("Supported JMS properties:");           Enumeration enum = cmd.getJMSXPropertyNames();           while(enum.hasMoreElements()) {              System.out.println("\t" + enum.nextElement());           }           qConn.close();        }     } 

Compiling and running the class listed above using JMQ will produce the output shown below: