org.exolab.jms.client
Class JmsXAQueueConnection

java.lang.Object
  |
  +--org.exolab.jms.client.JmsConnection
        |
        +--org.exolab.jms.client.JmsQueueConnection
              |
              +--org.exolab.jms.client.JmsXAQueueConnection

All Implemented Interfaces:

javax.jms.Connection, javax.jms.QueueConnection, javax.jms.XAConnection, javax.jms.XAQueueConnection

public class JmsXAQueueConnection

extends org.exolab.jms.client.JmsQueueConnection

implements javax.jms.XAQueueConnection

Client implementation of the javax.jms.XAQueueConnection interface.

Version:

$Revision: 1.2 $ $Date: 2005/03/18 03:36:37 $

Author:

Jim Alateras, Tim Anderson

Constructor Summary

JmsXAQueueConnection(JmsXAConnectionFactory factory, java.lang.String id, java.lang.String username, java.lang.String password)
Construct a new JmsXAQueueConnection.

Method Summary

protected void	addSession(org.exolab.jms.client.JmsSession session) Add the specified session to the list of managed sessions.
void	close() Closes the connection.
javax.jms.ConnectionConsumer	createConnectionConsumer(javax.jms.Destination destination, java.lang.String messageSelector, javax.jms.ServerSessionPool sessionPool, int maxMessages) Creates a connection consumer for this connection (optional operation).
javax.jms.ConnectionConsumer	createConnectionConsumer(javax.jms.Queue queue, java.lang.String selector, javax.jms.ServerSessionPool pool, int maxMessages) Create a connection consumer for this connection
javax.jms.ConnectionConsumer	createDurableConnectionConsumer(javax.jms.Topic topic, java.lang.String subscriptionName, java.lang.String messageSelector, javax.jms.ServerSessionPool sessionPool, int maxMessages) This implementation always throws IllegalStateException, as per section 4.11 of the JMS specification.
javax.jms.QueueSession	createQueueSession(boolean transacted, int acknowledgeMode) Creates an XAQueueSession object.
javax.jms.Session	createSession(boolean transacted, int acknowledgeMode) Creates a Session object.
javax.jms.XAQueueSession	createXAQueueSession() Creates an XAQueueSession object.
javax.jms.XASession	createXASession() Creates an XASession object.
protected void	deleteTemporaryDestination(JmsDestination destination) Delete the temporary destination and all the registered sessions consumers waiting to receive messages from this destination will be stopped.
protected void	ensureOpen() Verifies that the connection is open.
java.lang.String	getClientID() Gets the client identifier for this connection.
long	getConnectionId() Returns the connection identifier.
javax.jms.ExceptionListener	getExceptionListener() Returns the ExceptionListener for this connection.
javax.jms.ConnectionMetaData	getMetaData() Returns the metadata for this connection.
protected ServerConnection	getServerConnection() Returns the server connection.
protected boolean	isStopped() Returns the running state of the connection.
void	notifyExceptionListener(javax.jms.JMSException message) Notify the exception listener of a JMSException.
protected void	removeSession(org.exolab.jms.client.JmsSession session) Remove the specified session from the list of managed sessions.
void	setClientID(java.lang.String clientID) Sets the client identifier for this connection.
void	setExceptionListener(javax.jms.ExceptionListener listener) Sets an exception listener for this connection.
protected void	setModified() Flags this connection as being modified.
void	start() Starts (or restarts) a connection's delivery of incoming messages.
void	stop() Temporarily stops 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

Methods inherited from interface javax.jms.XAConnection

createSession

Methods inherited from interface javax.jms.Connection

close, createConnectionConsumer, createDurableConnectionConsumer, getClientID, getExceptionListener, getMetaData, setClientID, setExceptionListener, start, stop

Methods inherited from interface javax.jms.QueueConnection

createConnectionConsumer

Constructor Detail

JmsXAQueueConnection

public JmsXAQueueConnection(JmsXAConnectionFactory factory,
                            java.lang.String id,
                            java.lang.String username,
                            java.lang.String password)
                     throws javax.jms.JMSException

Construct a new JmsXAQueueConnection.

