Package com.amazon.sqs.javamessaging

Class SQSConnection

java.lang.Object
com.amazon.sqs.javamessaging.SQSConnection
All Implemented Interfaces:
jakarta.jms.Connection, jakarta.jms.QueueConnection, AutoCloseable
public class SQSConnection extends Object implements jakarta.jms.Connection, jakarta.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 Details

    • getAmazonSQSClient

      public software.amazon.awssdk.services.sqs.SqsClient 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 SqsClient 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 jakarta.jms.QueueSession createQueueSession(boolean transacted, int acknowledgeMode) throws jakarta.jms.JMSException
      Creates a QueueSession
      Specified by:
      createQueueSession in interface jakarta.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:
      jakarta.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 jakarta.jms.Session createSession(boolean transacted, int acknowledgeMode) throws jakarta.jms.JMSException
      Creates a Session
      Specified by:
      createSession in interface jakarta.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:
      jakarta.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 jakarta.jms.Session createSession(int sessionMode) throws jakarta.jms.JMSException
      Specified by:
      createSession in interface jakarta.jms.Connection
      Throws:
      jakarta.jms.JMSException

    • createSession

      public jakarta.jms.Session createSession() throws jakarta.jms.JMSException
      Specified by:
      createSession in interface jakarta.jms.Connection
      Throws:
      jakarta.jms.JMSException

    • getExceptionListener

      public jakarta.jms.ExceptionListener getExceptionListener() throws jakarta.jms.JMSException
      Specified by:
      getExceptionListener in interface jakarta.jms.Connection
      Throws:
      jakarta.jms.JMSException

    • setExceptionListener

      public void setExceptionListener(jakarta.jms.ExceptionListener listener) throws jakarta.jms.JMSException
      Specified by:
      setExceptionListener in interface jakarta.jms.Connection
      Throws:
      jakarta.jms.JMSException

    • checkClosing

      public void checkClosing() throws jakarta.jms.IllegalStateException
      Checks if the connection close is in-progress or already completed.
      Throws:
      jakarta.jms.IllegalStateException - If the connection close is in-progress or already completed.

    • checkClosed

      public void checkClosed() throws jakarta.jms.IllegalStateException
      Checks if the connection close is already completed.
      Throws:
      jakarta.jms.IllegalStateException - If the connection close is already completed.

    • start

      public void start() throws jakarta.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 jakarta.jms.Connection
      Throws:
      jakarta.jms.JMSException - On internal error

    • stop

      public void stop() throws jakarta.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 received 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 jakarta.jms.Connection
      Throws:
      jakarta.jms.IllegalStateException - If called by a message listener on its own Connection.
      jakarta.jms.JMSException - On internal error or called if close is in progress.

    • close

      public void close() throws jakarta.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 AutoCloseable
      Specified by:
      close in interface jakarta.jms.Connection
      Throws:
      jakarta.jms.IllegalStateException - If called by a message listener on its own Connection.
      jakarta.jms.JMSException - On internal error.

    • getClientID

      public String getClientID() throws jakarta.jms.JMSException
      Gets the client identifier for this connection.
      Specified by:
      getClientID in interface jakarta.jms.Connection
      Returns:
      client identifier
      Throws:
      jakarta.jms.JMSException - If the connection is being closed

    • setClientID

      public void setClientID(String clientID) throws jakarta.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 jakarta.jms.Connection
      Parameters:
      clientID - The client identifier
      Throws:
      jakarta.jms.JMSException - If the connection is being closed
      jakarta.jms.InvalidClientIDException - If empty or null client ID is used
      jakarta.jms.IllegalStateException - If the client ID is already set or attempted to set after an action on the connection already took place

    • getMetaData

      public jakarta.jms.ConnectionMetaData getMetaData() throws jakarta.jms.JMSException
      Get the metadata for this connection
      Specified by:
      getMetaData in interface jakarta.jms.Connection
      Returns:
      the connection metadata
      Throws:
      jakarta.jms.JMSException - If the connection is being closed

    • createConnectionConsumer

      public jakarta.jms.ConnectionConsumer createConnectionConsumer(jakarta.jms.Destination destination, String messageSelector, jakarta.jms.ServerSessionPool sessionPool, int maxMessages) throws jakarta.jms.JMSException
      This method is not supported.
      Specified by:
      createConnectionConsumer in interface jakarta.jms.Connection
      Throws:
      jakarta.jms.JMSException

    • createSharedConnectionConsumer

      public jakarta.jms.ConnectionConsumer createSharedConnectionConsumer(jakarta.jms.Topic topic, String subscriptionName, String messageSelector, jakarta.jms.ServerSessionPool sessionPool, int maxMessages) throws jakarta.jms.JMSException
      Specified by:
      createSharedConnectionConsumer in interface jakarta.jms.Connection
      Throws:
      jakarta.jms.JMSException

    • createDurableConnectionConsumer

      public jakarta.jms.ConnectionConsumer createDurableConnectionConsumer(jakarta.jms.Topic topic, String subscriptionName, String messageSelector, jakarta.jms.ServerSessionPool sessionPool, int maxMessages) throws jakarta.jms.JMSException
      This method is not supported.
      Specified by:
      createDurableConnectionConsumer in interface jakarta.jms.Connection
      Throws:
      jakarta.jms.JMSException

    • createSharedDurableConnectionConsumer

      public jakarta.jms.ConnectionConsumer createSharedDurableConnectionConsumer(jakarta.jms.Topic topic, String subscriptionName, String messageSelector, jakarta.jms.ServerSessionPool sessionPool, int maxMessages) throws jakarta.jms.JMSException
      Specified by:
      createSharedDurableConnectionConsumer in interface jakarta.jms.Connection
      Throws:
      jakarta.jms.JMSException

    • createConnectionConsumer

      public jakarta.jms.ConnectionConsumer createConnectionConsumer(jakarta.jms.Queue queue, String messageSelector, jakarta.jms.ServerSessionPool sessionPool, int maxMessages) throws jakarta.jms.JMSException
      This method is not supported.
      Specified by:
      createConnectionConsumer in interface jakarta.jms.QueueConnection
      Throws:
      jakarta.jms.JMSException