com.amazon.sqs.javamessaging

Class SQSConnection

java.lang.Object

com.amazon.sqs.javamessaging.SQSConnection

All Implemented Interfaces:

javax.jms.Connection, javax.jms.QueueConnection

public class SQSConnection
extends Object
implements javax.jms.Connection, javax.jms.QueueConnection

This is a logical connection entity, which encapsulates the logic to create sessions.

Supports concurrent use, but the session objects it creates do no support concurrent use.

The authentication does not take place with the creation of connection. It takes place when the amazonSQSClient is used to call any SQS API.

The physical connections are handled by the underlying amazonSQSClient.

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, but message producer can send messages while a connection is stopped.

Although the connection can be started immediately, it is typical to leave the connection in stopped mode until setup is complete (that is, until all message consumers have been created). At that point, the client calls the connection's start method, 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 be started immediately, and the setup can be done afterwards. Clients that do this must be prepared to handle asynchronous message delivery while they are still in the process of setting up.

Transacted sessions are not supported.

Exception listener on connection is not supported.

Method Summary

Modifier and Type	Method and Description
void	checkClosed() Checks if the connection close is already completed.
void	checkClosing() Checks if the connection close is in-progress or already completed.
void	close() Closes the connection.
javax.jms.ConnectionConsumer	createConnectionConsumer(javax.jms.Destination destination, String messageSelector, javax.jms.ServerSessionPool sessionPool, int maxMessages) This method is not supported.
javax.jms.ConnectionConsumer	createConnectionConsumer(javax.jms.Queue queue, String messageSelector, javax.jms.ServerSessionPool sessionPool, int maxMessages) This method is not supported.
javax.jms.ConnectionConsumer	createDurableConnectionConsumer(javax.jms.Topic topic, String subscriptionName, String messageSelector, javax.jms.ServerSessionPool sessionPool, int maxMessages) This method is not supported.
javax.jms.QueueSession	createQueueSession(boolean transacted, int acknowledgeMode) Creates a QueueSession
javax.jms.Session	createSession(boolean transacted, int acknowledgeMode) Creates a Session
com.amazonaws.services.sqs.AmazonSQS	getAmazonSQSClient() Get the AmazonSQSClient used by this connection.
String	getClientID() Gets the client identifier for this connection.
javax.jms.ExceptionListener	getExceptionListener()
javax.jms.ConnectionMetaData	getMetaData() Get the metadata for this connection
AmazonSQSMessagingClientWrapper	getWrappedAmazonSQSClient() Get a wrapped version of the AmazonSQSClient used by this connection.
void	setClientID(String clientID) Sets the client identifier for this connection.
void	setExceptionListener(javax.jms.ExceptionListener listener)
void	start() Starts a connection's delivery of incoming messages.
void	stop() 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

Method Detail

getAmazonSQSClient

public com.amazonaws.services.sqs.AmazonSQS getAmazonSQSClient()

Get the AmazonSQSClient used by this connection. This can be used to do administrative operations that aren't included in the JMS specification, e.g. creating new queues.

Returns:

the AmazonSQSClient used by this connection

getWrappedAmazonSQSClient

public AmazonSQSMessagingClientWrapper getWrappedAmazonSQSClient()

Get a wrapped version of the AmazonSQSClient used by this connection. The wrapper transforms all exceptions from the client into JMSExceptions so that it can more easily be used by existing code that already expects JMSExceptions. This client can be used to do administrative operations that aren't included in the JMS specification, e.g. creating new queues.

Returns:

wrapped version of the AmazonSQSClient used by this connection

createQueueSession

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

Creates a QueueSession

Specified by:

createQueueSession in interface javax.jms.QueueConnection

Parameters:

transacted - Only false is supported.

acknowledgeMode - Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE, and SQSSession.UNORDERED_ACKNOWLEDGE

Returns:

a new queue session.

Throws:

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

createSession

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

Creates a Session

Specified by:

createSession in interface javax.jms.Connection

Parameters:

transacted - Only false is supported.

acknowledgeMode - Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE, and SQSSession.UNORDERED_ACKNOWLEDGE

Returns:

a new session.

Throws:

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

getExceptionListener

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

Specified by:

getExceptionListener in interface javax.jms.Connection

Throws:

javax.jms.JMSException

setExceptionListener

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

Specified by:

setExceptionListener in interface javax.jms.Connection

Throws:

javax.jms.JMSException

checkClosing

public void checkClosing()
                  throws javax.jms.IllegalStateException

Checks if the connection close is in-progress or already completed.

Throws:

javax.jms.IllegalStateException - If the connection close is in-progress or already completed.

checkClosed

public void checkClosed()
                 throws javax.jms.IllegalStateException

Checks if the connection close is already completed.

Throws:

javax.jms.IllegalStateException - If the connection close is already completed.

start

public void start()
           throws javax.jms.JMSException

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

This will not return until all the sessions start internally.

Specified by:

start in interface javax.jms.Connection

Throws:

javax.jms.JMSException - On internal error

stop

public void stop()
          throws javax.jms.JMSException

Stops a connection's delivery of incoming messages. A call to stop on a connection that has already been stopped is ignored.

This will not return until all the sessions stop internally, which blocks until receives and/or message listeners in progress have completed. While these message listeners are completing, they must have the full services of the connection available to them.

A call to stop must not return until delivery of messages has paused. This means that a client can rely on the fact that none of its message listeners will be called and that all threads of control waiting for receive calls to return will not return with a message until the connection is restarted. The receive timers for a stopped connection continue to advance, so receives may time out while the connection is stopped.

A message listener must not attempt to stop its own connection; otherwise throws a IllegalStateException.

Specified by:

stop in interface javax.jms.Connection

Throws:

javax.jms.IllegalStateException - If called by a message listener on its own Connection.

javax.jms.JMSException - On internal error or called if close is in progress.

close

public void close()
           throws javax.jms.JMSException

Closes the connection.

This will not return until all the sessions close internally, which blocks until receives and/or message listeners in progress have completed.

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.

A message listener must not attempt to close its own connection; otherwise throws a IllegalStateException.

Specified by:

close in interface javax.jms.Connection

Throws:

javax.jms.IllegalStateException - If called by a message listener on its own Connection.

javax.jms.JMSException - On internal error.

getClientID

public String getClientID()
                   throws javax.jms.JMSException

Gets the client identifier for this connection.

Specified by:

getClientID in interface javax.jms.Connection

Returns:

client identifier

Throws:

javax.jms.JMSException - If the connection is being closed

setClientID

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

Sets the client identifier for this connection.

Does not verify uniqueness of client ID, so does not detect if another connection is already using the same client ID

Specified by:

setClientID in interface javax.jms.Connection

Parameters:

clientID - The client identifier

Throws:

javax.jms.JMSException - If the connection is being closed

javax.jms.InvalidClientIDException - If empty or null client ID is used

javax.jms.IllegalStateException - If the client ID is already set or attempted to set after an action on the connection already took place

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 - If the connection is being closed

createConnectionConsumer

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

This method is not supported.

Specified by:

createConnectionConsumer in interface javax.jms.Connection

Throws:

javax.jms.JMSException

createDurableConnectionConsumer

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

This method is not supported.

Specified by:

createDurableConnectionConsumer in interface javax.jms.Connection

Throws:

javax.jms.JMSException

createConnectionConsumer

public javax.jms.ConnectionConsumer createConnectionConsumer(javax.jms.Queue queue,
                                                             String messageSelector,
                                                             javax.jms.ServerSessionPool sessionPool,
                                                             int maxMessages)
                                                      throws javax.jms.JMSException

This method is not supported.

Specified by:

createConnectionConsumer in interface javax.jms.QueueConnection

Throws:

javax.jms.JMSException