Parameters:

factory - factory creating this object

id - the connection identifier

username - client username

password - client password

Throws:

javax.jms.JMSException - if there is any problem creating this object

Method Detail

createXASession

public javax.jms.XASession createXASession()
                                    throws javax.jms.JMSException

Creates an XASession object.

Specified by:

createXASession in interface javax.jms.XAConnection

Returns:

a newly created XASession

Throws:

javax.jms.JMSException - if the XAConnection object fails to create an XASession due to some internal error.

createXAQueueSession

public javax.jms.XAQueueSession createXAQueueSession()
                                              throws javax.jms.JMSException

Creates an XAQueueSession object.

Specified by:

createXAQueueSession in interface javax.jms.XAQueueConnection

Returns:

a newly created XAQueueSession

Throws:

javax.jms.JMSException - if the XAQueueConnection object fails to create an XA queue session due to some internal error.

createQueueSession

public javax.jms.QueueSession createQueueSession(boolean transacted,
                                                 int acknowledgeMode)
                                          throws javax.jms.JMSException

Creates an XAQueueSession object.

Specified by:

createQueueSession in interface javax.jms.XAQueueConnection

Overrides:

createQueueSession in class org.exolab.jms.client.JmsQueueConnection

Parameters:

transacted - usage undefined

acknowledgeMode - usage undefined

Returns:

a newly created XAQueueSession

Throws:

javax.jms.JMSException - if the XAQueueConnection object fails to create an XA queue session due to some internal error.

createConnectionConsumer

public javax.jms.ConnectionConsumer createConnectionConsumer(javax.jms.Queue queue,
                                                             java.lang.String selector,
                                                             javax.jms.ServerSessionPool pool,
                                                             int maxMessages)
                                                      throws javax.jms.JMSException

Create a connection consumer for this connection

Specified by:

createConnectionConsumer in interface javax.jms.QueueConnection

Parameters:

queue - the queue to access

selector - the message selector. May be null

pool - the server session pool to associate with the consumer

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

Returns:

the new connection consumer

Throws:

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

javax.jms.JMSException - if the connection consumer cannot be created

createDurableConnectionConsumer

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

This implementation always throws IllegalStateException, as per section 4.11 of the JMS specification.

Specified by:

createDurableConnectionConsumer in interface javax.jms.Connection

Overrides:

createDurableConnectionConsumer in class org.exolab.jms.client.JmsConnection

Throws:

java.lang.IllegalStateException - if invoked

getConnectionId

public long getConnectionId()

Returns the connection identifier.

Returns:

the connection identifier

getClientID

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

Gets the client identifier for this connection.

Specified by:

getClientID in interface javax.jms.Connection

Returns:

the unique client identifier

Throws:

javax.jms.JMSException - if the JMS provider 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

Sets the client identifier for this connection.

Specified by:

setClientID in interface javax.jms.Connection

Parameters:

clientID - the unique client identifier

Throws:

javax.jms.JMSException - if the JMS provider fails to set the client ID for this connection due to some internal error.

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

javax.jms.IllegalStateException - if the JMS client attempts to set a connection's client ID at the wrong time or when it has been administratively configured.

getMetaData

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

Returns the metadata for this connection.

Specified by:

getMetaData in interface javax.jms.Connection

Returns:

the connection metadata

Throws:

javax.jms.JMSException - if the JMS provider fails to get the connection metadata for this connection.

getExceptionListener

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

Returns the ExceptionListener for this connection.

Specified by:

getExceptionListener in interface javax.jms.Connection

Returns:

the ExceptionListener for this connection, or null if none is associated with this connection.

Throws:

javax.jms.JMSException - if the JMS provider fails to get the ExceptionListener for this connection.

setExceptionListener

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

Sets an exception listener for this connection.

Specified by:

setExceptionListener in interface javax.jms.Connection

Parameters:

listener - the exception listener

Throws:

javax.jms.JMSException - if the JMS provider fails to set the exception listener for this connection.

notifyExceptionListener

public void notifyExceptionListener(javax.jms.JMSException message)

Notify the exception listener of a JMSException. If the exception listener is not set then ignore it.

