com.amazon.sqs.javamessaging

Class SQSConnection

java.lang.Object

com.amazon.sqs.javamessaging.SQSConnection

public class SQSConnection
extends java.lang.Object

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

Methods

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.
ConnectionConsumer	createConnectionConsumer(Destination destination, java.lang.String messageSelector, ServerSessionPool sessionPool, int maxMessages) This method is not supported.
ConnectionConsumer	createConnectionConsumer(Queue queue, java.lang.String messageSelector, ServerSessionPool sessionPool, int maxMessages) This method is not supported.
ConnectionConsumer	createDurableConnectionConsumer(Topic topic, java.lang.String subscriptionName, java.lang.String messageSelector, ServerSessionPool sessionPool, int maxMessages) This method is not supported.
QueueSession	createQueueSession(boolean transacted, int acknowledgeMode) Creates a QueueSession
Session	createSession(boolean transacted, int acknowledgeMode) Creates a Session
AmazonSQS	getAmazonSQSClient() Get the AmazonSQSClient used by this connection.
java.lang.String	getClientID() Gets the client identifier for this connection.
ExceptionListener	getExceptionListener()
ConnectionMetaData	getMetaData() Get the metadata for this connection
AmazonSQSMessagingClientWrapper	getWrappedAmazonSQSClient() Get a wrapped version of the AmazonSQSClient used by this connection.
void	setClientID(java.lang.String clientID) Sets the client identifier for this connection.
void	setExceptionListener(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 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 QueueSession createQueueSession(boolean transacted,
                              int acknowledgeMode)
                                throws JMSException

Creates a QueueSession

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:

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 Session createSession(boolean transacted,
                    int acknowledgeMode)
                      throws JMSException

Creates a Session

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:

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 ExceptionListener getExceptionListener()
                                       throws JMSException

Throws:

JMSException

setExceptionListener

public void setExceptionListener(ExceptionListener listener)
                          throws JMSException

Throws:

JMSException

checkClosing

public void checkClosing()
                  throws java.lang.IllegalStateException

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

Throws:

java.lang.IllegalStateException - If the connection close is in-progress or already completed.

checkClosed

public void checkClosed()
                 throws java.lang.IllegalStateException

Checks if the connection close is already completed.

Throws:

java.lang.IllegalStateException - If the connection close is already completed.

start

public void start()
           throws 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.

Throws:

JMSException - On internal error

stop

public void stop()
          throws 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.

Throws:

java.lang.IllegalStateException - If called by a message listener on its own Connection.

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

close

public void close()
           throws 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.

Throws:

java.lang.IllegalStateException - If called by a message listener on its own Connection.

JMSException - On internal error.

getClientID

public java.lang.String getClientID()
                             throws JMSException

Gets the client identifier for this connection.

Returns:

client identifier

Throws:

JMSException - If the connection is being closed

setClientID

public void setClientID(java.lang.String clientID)
                 throws 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

Parameters:

clientID - The client identifier

Throws:

JMSException - If the connection is being closed

InvalidClientIDException - If empty or null client ID is used

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

getMetaData

public ConnectionMetaData getMetaData()
                               throws JMSException

Get the metadata for this connection

Returns:

the connection metadata

Throws:

JMSException - If the connection is being closed

createConnectionConsumer

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

This method is not supported.

Throws:

JMSException

createDurableConnectionConsumer

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

This method is not supported.

Throws:

JMSException

createConnectionConsumer

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

This method is not supported.

Throws:

JMSException