Websphere MQ Everyplace

com.ibm.mqe.jms
Class MQeConnection

java.lang.Object
  |
  +--com.ibm.mqe.jms.MQeConnection
All Implemented Interfaces:
javax.jms.Connection
Direct Known Subclasses:
MQeQueueConnection

public class MQeConnection
extends java.lang.Object
implements javax.jms.Connection

A JMS Connection is a client's active connection to its JMS provider.

Connections support concurrent use.

A JMS client typically creates a Connection; one or more Sessions; and a number of message producers and consumers. When a Connection is created it is in stopped mode. That means that no messages are being delivered. A message producer can send messages while a Connection is stopped.

It is typical to leave the Connection in stopped mode until setup is complete. At that point the Connection's start() method is called and messages begin arriving at the Connection's consumers. This setup convention minimizes any client confusion that may result from asynchronous message delivery while the client is still in the process of setting itself up.A Connection can immediately be started and the setup can be done afterwards. However, clients that do this must be prepared to handle asynchronous message delivery while they are still in the process of setting up.

See Also:
ConnectionFactory, QueueConnection

Constructor Summary
MQeConnection()
           
 
Method Summary
 void close()
          Since a provider typically allocates significant resources outside the JVM on behalf of a Connection, clients should close them when they are not needed.
 javax.jms.Session createSession(boolean transacted, int acknowledgeMode)
          Creates a Session object.
 java.lang.String getClientID()
          Get the client identifier for this connection.
 javax.jms.ExceptionListener getExceptionListener()
          Gets the ExceptionListener object for this connection.
 javax.jms.ConnectionMetaData getMetaData()
          Get the metadata for this connection.
 void setClientID(java.lang.String clientID)
          Set the client identifier for this connection.
 void setExceptionListener(javax.jms.ExceptionListener listener)
          Set an exception listener for this connection.
 void start()
          Start (or restart) a Connection's delivery of incoming messages.
 void stop()
          Used to temporarily stop a Connection's delivery of incoming messages.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MQeConnection

public MQeConnection()
Method Detail

getClientID

public java.lang.String getClientID()
                             throws javax.jms.JMSException
Get the client identifier for this connection.

Specified by:
getClientID in interface javax.jms.Connection
Returns:
the unique client identifier.
Throws:
javax.jms.JMSException - if JMS implementation fails to return the client ID for this Connection due to some internal error.

setClientID

public void setClientID(java.lang.String clientID)
                 throws javax.jms.JMSException
Set the client identifier for this connection.

The purpose of client identifier is to associate a session and its objects with a state maintained on behalf of the client by a provider. The only such state identified by JMS is that required to support durable subscriptions, and the clientId is ignored for point-to-point connections.

Specified by:
setClientID in interface javax.jms.Connection
Parameters:
clientID - the unique client identifier
Throws:
javax.jms.JMSException - general exception if JMS implementation fails to set the client ID for this Connection due to some internal error.
javax.jms.InvalidClientIDException - if JMS client specifies an invalid or duplicate client id.

getMetaData

public javax.jms.ConnectionMetaData getMetaData()
                                         throws javax.jms.JMSException
Get the metadata for this connection.

Specified by:
getMetaData in interface javax.jms.Connection
Returns:
the connection metadata.
Throws:
javax.jms.JMSException - general exception if JMS implementation fails to get the Connection meta-data for this Connection.
See Also:
ConnectionMetaData

setExceptionListener

public void setExceptionListener(javax.jms.ExceptionListener listener)
                          throws javax.jms.JMSException
Set an exception listener for this connection.

Specified by:
setExceptionListener in interface javax.jms.Connection
Parameters:
listener - the exception listener.
Throws:
javax.jms.JMSException - general exception if JMS implementation fails to set the Exception listener for this Connection.

getExceptionListener

public javax.jms.ExceptionListener getExceptionListener()
                                                 throws javax.jms.JMSException
Gets the ExceptionListener object for this connection.

Specified by:
getExceptionListener in interface javax.jms.Connection
Returns:
the ExceptionListener for this connection
Throws:
javax.jms.JMSException - if the JMS provider fails to get the ExceptionListener for this connection.

start

public void start()
           throws javax.jms.JMSException
Start (or restart) a Connection's delivery of incoming messages. Restart begins with the oldest unacknowledged message. Starting a started session is ignored.

Specified by:
start in interface javax.jms.Connection
Throws:
javax.jms.JMSException - if JMS implementation fails to start the message delivery due to some internal error.
See Also:
Connection.stop()

stop

public void stop()
          throws javax.jms.JMSException
Used to temporarily stop a Connection's delivery of incoming messages. It can be restarted using its start() method. When stopped, delivery to all the Connection's message consumers is inhibited: synchronous receive's block and messages are not delivered to message listeners.

Stopping a Session has no affect on its ability to send messages. Stopping a stopped session is ignored.

Specified by:
stop in interface javax.jms.Connection
Throws:
javax.jms.JMSException - if JMS implementation fails to stop the message delivery due to some internal error.
See Also:
Connection.start()

close

public void close()
           throws javax.jms.JMSException
Since a provider typically allocates significant resources outside the JVM on behalf of a Connection, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

Closing a connection causes any of it's sessions' in-process transactions to be rolled back.

This method should not be invoked from within javax.jms.MessageListener#onMessage().

Specified by:
close in interface javax.jms.Connection
Throws:
javax.jms.JMSException - if JMS implementation fails to close the connection due to internal error. For example, a failure to release resources or to close socket connection can lead to throwing of this exception.

createSession

public javax.jms.Session createSession(boolean transacted,
                                       int acknowledgeMode)
                                throws javax.jms.JMSException
Creates a Session object.

Parameters:
transacted - indicates whether the session is transacted
acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives; ignored if the session is transacted. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE.
Returns:
a newly created session
Throws:
javax.jms.JMSException - if the Connection object fails to create a session due an internal error
Since:
1.1
See Also:
Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

Websphere MQ Everyplace