Parameters:

message - message to deliver

start

public void start()
           throws javax.jms.JMSException

Starts (or restarts) a connection's delivery of incoming messages. A call to start on a connection that has already been started is ignored.

Specified by:

start in interface javax.jms.Connection

Throws:

javax.jms.JMSException - if the JMS provider fails to start message delivery due to some internal error.

stop

public void stop()
          throws javax.jms.JMSException

Temporarily stops a connection's delivery of incoming messages. Delivery can be restarted using the connection's start method. When the connection is stopped, delivery to all the connection's message consumers is inhibited: synchronous receives block, and messages are not delivered to message listeners.

This call blocks until receives and/or message listeners in progress have completed.

Stopping a connection has no effect on its ability to send messages. A call to stop on a connection that has already been stopped is ignored.

Specified by:

stop in interface javax.jms.Connection

Throws:

javax.jms.JMSException - if the JMS provider fails to stop message delivery due to some internal error.

close

public void close()
           throws javax.jms.JMSException

Closes the connection.

When this method is invoked, it should not return until message processing has been shut down in an orderly fashion. This means that all message listeners that may have been running have returned, and that all pending receives have returned. A close terminates all pending message receives on the connection's sessions' consumers. The receives may return with a message or with null, depending on whether there was a message available at the time of the close. If one or more of the connection's sessions' message listeners is processing a message at the time when connection close is invoked, all the facilities of the connection and its sessions must remain available to those listeners until they return control to the JMS provider.

Closing a connection causes any of its sessions' transactions in progress to be rolled back. In the case where a session's work is coordinated by an external transaction manager, a session's commit and rollback methods are not used and the result of a closed session's work is determined later by the transaction manager.

Closing a connection does NOT force an acknowledgment of client-acknowledged sessions.

Invoking the acknowledge method of a received message from a closed connection's session must throw an IllegalStateException. Closing a closed connection must NOT throw an exception.

Specified by:

close in interface javax.jms.Connection

Throws:

javax.jms.JMSException - if the JMS provider fails to close the connection due to some internal error.

createSession

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

Creates a Session object.

Specified by:

createSession in interface javax.jms.Connection

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 to some internal error or lack of support for the specific transaction and acknowledgement mode.

See Also:

Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE

createConnectionConsumer

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

Creates a connection consumer for this connection (optional operation). This is an expert facility not used by regular JMS clients.

Specified by:

createConnectionConsumer in interface javax.jms.Connection

Parameters:

destination - the destination to access

messageSelector - 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.

sessionPool - 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 object fails to create a connection consumer due to some internal error or invalid arguments for sessionPool and messageSelector.

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

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

getServerConnection

protected ServerConnection getServerConnection()
                                        throws javax.jms.JMSException

Returns the server connection.

Returns:

the server connection

Throws:

javax.jms.JMSException - if the connection is null

addSession

protected void addSession(org.exolab.jms.client.JmsSession session)

Add the specified session to the list of managed sessions.

Parameters:

session - session to register

removeSession

protected void removeSession(org.exolab.jms.client.JmsSession session)

Remove the specified session from the list of managed sessions. If it doesn't exist then fail silently.

Parameters:

session - session to remove

isStopped

protected boolean isStopped()

Returns the running state of the connection.

Returns:

true if stopped

setModified

protected void setModified()

Flags this connection as being modified. Subsequent attempts to invoke JmsConnection.setClientID(java.lang.String) will result in an IllegalStateException being thrown.

deleteTemporaryDestination

protected void deleteTemporaryDestination(JmsDestination destination)
                                   throws javax.jms.JMSException

Delete the temporary destination and all the registered sessions consumers waiting to receive messages from this destination will be stopped.

It will throw a JMSException if the specified destination is not temporary or if the destination is null or if the destination is not owned by this connection

Parameters:

destination - temporary destination to delete

Throws:

javax.jms.JMSException -

ensureOpen

protected void ensureOpen()
                   throws javax.jms.IllegalStateException

Verifies that the connection is open.

Throws:

javax.jms.IllegalStateException - if the connection is closed