com.ibm.mq.jms

Class MQConnection

java.lang.Object

com.ibm.mq.jms.MQRoot

com.ibm.mq.jms.MQConnection

All Implemented Interfaces:

JmsConnection, JmsPropertyContext, JmsReadablePropertyContext, java.io.Serializable, java.lang.AutoCloseable, java.util.Map<java.lang.String,java.lang.Object>, javax.jms.Connection

Direct Known Subclasses:

MQQueueConnection, MQTopicConnection, MQXAConnection

public class MQConnection
extends MQRoot
implements javax.jms.Connection, JmsConnection

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

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Method Summary

Modifier and Type	Method and Description
void	close() Moves the connection into the closed state.
javax.jms.ConnectionConsumer	createConnectionConsumer(javax.jms.Destination destination, java.lang.String selector, javax.jms.ServerSessionPool ssp, int maxMessages) Creates a connection consumer for this connection.
javax.jms.ConnectionConsumer	createDurableConnectionConsumer(javax.jms.Topic topic, java.lang.String subName, java.lang.String selector, javax.jms.ServerSessionPool ssp, int maxMessageCount) Creates a durable connection consumer for this connection.
javax.jms.Session	createSession() Creates a Session object, specifying no arguments.
javax.jms.Session	createSession(boolean transacted, int acknowledgeMode) Creates a Session object.
javax.jms.Session	createSession(int sessionMode) Creates a Session object, specifying a sessionMode.
javax.jms.ConnectionConsumer	createSharedConnectionConsumer(javax.jms.Topic topic, java.lang.String subscriptionName, java.lang.String messageSelector, javax.jms.ServerSessionPool sessionPool, int maxMessages)
javax.jms.ConnectionConsumer	createSharedDurableConnectionConsumer(javax.jms.Topic topic, java.lang.String subName, java.lang.String selector, javax.jms.ServerSessionPool sessionPool, int maxMessages)
java.lang.String	getClientID() Gets the client ID for this connection.
javax.jms.ExceptionListener	getExceptionListener() Gets the exception listener for this connection.
javax.jms.ConnectionMetaData	getMetaData() Gets the meta data for this connection.
void	setClientID(java.lang.String clientID) Sets the client ID for this connection.
void	setExceptionListener(javax.jms.ExceptionListener listener) Sets an exception listener for this connection.
void	start() Start or restart delivering incoming messages.
void	stop() Temporarily stops a connection's delivery of incoming messages.
java.lang.String	toString() Represent key information about the Connection, in JSON form ObjectId As a className and hexadecimal identifier ConnectionId In hexadecimal form ConnectionMode As specified at connection time Host Only applicable for client connections, but may be shown for bindings Port Only applicable for client connections, but may be shown for bindings QueueManager As specified at connection time ResolvedQueueManager Possibly different to QueueManager if a CCDT was used

Methods inherited from class com.ibm.mq.jms.MQRoot

clear, containsKey, containsValue, entrySet, equals, get, getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty, getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, hashCode, isEmpty, keySet, propertyExists, put, putAll, remove, setBatchProperties, setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty, setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty, setObjectProperty, setShortProperty, setStringProperty, size, values

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.ibm.msg.client.jms.JmsPropertyContext

setBatchProperties, setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty, setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty, setObjectProperty, setShortProperty, setStringProperty, toJson

Methods inherited from interface com.ibm.msg.client.jms.JmsReadablePropertyContext

getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty, getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, propertyExists, stringifyMe

Methods inherited from interface java.util.Map

clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values

Method Detail

close

public void close()
           throws javax.jms.JMSException

Moves the connection into the closed state.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface javax.jms.Connection

Throws:

javax.jms.JMSException - if the connection cannot be closed.

createConnectionConsumer

public javax.jms.ConnectionConsumer createConnectionConsumer(javax.jms.Destination destination,
                                                             java.lang.String selector,
                                                             javax.jms.ServerSessionPool ssp,
                                                             int maxMessages)
                                                      throws javax.jms.JMSException

Creates a connection consumer for this connection. This facility is only used by advanced JMS clients.

Specified by:

createConnectionConsumer in interface javax.jms.Connection

Parameters:

destination - the destination to access

selector - only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.

ssp - the server session pool to associate with this connection consumer

maxMessages - the maximum number of messages that can be assigned to a server session at one time

Returns:

the connection consumer.

Throws:

javax.jms.JMSException - if the connection fails to create a connection consumer due to some internal error or invalid arguments.

javax.jms.InvalidDestinationException - if an invalid destination is specified.

javax.jms.InvalidSelectorException - if the message selector is invalid. *

See Also:

Connection.createConnectionConsumer(javax.jms.Destination, java.lang.String, javax.jms.ServerSessionPool, int)

createDurableConnectionConsumer

public javax.jms.ConnectionConsumer createDurableConnectionConsumer(javax.jms.Topic topic,
                                                                    java.lang.String subName,
                                                                    java.lang.String selector,
                                                                    javax.jms.ServerSessionPool ssp,
                                                                    int maxMessageCount)
                                                             throws javax.jms.JMSException

Creates a durable connection consumer for this connection. This facility is only used by advanced JMS clients.

Specified by:

createDurableConnectionConsumer in interface javax.jms.Connection

Parameters:

topic - the topic to be accessed.

subName - the name of the durable subscription.

selector - delivers only those messages with properties that match the message selector expression. A value of null or an empty string indicates that there is no message selector for the message consumer.

ssp - the server session pool to associate with this connection consumer.

maxMessageCount - the maximum number of messages that can be assigned to a server session at one time.

Returns:

the connection consumer.

Throws:

javax.jms.JMSException - if JMS Connection fails to create a durable connection consumer due to some internal error or invalid arguments for sessionPool and message selector.

javax.jms.InvalidSelectorException - if the message selector is invalid.

See Also:

ConnectionConsumer

createSession

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

Creates a Session object. This method has been superseded by the method createSession(int) which specifies the same information using a single argument, and by the method createSession() which is for use in a Java EE JTA transaction. Applications should consider using those methods instead of this one.

Specified by:

createSession in interface javax.jms.Connection

Parameters:

transacted - true indicates that the session is transacted.

acknowledgeMode - indicates whether the consumer or the client acknowledges any messages it receives. Possible values are:

• Session.AUTO_ACKNOWLEDGE
• Session.CLIENT_ACKNOWLEDGE
• Session.DUPS_OK_ACKNOWLEDGE

See the JMS specification for details of these values. acknowledgeMode is ignored if the session is transacted.

Returns:

a newly created session.

Throws:

javax.jms.JMSException - if the Connection object fails to create a session due to some internal error or lack of support for the specific transaction and acknowledgement mode.

getClientID

public java.lang.String getClientID()
                             throws javax.jms.JMSException

Gets the client ID for this connection.

Specified by:

getClientID in interface javax.jms.Connection

Returns:

the unique client identifier.

Throws:

javax.jms.JMSException - if the JMS implementation fails to return the client ID for this connection due to an internal error.

getExceptionListener

public javax.jms.ExceptionListener getExceptionListener()
                                                 throws javax.jms.JMSException

Gets the exception listener for this connection. A connection's exception listener receives a JMSException if there is an unrecoverable problem with the connection to IBM MQ.

Specified by:

getExceptionListener in interface javax.jms.Connection

Returns:

the exception listener.

Throws:

javax.jms.JMSException

See Also:

ExceptionListener

getMetaData

public javax.jms.ConnectionMetaData getMetaData()
                                         throws javax.jms.JMSException

Gets the meta data for this connection.

Specified by:

getMetaData in interface javax.jms.Connection

Returns:

the connection meta data.

Throws:

javax.jms.JMSException - general exception if the JMS implementation fails to get the connection meta-data for this connection.

setClientID

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

Sets the client ID for this connection.

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 an internal error.

javax.jms.InvalidClientIDException - if the JMS client specifies an invalid or duplicate client ID.

setExceptionListener

public void setExceptionListener(javax.jms.ExceptionListener listener)
                          throws javax.jms.JMSException

Sets an exception listener for this connection. A connection's ExceptionListener receives a JMSException if there is an unrecoverable problem with the connection to IBM MQ. To remove an ExceptionListener, call this method passing in a null value

Specified by:

setExceptionListener in interface javax.jms.Connection

Parameters:

listener - the exception listener.

Throws:

javax.jms.JMSException

See Also:

ExceptionListener

start

public void start()
           throws javax.jms.JMSException

Start or restart delivering incoming messages.

Specified by:

start in interface javax.jms.Connection

Throws:

javax.jms.JMSException

stop

public void stop()
          throws javax.jms.JMSException

