Package org.apache.qpid.jms.provider

Class ProviderWrapper<E extends Provider>

  • Type Parameters:
    E - the Type of the Provider instance being wrapped.
    All Implemented Interfaces:
    Provider, ProviderListener
    public class ProviderWrapper<E extends Provider>
extends java.lang.Object
implements Provider, ProviderListener
    Allows one Provider instance to wrap around another and provide some additional features beyond the normal Provider interface. This wrapper is meant primarily for Providers that are adding some additional feature on-top of an existing provider such as a discovery based provider that only needs to pass along discovered remote peer information.

    • Constructor Summary

      Constructors 
      Constructor Description
      ProviderWrapper​(E next)  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void acknowledge​(JmsInboundMessageDispatch envelope, ProviderConstants.ACK_TYPE ackType, AsyncResult request)
      Called to acknowledge a JmsMessage has been delivered, consumed, re-delivered...etc.
      void acknowledge​(JmsSessionId sessionId, ProviderConstants.ACK_TYPE ackType, AsyncResult request)
      Called to acknowledge all messages that have been delivered in a given session.
      void close()
      Closes this Provider terminating all connections and canceling any pending operations.
      void commit​(JmsTransactionInfo transactionInfo, JmsTransactionInfo nextTransactionInfo, AsyncResult request)
      Called to commit an open transaction, and start a new one if a new transaction info object is provided.
      void connect​(JmsConnectionInfo connectionInfo)
      Performs the initial low level connection for this provider such as TCP or SSL connection to a remote Broker.
      void create​(JmsResource resource, AsyncResult request)
      Create the Provider version of the given JmsResource.
      void destroy​(JmsResource resourceId, AsyncResult request)
      Instruct the Provider to dispose of a given JmsResource.
      java.util.List<java.net.URI> getAlternateURIs()
      Returns a List of alternate remote peers (possibly found via discovery) to which the caller can attempt a recoonect should this provider connection fail.
      JmsMessageFactory getMessageFactory()
      Gets the Provider specific Message factory for use in the JMS layer when a Session is asked to create a Message type.
      Provider getNext()  
      ProviderListener getProviderListener()
      Gets the currently set ProdiverListener instance.
      java.net.URI getRemoteURI()
      Returns the URI used to configure this Provider and specify the remote address of the Broker it connects to.
      ProviderFuture newProviderFuture()
      Gets a ProviderFuture instance from the Provider for use in performing Provider calls that require an asynchronous completion to know when the call to the provider has succeeded or failed.
      ProviderFuture newProviderFuture​(ProviderSynchronization synchronization)
      Gets a ProviderFuture instance from the Provider for use in performing Provider calls that require an asynchronous completion to know when the call to the provider has succeeded or failed.
      void onCompletedMessageSend​(JmsOutboundMessageDispatch envelope)
      Called when an outbound message dispatch that requested a completion callback has reached a state where the send can be considered successful based on the QoS level associated of the outbound message.
      void onConnectionEstablished​(java.net.URI remoteURI)
      Called to indicate that the underlying connection to the Broker has been established for the first time.
      void onConnectionFailure​(ProviderException ex)
      Called to indicate that the underlying connection to the Broker has been lost and the Provider will not perform any reconnect.
      void onConnectionInterrupted​(java.net.URI remoteURI)
      Called from a fault tolerant Provider instance to signal that the underlying connection to the Broker has been lost.
      void onConnectionRecovered​(Provider provider)
      Called to indicate that a connection to the Broker has been reestablished and that all recovery operations have succeeded and the connection will now be transitioned to a recovered state.
      void onConnectionRecovery​(Provider provider)
      Called to indicate that a connection to the Broker has been reestablished and that notified listener should start to recover it's state.
      void onConnectionRestored​(java.net.URI remoteURI)
      Called to signal that all recovery operations are now complete and the Provider is again in a normal connected state.
      void onFailedMessageSend​(JmsOutboundMessageDispatch envelope, ProviderException cause)
      Called when an outbound message dispatch that requested a completion callback has reached a state where the send can be considered failed.
      void onInboundMessage​(JmsInboundMessageDispatch envelope)
      Called when a new Message has arrived for a registered consumer.
      void onProviderException​(ProviderException cause)
      Called to indicate that a some client operation caused or received an error that is not considered fatal at the provider level.
      void onResourceClosed​(JmsResource resource, ProviderException cause)
      Called to indicate that a currently active resource has been closed due to some error condition, management request or some other action.
      void pull​(JmsConsumerId consumerId, long timeout, AsyncResult request)
      Request a remote peer send a Message to this client.
      void recover​(JmsSessionId sessionId, AsyncResult request)
      Called to recover all unacknowledged messages for a Session in client Ack mode.
      void rollback​(JmsTransactionInfo transactionInfo, JmsTransactionInfo nextTransactionInfo, AsyncResult request)
      Called to roll back an open transaction, and start a new one if a new transaction info object is provided.
      void send​(JmsOutboundMessageDispatch envelope, AsyncResult request)
      Sends the JmsMessage contained in the outbound dispatch envelope.
      void setProviderListener​(ProviderListener listener)
      Sets the listener of events from this Provider instance.
      void start()
      Starts the Provider.
      void start​(JmsResource resource, AsyncResult request)
      Starts the Provider version of the given JmsResource.
      void stop​(JmsResource resource, AsyncResult request)
      Stops (pauses) the Provider version of the given JmsResource, the resource would then need to be started again via a call to start() For some JMS Resources it is necessary or advantageous to have a stopped state that can be triggered to stop the resource generating new events or messages.
      void unsubscribe​(java.lang.String subscription, AsyncResult request)
      Remove a durable topic subscription by name.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • ProviderWrapper

        public ProviderWrapper​(E next)

    • Method Detail

      • connect

        public void connect​(JmsConnectionInfo connectionInfo)
             throws ProviderException
        Description copied from interface: Provider
        Performs the initial low level connection for this provider such as TCP or SSL connection to a remote Broker. If this operation fails then the Provider is considered to be unusable and no further operations should be attempted using this Provider.
        Specified by:
        connect in interface Provider
        Parameters:
        connectionInfo - The JmsConnectionInfo that contains the properties that define this connection.
        Throws:
        ProviderException - if the remote resource can not be contacted.

      • start

        public void start()
           throws ProviderException,
                  java.lang.IllegalStateException
        Description copied from interface: Provider
        Starts the Provider. The start method provides a place for the Provider to perform and pre-start configuration checks to ensure that the current state is valid and that all contracts have been met prior to starting.
        Specified by:
        start in interface Provider
        Throws:
        ProviderException - if an error occurs during start processing.
        java.lang.IllegalStateException - if the Provider is improperly configured.

      • close

        public void close()
        Description copied from interface: Provider
        Closes this Provider terminating all connections and canceling any pending operations. The Provider is considered unusable after this call. This call is a blocking call and will not return until the Provider has closed or an error occurs.
        Specified by:
        close in interface Provider

      • getRemoteURI

        public java.net.URI getRemoteURI()
        Description copied from interface: Provider
        Returns the URI used to configure this Provider and specify the remote address of the Broker it connects to.
        Specified by:
        getRemoteURI in interface Provider
        Returns:
        the URI used to configure this Provider.

      • getAlternateURIs

        public java.util.List<java.net.URI> getAlternateURIs()
        Description copied from interface: Provider
        Returns a List of alternate remote peers (possibly found via discovery) to which the caller can attempt a recoonect should this provider connection fail. If there are no known alternates this method returns an empty List.
        Specified by:
        getAlternateURIs in interface Provider
        Returns:
        a List or alternate remote URIs that could be connected to later.

      • create

        public void create​(JmsResource resource,
                   AsyncResult request)
            throws ProviderException
        Description copied from interface: Provider
        Create the Provider version of the given JmsResource. For each JMS Resource type the Provider implementation must create it's own internal representation and upon successful creation provide the caller with a response. The Provider should examine the given JmsResource to determine if the given configuration is supported or can be simulated, or is not supported in which case an exception should be thrown. It is possible for a Provider to indicate that it cannot complete a requested create either due to some mis-configuration such as bad login credentials on connection create by throwing a JMSException. If the Provider does not support creating of the indicated resource such as a Temporary Queue etc the provider may throw an UnsupportedOperationException to indicate this.
        Specified by:
        create in interface Provider
        Parameters:
        resource - The JmsResouce instance that indicates what is being created.
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • start

        public void start​(JmsResource resource,
                  AsyncResult request)
           throws ProviderException
        Description copied from interface: Provider
        Starts the Provider version of the given JmsResource. For some JMS Resources it is necessary or advantageous to have a started state that must be triggered prior to it's normal use. An example of this would be a MessageConsumer which should not receive any incoming messages until the JMS layer is in a state to handle them. One such time would be after connection recovery. A JMS consumer should normally recover with it's prefetch value set to zero, or an AMQP link credit of zero and only open up the credit window once all Connection resources are restored. The provider is required to implement this method and not throw any error other than an ProviderException if a communication error occurs. The start operation is not required to have any effect on the provider resource but must not throw UnsupportedOperation etc.
        Specified by:
        start in interface Provider
        Parameters:
        resource - The JmsResouce instance that indicates what is being started.
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • stop

        public void stop​(JmsResource resource,
                 AsyncResult request)
          throws ProviderException
        Description copied from interface: Provider
        Stops (pauses) the Provider version of the given JmsResource, the resource would then need to be started again via a call to start() For some JMS Resources it is necessary or advantageous to have a stopped state that can be triggered to stop the resource generating new events or messages. An example of this would be a JMS Session which should not receive any incoming messages for any consumers until the JMS layer is in a state to handle them. One such time would be during a transaction rollback. A JMS Session should normally ensure that messages received in a transaction are set to be redelivered prior to any new deliveries on a transaction rollback. The provider is required to implement this method and not throw any error other than an ProviderException if a communication error occurs. The stop operation is not required to have any effect on the provider resource but must not throw UnsupportedOperation etc.
        Specified by:
        stop in interface Provider
        Parameters:
        resource - The JmsResouce instance that indicates what is being stopped.
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • destroy

        public void destroy​(JmsResource resourceId,
                    AsyncResult request)
             throws ProviderException
        Description copied from interface: Provider
        Instruct the Provider to dispose of a given JmsResource. The provider is given a JmsResource which it should use to remove any associated resources and inform the remote Broker instance of the removal of this resource. If the Provider cannot destroy the resource due to a non-communication error such as the logged in user not have role access to destroy the given resource it may throw an instance of JMSException to indicate such an error.
        Specified by:
        destroy in interface Provider
        Parameters:
        resourceId - The JmsResouce that identifies a previously created JmsResource.
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • send

        public void send​(JmsOutboundMessageDispatch envelope,
                 AsyncResult request)
          throws ProviderException
        Description copied from interface: Provider
        Sends the JmsMessage contained in the outbound dispatch envelope.
        Specified by:
        send in interface Provider
        Parameters:
        envelope - the message envelope containing the JmsMessage to send.
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • acknowledge

        public void acknowledge​(JmsSessionId sessionId,
                        ProviderConstants.ACK_TYPE ackType,
                        AsyncResult request)
                 throws ProviderException
        Description copied from interface: Provider
        Called to acknowledge all messages that have been delivered in a given session. This method is typically used by a Session that is configured for client acknowledge mode. The acknowledgement should only be applied to Messages that have been marked as delivered and not those still awaiting dispatch.
        Specified by:
        acknowledge in interface Provider
        Parameters:
        sessionId - the ID of the Session whose delivered messages should be acknowledged.
        ackType - The type of acknowledgement being done.
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • acknowledge

        public void acknowledge​(JmsInboundMessageDispatch envelope,
                        ProviderConstants.ACK_TYPE ackType,
                        AsyncResult request)
                 throws ProviderException
        Description copied from interface: Provider
        Called to acknowledge a JmsMessage has been delivered, consumed, re-delivered...etc. The provider should perform an acknowledgement for the message based on the configured mode of the consumer that it was dispatched to and the capabilities of the protocol.
        Specified by:
        acknowledge in interface Provider
        Parameters:
        envelope - The message dispatch envelope containing the Message delivery information.
        ackType - The type of acknowledgement being done.
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • commit

        public void commit​(JmsTransactionInfo transactionInfo,
                   JmsTransactionInfo nextTransactionInfo,
                   AsyncResult request)
            throws ProviderException
        Description copied from interface: Provider
        Called to commit an open transaction, and start a new one if a new transaction info object is provided. If this method throws an exception it is either because the commit failed, or the start of the next transaction failed. The caller can investigate the state of the provided next transaction object to determine if a new transaction was created. If the provider is unable to support transactions then it should throw an UnsupportedOperationException to indicate this. The Provider may also throw a JMSException to indicate a transaction was already rolled back etc.
        Specified by:
        commit in interface Provider
        Parameters:
        transactionInfo - the transaction info that describes the transaction being committed.
        nextTransactionInfo - the transaction info that describes the new transaction that should be created.
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • rollback

        public void rollback​(JmsTransactionInfo transactionInfo,
                     JmsTransactionInfo nextTransactionInfo,
                     AsyncResult request)
              throws ProviderException
        Description copied from interface: Provider
        Called to roll back an open transaction, and start a new one if a new transaction info object is provided. If this method throws an exception it is either because the commit failed, or the start of the next transaction failed. The caller can investigate the state of the provided next transaction object to determine if a new transaction was created.
        Specified by:
        rollback in interface Provider
        Parameters:
        transactionInfo - the transaction info that describes the transaction being rolled back.
        nextTransactionInfo - the transaction info that describes the new transaction that should be created.
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • recover

        public void recover​(JmsSessionId sessionId,
                    AsyncResult request)
             throws ProviderException
        Description copied from interface: Provider
        Called to recover all unacknowledged messages for a Session in client Ack mode.
        Specified by:
        recover in interface Provider
        Parameters:
        sessionId - the Id of the JmsSession that is recovering unacknowledged messages..
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • unsubscribe

        public void unsubscribe​(java.lang.String subscription,
                        AsyncResult request)
                 throws ProviderException
        Description copied from interface: Provider
        Remove a durable topic subscription by name. A provider can throw an instance of JMSException to indicate that it cannot perform the un-subscribe operation due to bad security credentials etc.
        Specified by:
        unsubscribe in interface Provider
        Parameters:
        subscription - the name of the durable subscription that is to be removed.
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • pull

        public void pull​(JmsConsumerId consumerId,
                 long timeout,
                 AsyncResult request)
          throws ProviderException
        Description copied from interface: Provider
        Request a remote peer send a Message to this client. A message pull request is usually only needed in the case where the client sets a zero prefetch limit on the consumer. If the consumer has a set prefetch that's greater than zero this method should just return without performing any action. timeout < 0 then it should remain open until a message is received. timeout = 0 then it returns a message or null if none available timeout > 0 then it should remain open for timeout amount of time. The timeout value when positive is given in milliseconds.
        Specified by:
        pull in interface Provider
        Parameters:
        consumerId - the ID of the Consumer instance that is attempt to pull a message from the remote.
        timeout - the amount of time to tell the remote peer to keep this pull request valid.
        request - The request object that should be signaled when this operation completes.
        Throws:
        ProviderException - if an error occurs or the Provider is already closed.

      • getMessageFactory

        public JmsMessageFactory getMessageFactory()
        Description copied from interface: Provider
        Gets the Provider specific Message factory for use in the JMS layer when a Session is asked to create a Message type. The Provider should implement it's own internal JmsMessage core to optimize read / write and marshal operations for the connection.
        Specified by:
        getMessageFactory in interface Provider
        Returns:
        a JmsMessageFactory instance for use by the JMS layer.

      • newProviderFuture

        public ProviderFuture newProviderFuture()
        Description copied from interface: Provider
        Gets a ProviderFuture instance from the Provider for use in performing Provider calls that require an asynchronous completion to know when the call to the provider has succeeded or failed.
        Specified by:
        newProviderFuture in interface Provider
        Returns:
        a ProviderFuture for use in calling Provider methods that require a completion object.

      • newProviderFuture

        public ProviderFuture newProviderFuture​(ProviderSynchronization synchronization)
        Description copied from interface: Provider
        Gets a ProviderFuture instance from the Provider for use in performing Provider calls that require an asynchronous completion to know when the call to the provider has succeeded or failed.
        Specified by:
        newProviderFuture in interface Provider
        Parameters:
        synchronization - A ProviderSynchronization to assign to the resulting ProviderFuture.
        Returns:
        a ProviderFuture for use in calling Provider methods that require a completion object.

      • setProviderListener

        public void setProviderListener​(ProviderListener listener)
        Description copied from interface: Provider
        Sets the listener of events from this Provider instance.
        Specified by:
        setProviderListener in interface Provider
        Parameters:
        listener - The listener instance that will receive all event callbacks.

      • getProviderListener

        public ProviderListener getProviderListener()
        Description copied from interface: Provider
        Gets the currently set ProdiverListener instance.
        Specified by:
        getProviderListener in interface Provider
        Returns:
        the currently set ProviderListener instance.

      • onCompletedMessageSend

        public void onCompletedMessageSend​(JmsOutboundMessageDispatch envelope)
        Description copied from interface: ProviderListener
        Called when an outbound message dispatch that requested a completion callback has reached a state where the send can be considered successful based on the QoS level associated of the outbound message.
        Specified by:
        onCompletedMessageSend in interface ProviderListener
        Parameters:
        envelope - the original outbound message dispatch that is now complete.

      • onFailedMessageSend

        public void onFailedMessageSend​(JmsOutboundMessageDispatch envelope,
                                ProviderException cause)
        Description copied from interface: ProviderListener
        Called when an outbound message dispatch that requested a completion callback has reached a state where the send can be considered failed.
        Specified by:
        onFailedMessageSend in interface ProviderListener
        Parameters:
        envelope - the original outbound message dispatch that should be treated as a failed send.
        cause - the exception that describes the cause of the failed send.

      • onConnectionInterrupted

        public void onConnectionInterrupted​(java.net.URI remoteURI)
        Description copied from interface: ProviderListener
        Called from a fault tolerant Provider instance to signal that the underlying connection to the Broker has been lost. The Provider will attempt to reconnect following this event unless closed. It is considered a programming error to allow any exceptions to be thrown from this notification method.
        Specified by:
        onConnectionInterrupted in interface ProviderListener
        Parameters:
        remoteURI - The URI of the Broker whose connection was lost.

      • onConnectionRecovery

        public void onConnectionRecovery​(Provider provider)
                          throws java.lang.Exception
        Description copied from interface: ProviderListener
        Called to indicate that a connection to the Broker has been reestablished and that notified listener should start to recover it's state. The provider will not transition to the recovered state until the listener notifies the provider that recovery is complete.
        Specified by:
        onConnectionRecovery in interface ProviderListener
        Parameters:
        provider - The new Provider instance that will become active after the state has been recovered.
        Throws:
        java.lang.Exception - if an error occurs during recovery attempt, this will fail the Provider that's being used for recovery.

      • onConnectionRecovered

        public void onConnectionRecovered​(Provider provider)
                           throws java.lang.Exception
        Description copied from interface: ProviderListener
        Called to indicate that a connection to the Broker has been reestablished and that all recovery operations have succeeded and the connection will now be transitioned to a recovered state. This method gives the listener a chance so send any necessary post recovery commands such as consumer start or message pull for a zero prefetch consumer etc.
        Specified by:
        onConnectionRecovered in interface ProviderListener
        Parameters:
        provider - The new Provider instance that will become active after the state has been recovered.
        Throws:
        java.lang.Exception - if an error occurs during recovery attempt, this will fail the Provider that's being used for recovery.

      • onConnectionRestored

        public void onConnectionRestored​(java.net.URI remoteURI)
        Description copied from interface: ProviderListener
        Called to signal that all recovery operations are now complete and the Provider is again in a normal connected state. It is considered a programming error to allow any exceptions to be thrown from this notification method.
        Specified by:
        onConnectionRestored in interface ProviderListener
        Parameters:
        remoteURI - The URI of the Broker that the client has now connected to.

      • onConnectionEstablished

        public void onConnectionEstablished​(java.net.URI remoteURI)
        Description copied from interface: ProviderListener
        Called to indicate that the underlying connection to the Broker has been established for the first time. For a fault tolerant provider this event should only ever be triggered once with the interruption and recovery events following on for future
        Specified by:
        onConnectionEstablished in interface ProviderListener
        Parameters:
        remoteURI - The URI of the Broker that the client has now connected to.

      • onConnectionFailure

        public void onConnectionFailure​(ProviderException ex)
        Description copied from interface: ProviderListener
        Called to indicate that the underlying connection to the Broker has been lost and the Provider will not perform any reconnect. Following this call the provider is in a failed state and further calls to it will throw an Exception.
        Specified by:
        onConnectionFailure in interface ProviderListener
        Parameters:
        ex - The exception that indicates the cause of this Provider failure.

      • onResourceClosed

        public void onResourceClosed​(JmsResource resource,
                             ProviderException cause)
        Description copied from interface: ProviderListener
        Called to indicate that a currently active resource has been closed due to some error condition, management request or some other action. This can either be initiated remotely or locally depending on the condition that triggers the close.
        Specified by:
        onResourceClosed in interface ProviderListener
        Parameters:
        resource - the JmsResource instance that has been closed.
        cause - optional exception object that indicates the cause of the close.

      • onProviderException

        public void onProviderException​(ProviderException cause)
        Description copied from interface: ProviderListener
        Called to indicate that a some client operation caused or received an error that is not considered fatal at the provider level.
        Specified by:
        onProviderException in interface ProviderListener
        Parameters:
        cause - the exception object that is being reported to the listener.

      • getNext

        public Provider getNext()
        Returns:
        the wrapped Provider.