Package org.apache.qpid.protonj2.client.impl

Class ClientSession

  • All Implemented Interfaces:
    java.lang.AutoCloseable, Session
    Direct Known Subclasses:
    ClientStreamSession
    public class ClientSession
extends java.lang.Object
implements Session
    Client implementation of the Session API.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Session beginTransaction()
      Opens a new transaction scoped to this Session if one is not already active.
      protected void checkClosedOrFailed()  
      ClientInstance client()  
      void close()
      Requests a close of the Session at the remote and waits until the Session has been fully closed or until the configured SessionOptions.closeTimeout() is exceeded.
      void close​(ErrorCondition error)
      Requests a close of the Session at the remote and waits until the Session has been fully closed or until the configured SessionOptions.closeTimeout() is exceeded.
      java.util.concurrent.Future<Session> closeAsync()
      Requests a close of the Session at the remote and returns a Future that will be completed once the session has been remotely closed or an error occurs.
      java.util.concurrent.Future<Session> closeAsync​(ErrorCondition error)
      Requests a close of the Session at the remote and returns a Future that will be completed once the session has been remotely closed or an error occurs.
      Session commitTransaction()
      Commit the currently active transaction in this Session.
      ClientConnection connection()  
      java.lang.String[] desiredCapabilities()
      Returns the desired capabilities that the remote provided upon successfully opening the Session.
      Receiver nextReceiver()
      Waits indefinitely for a receiver created from this session to have a delivery ready for receipt.
      Receiver nextReceiver​(long timeout, java.util.concurrent.TimeUnit unit)
      Waits for the given duration for a receiver created from this session to have a delivery ready for receipt.
      Receiver nextReceiver​(NextReceiverPolicy policy)
      Waits indefinitely for a receiver created from this session to have a delivery ready for receipt.
      Receiver nextReceiver​(NextReceiverPolicy policy, long timeout, java.util.concurrent.TimeUnit unit)
      Waits for the given duration for a receiver created from this session to have a delivery ready for receipt.
      java.lang.String[] offeredCapabilities()
      Returns the offered capabilities that the remote provided upon successfully opening the Session.
      Sender openAnonymousSender()
      Creates a sender that is established to the 'anonymous relay' and as such each message that is sent using this sender must specify an address in its destination address field.
      Sender openAnonymousSender​(SenderOptions senderOptions)
      Creates a sender that is established to the 'anonymous relay' and as such each message that is sent using this sender must specify an address in its destination address field.
      Receiver openDurableReceiver​(java.lang.String address, java.lang.String subscriptionName)
      Creates a receiver used to consume messages from the given node address and configure it such that the remote create a durable node.
      Receiver openDurableReceiver​(java.lang.String address, java.lang.String subscriptionName, ReceiverOptions receiverOptions)
      Creates a receiver used to consume messages from the given node address and configure it such that the remote create a durable node.
      Receiver openDynamicReceiver()
      Creates a dynamic receiver used to consume messages from the given node address.
      Receiver openDynamicReceiver​(java.util.Map<java.lang.String,​java.lang.Object> dynamicNodeProperties)
      Creates a dynamic receiver used to consume messages from the given node address.
      Receiver openDynamicReceiver​(java.util.Map<java.lang.String,​java.lang.Object> dynamicNodeProperties, ReceiverOptions receiverOptions)
      Creates a dynamic receiver used to consume messages from the given node address.
      Receiver openDynamicReceiver​(ReceiverOptions receiverOptions)
      Creates a dynamic receiver used to consume messages from the given node address.
      java.util.concurrent.Future<Session> openFuture()  
      Receiver openReceiver​(java.lang.String address)
      Creates a receiver used to consume messages from the given node address.
      Receiver openReceiver​(java.lang.String address, ReceiverOptions receiverOptions)
      Creates a receiver used to consume messages from the given node address.
      Sender openSender​(java.lang.String address)
      Creates a sender used to send messages to the given node address.
      Sender openSender​(java.lang.String address, SenderOptions senderOptions)
      Creates a sender used to send messages to the given node address.
      java.util.Map<java.lang.String,​java.lang.Object> properties()
      Returns the properties that the remote provided upon successfully opening the Session.
      Session rollbackTransaction()
      Roll back the currently active transaction in this Session.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • openFuture

        public java.util.concurrent.Future<Session> openFuture()
        Specified by:
        openFuture in interface Session
        Returns:
        a Future that will be completed when the remote opens this Session.

      • close

        public void close()
        Description copied from interface: Session
        Requests a close of the Session at the remote and waits until the Session has been fully closed or until the configured SessionOptions.closeTimeout() is exceeded.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface Session

      • closeAsync

        public java.util.concurrent.Future<Session> closeAsync()
        Description copied from interface: Session
        Requests a close of the Session at the remote and returns a Future that will be completed once the session has been remotely closed or an error occurs.
        Specified by:
        closeAsync in interface Session
        Returns:
        a Future that will be completed when the remote closes this Session.

      • closeAsync

        public java.util.concurrent.Future<Session> closeAsync​(ErrorCondition error)
        Description copied from interface: Session
        Requests a close of the Session at the remote and returns a Future that will be completed once the session has been remotely closed or an error occurs.
        Specified by:
        closeAsync in interface Session
        Parameters:
        error - The ErrorCondition to transmit to the remote along with the close operation.
        Returns:
        a Future that will be completed when the remote closes this Session.

      • openReceiver

        public Receiver openReceiver​(java.lang.String address)
                      throws ClientException
        Description copied from interface: Session
        Creates a receiver used to consume messages from the given node address.
        Specified by:
        openReceiver in interface Session
        Parameters:
        address - The source address to attach the consumer to.
        Returns:
        the newly created Receiver
        Throws:
        ClientException - if an internal error occurs.

      • openReceiver

        public Receiver openReceiver​(java.lang.String address,
                             ReceiverOptions receiverOptions)
                      throws ClientException
        Description copied from interface: Session
        Creates a receiver used to consume messages from the given node address.
        Specified by:
        openReceiver in interface Session
        Parameters:
        address - The source address to attach the consumer to.
        receiverOptions - The options for this receiver.
        Returns:
        the newly created Receiver
        Throws:
        ClientException - if an internal error occurs.

      • openDurableReceiver

        public Receiver openDurableReceiver​(java.lang.String address,
                                    java.lang.String subscriptionName)
                             throws ClientException
        Description copied from interface: Session
        Creates a receiver used to consume messages from the given node address and configure it such that the remote create a durable node.
        Specified by:
        openDurableReceiver in interface Session
        Parameters:
        address - The source address to attach the consumer to.
        subscriptionName - The name to give the subscription (link name).
        Returns:
        the newly created Receiver
        Throws:
        ClientException - if an internal error occurs.

      • openDurableReceiver

        public Receiver openDurableReceiver​(java.lang.String address,
                                    java.lang.String subscriptionName,
                                    ReceiverOptions receiverOptions)
                             throws ClientException
        Description copied from interface: Session
        Creates a receiver used to consume messages from the given node address and configure it such that the remote create a durable node.
        Specified by:
        openDurableReceiver in interface Session
        Parameters:
        address - The source address to attach the consumer to.
        subscriptionName - The name to give the subscription (link name).
        receiverOptions - The options for this receiver.
        Returns:
        the newly created Receiver
        Throws:
        ClientException - if an internal error occurs.

      • openDynamicReceiver

        public Receiver openDynamicReceiver​(java.util.Map<java.lang.String,​java.lang.Object> dynamicNodeProperties)
                             throws ClientException
        Description copied from interface: Session
        Creates a dynamic receiver used to consume messages from the given node address.
        Specified by:
        openDynamicReceiver in interface Session
        Parameters:
        dynamicNodeProperties - The dynamic node properties to be applied to the node created by the remote.
        Returns:
        the newly created Receiver
        Throws:
        ClientException - if an internal error occurs.

      • openDynamicReceiver

        public Receiver openDynamicReceiver​(java.util.Map<java.lang.String,​java.lang.Object> dynamicNodeProperties,
                                    ReceiverOptions receiverOptions)
                             throws ClientException
        Description copied from interface: Session
        Creates a dynamic receiver used to consume messages from the given node address.
        Specified by:
        openDynamicReceiver in interface Session
        Parameters:
        dynamicNodeProperties - The dynamic node properties to be applied to the node created by the remote.
        receiverOptions - The options for this receiver.
        Returns:
        the newly created Receiver
        Throws:
        ClientException - if an internal error occurs.

      • openSender

        public Sender openSender​(java.lang.String address)
                  throws ClientException
        Description copied from interface: Session
        Creates a sender used to send messages to the given node address. If no address (i.e null) is specified then a sender will be established to the 'anonymous relay' and each message must specify its destination address.
        Specified by:
        openSender in interface Session
        Parameters:
        address - The target address to attach to, or null to attach to the anonymous relay.
        Returns:
        the newly created Sender.
        Throws:
        ClientException - if an internal error occurs.

      • openSender

        public Sender openSender​(java.lang.String address,
                         SenderOptions senderOptions)
                  throws ClientException
        Description copied from interface: Session
        Creates a sender used to send messages to the given node address. If no address (i.e null) is specified then a sender will be established to the 'anonymous relay' and each message must specify its destination address.
        Specified by:
        openSender in interface Session
        Parameters:
        address - The target address to attach to, or null to attach to the anonymous relay.
        senderOptions - The options for this sender.
        Returns:
        the newly created Sender.
        Throws:
        ClientException - if an internal error occurs.

      • openAnonymousSender

        public Sender openAnonymousSender​(SenderOptions senderOptions)
                           throws ClientException
        Description copied from interface: Session
        Creates a sender that is established to the 'anonymous relay' and as such each message that is sent using this sender must specify an address in its destination address field.
        Specified by:
        openAnonymousSender in interface Session
        Parameters:
        senderOptions - The options for this sender.
        Returns:
        the newly created Sender.
        Throws:
        ClientException - if an internal error occurs.
        ClientUnsupportedOperationException - if the remote did not signal support for anonymous relays.

      • properties

        public java.util.Map<java.lang.String,​java.lang.Object> properties()
                                                                  throws ClientException
        Description copied from interface: Session
        Returns the properties that the remote provided upon successfully opening the Session. If the open has not completed yet this method will block to await the open response which carries the remote properties. If the remote provides no properties this method will return null.
        Specified by:
        properties in interface Session
        Returns:
        any properties provided from the remote once the session has successfully opened.
        Throws:
        ClientException - if an error occurs while obtaining the Session remote properties.

      • offeredCapabilities

        public java.lang.String[] offeredCapabilities()
                                       throws ClientException
        Description copied from interface: Session
        Returns the offered capabilities that the remote provided upon successfully opening the Session. If the open has not completed yet this method will block to await the open response which carries the remote offered capabilities. If the remote provides no capabilities this method will return null.
        Specified by:
        offeredCapabilities in interface Session
        Returns:
        any capabilities provided from the remote once the session has successfully opened.
        Throws:
        ClientException - if an error occurs while obtaining the Session remote offered capabilities.

      • desiredCapabilities

        public java.lang.String[] desiredCapabilities()
                                       throws ClientException
        Description copied from interface: Session
        Returns the desired capabilities that the remote provided upon successfully opening the Session. If the open has not completed yet this method will block to await the open response which carries the remote desired capabilities. If the remote provides no capabilities this method will return null.
        Specified by:
        desiredCapabilities in interface Session
        Returns:
        any desired capabilities provided from the remote once the session has successfully opened.
        Throws:
        ClientException - if an error occurs while obtaining the Session remote desired capabilities.

      • beginTransaction

        public Session beginTransaction()
                         throws ClientException
        Description copied from interface: Session
        Opens a new transaction scoped to this Session if one is not already active. A Session that has an active transaction will perform all sends and all delivery dispositions under that active transaction. If the user wishes to send with the same session but outside of a transaction they user must commit the active transaction and not request that a new one be started. A session can only have one active transaction at a time and as such any call to begin while there is a currently active transaction will throw an ClientTransactionNotActiveException to indicate that the operation being requested is not valid at that time. This is a blocking method that will return successfully only after a new transaction has been started.
        Specified by:
        beginTransaction in interface Session
        Returns:
        this Session instance.
        Throws:
        ClientException - if an error occurs while attempting to begin a new transaction.

      • commitTransaction

        public Session commitTransaction()
                          throws ClientException
        Description copied from interface: Session
        Commit the currently active transaction in this Session. Commit the currently active transaction in this Session but does not start a new transaction automatically. If there is no current transaction this method will throw an ClientTransactionNotActiveException to indicate this error. If the active transaction has entered an in doubt state or was remotely rolled back this method will throw an error to indicate that the commit failed and that a new transaction need to be started by the user. When a transaction rolled back error occurs the user should assume that all work performed under that transaction has failed and will need to be attempted under a new transaction. This is a blocking method that will return successfully only after the current transaction has been committed.
        Specified by:
        commitTransaction in interface Session
        Returns:
        this Session instance.
        Throws:
        ClientException - if an error occurs while attempting to commit the current transaction.

      • rollbackTransaction

        public Session rollbackTransaction()
                            throws ClientException
        Description copied from interface: Session
        Roll back the currently active transaction in this Session. Roll back the currently active transaction in this Session but does not automatically start a new transaction. If there is no current transaction this method will throw an ClientTransactionNotActiveException to indicate this error. If the active transaction has entered an in doubt state or was remotely rolled back this method will throw an error to indicate that the roll back failed and that a new transaction need to be started by the user.
        Specified by:
        rollbackTransaction in interface Session
        Returns:
        this Session instance.
        Throws:
        ClientException - if an error occurs while attempting to roll back the current transaction.

      • nextReceiver

        public Receiver nextReceiver​(long timeout,
                             java.util.concurrent.TimeUnit unit)
                      throws ClientException
        Description copied from interface: Session
        Waits for the given duration for a receiver created from this session to have a delivery ready for receipt. The selection of the next receiver when more than one exits which has pending deliveries is based upon the configured value of the SessionOptions.defaultNextReceiverPolicy() used to create this session or if none was provided then the value is taken from the value of the ConnectionOptions.defaultNextReceiverPolicy(). If no receiver has an available delivery within the given timeout this method returns null.
        Specified by:
        nextReceiver in interface Session
        Parameters:
        timeout - The timeout value used to control how long the method waits for a new Delivery to be available.
        unit - The unit of time that the given timeout represents.
        Returns:
        the next receiver that has a pending delivery available based on policy.
        Throws:
        ClientException - if an internal error occurs.

      • nextReceiver

        public Receiver nextReceiver​(NextReceiverPolicy policy)
                      throws ClientException
        Description copied from interface: Session
        Waits indefinitely for a receiver created from this session to have a delivery ready for receipt. The selection of the next receiver when more than one exits which has pending deliveries is based upon the value of the NextReceiverPolicy that is provided by the caller.
        Specified by:
        nextReceiver in interface Session
        Parameters:
        policy - The policy to apply when selecting the next receiver.
        Returns:
        the next receiver that has a pending delivery available based on policy.
        Throws:
        ClientException - if an internal error occurs.

      • nextReceiver

        public Receiver nextReceiver​(NextReceiverPolicy policy,
                             long timeout,
                             java.util.concurrent.TimeUnit unit)
                      throws ClientException
        Description copied from interface: Session
        Waits for the given duration for a receiver created from this session to have a delivery ready for receipt. The selection of the next receiver when more than one exits which has pending deliveries is based upon the value of the NextReceiverPolicy provided by the caller. If no receiver has an available delivery within the given timeout this method returns null.
        Specified by:
        nextReceiver in interface Session
        Parameters:
        policy - The policy to apply when selecting the next receiver.
        timeout - The timeout value used to control how long the method waits for a new Delivery to be available.
        unit - The unit of time that the given timeout represents.
        Returns:
        the next receiver that has a pending delivery available based on policy.
        Throws:
        ClientException - if an internal error occurs.