Temporarily stops a connection's delivery of incoming messages. It can be restarted with the start() method. When it is stopped, it inhibits delivery to all its message consumers. Synchronous receives are blocked, and messages are not delivered to message listeners. Stopping a session has no affect on its ability to send messages. Stopping a session that is already stopped has no effect.

Specified by:

stop in interface javax.jms.Connection

Throws:

javax.jms.JMSException - if the JMS implementation fails to stop the message delivery because of an internal error.

toString

public java.lang.String toString()

Represent key information about the Connection, in JSON form

ObjectId

As a className and hexadecimal identifier

ConnectionId

In hexadecimal form

ConnectionMode

As specified at connection time

Host

Only applicable for client connections, but may be shown for bindings

Port

Only applicable for client connections, but may be shown for bindings

QueueManager

As specified at connection time

ResolvedQueueManager

Possibly different to QueueManager if a CCDT was used

Overrides:

toString in class java.lang.Object

Returns:

String representation of the connection

createSession

public javax.jms.Session createSession()
                                throws javax.jms.JMSException

Creates a Session object, specifying no arguments. In a Java SE environment, or in a Java EE web of EJB container when there is no active JTA transaction in progress, the created Session will be non-transacted and have an acknowledge mode of Session.AUTO_ACKNOWLEDGE In a Java EE web or EJB container when there is an active JTA transaction in progress, the created session will participate in the JTA transaction and be committed or rolled back when that transaction is committe dor rolled back.

Specified by:

createSession in interface javax.jms.Connection

Returns:

a newly created session.

Throws:

javax.jms.JMSException - if the Connection object fails to create a session due to some internal error or because this method is being called in a Java EE web or EJB application and an active session already exists for this connection.

createSession

public javax.jms.Session createSession(int sessionMode)
                                throws javax.jms.JMSException

Creates a Session object, specifying a sessionMode.

Specified by:

createSession in interface javax.jms.Connection

Parameters:

sessionMode - - indicates how messages will be committed or acknowledged. In a Java SE environment, or in a Java EE client container, this must be one of the following:

• Session.SESSION_TRANSACTED
• Session.AUTO_ACKNOWLEDGE
• Session.CLIENT_ACKNOWLEDGE
• Session.DUPS_OK_ACKNOWLEDGE

In a Java EE web or EJB container, this value is ignored when there is an active JTA transaction in progress. If there is no active JTA transaction then only Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE are allowed See the JMS specification for details of these values.

Returns:

a newly created session.

Throws:

javax.jms.JMSException - if the Connection object fails to create a session due to some internal error or lack of support for the specific session mode.

createSharedConnectionConsumer

public javax.jms.ConnectionConsumer createSharedConnectionConsumer(javax.jms.Topic topic,
                                                                   java.lang.String subscriptionName,
                                                                   java.lang.String messageSelector,
                                                                   javax.jms.ServerSessionPool sessionPool,
                                                                   int maxMessages)
                                                            throws javax.jms.IllegalStateException,
                                                                   javax.jms.InvalidDestinationException,
                                                                   javax.jms.InvalidSelectorException,
                                                                   javax.jms.JMSException

Specified by:

createSharedConnectionConsumer in interface javax.jms.Connection

Throws:

javax.jms.IllegalStateException

javax.jms.InvalidDestinationException

javax.jms.InvalidSelectorException

javax.jms.JMSException

See Also:

Connection.createSharedConnectionConsumer(javax.jms.Topic, java.lang.String, java.lang.String, javax.jms.ServerSessionPool, int)

createSharedDurableConnectionConsumer

public javax.jms.ConnectionConsumer createSharedDurableConnectionConsumer(javax.jms.Topic topic,
                                                                          java.lang.String subName,
                                                                          java.lang.String selector,
                                                                          javax.jms.ServerSessionPool sessionPool,
                                                                          int maxMessages)
                                                                   throws javax.jms.IllegalStateException,
                                                                          javax.jms.InvalidDestinationException,
                                                                          javax.jms.InvalidSelectorException,
                                                                          javax.jms.JMSException

Specified by:

createSharedDurableConnectionConsumer in interface javax.jms.Connection

Throws:

javax.jms.IllegalStateException

javax.jms.InvalidDestinationException

javax.jms.InvalidSelectorException

javax.jms.JMSException

See Also:

Connection.createSharedDurableConnectionConsumer(javax.jms.Topic, java.lang.String, java.lang.String, javax.jms.ServerSessionPool, int)