Package de.quantummaid.eventmaid.channel

Interface Channel<T>

  • Type Parameters:
    T - the type of messages send over this Channel
    All Superinterfaces:
    AutoCloseable, NoErrorAutoClosable
    public interface Channel<T>
extends NoErrorAutoClosable
    Channel is the concept used for transporting messages from sender to an consuming Action at the end of the Channel.

    Each Channel has a default Action, which, if not changed by a Filter, is executed for every message at the end of the transport. Different Action exists, that allow to add Subscriber, execute specific logic or move the message to different Channels. During the transport Filter can be added, that alter the message, its flow or the Action. Channels can be synchronous or asynchronous. Synchronous Channel execute the transport on the Thread calling send. Asynchronous Channels provide their own Threads and mechanism to queue messages, for which no Threads is available right away. Messages collect statistics over messages, that can be queried anytime. During creation exception handler can be set, that control the Channel's behavior, when an exception is thrown.

    The Channel implements the AutoCloseable interface, so that it can be used in try-with-resource statements.

    See Also:
    EventMaid Documentation, ChannelBuilder

    • Method Detail

      • send

        MessageId send​(T message)
        Send the given message over this Channel.
        Parameters:
        message - the message to be sent
        Returns:
        the MessageId of the send message
        Throws:
        AlreadyClosedException - if the Channel is already closed

      • send

        MessageId send​(T message,
               CorrelationId correlationId)
        Send the given message over this Channel with the given CorrelationId.
        Parameters:
        message - the message to be sent
        correlationId - the CorrelationId of the message
        Returns:
        the MessageId of the send message
        Throws:
        AlreadyClosedException - if the Channel is already closed

      • send

        MessageId send​(ProcessingContext<T> processingContext)
        Send the given processingContext object over this Channel.

        Channels use ProcessingContext objects internally to store and share processing relevant information. Examples are a shared key-value map or the history of past Channels. In case several Channels are logical connected and the information and history should be kept, Channels can accept the ProcessingContext object of the previous Channel directly.

        Parameters:
        processingContext - the ProcessingContext to be sent
        Returns:
        the ProcessingContext's MessageId
        Throws:
        AlreadyClosedException - if the Channel is already closed

      • addPreFilter

        void addPreFilter​(Filter<ProcessingContext<T>> filter)
        Adds the Filter to the list of pre Filter.

        Each Channel has three points, where Filter can be added: pre, process and post. All pre Filter will always be executed before the first process Filter. The same goes for process and post Filter.

        Parameters:
        filter - the Filter to be added

      • addPreFilter

        void addPreFilter​(Filter<ProcessingContext<T>> filter,
                  int position)
        Adds the Filter at the given position to the list of pre Filter.

        Each Channel has three points, where Filter can be added: pre, process and post. All pre Filter will always be executed before the first process Filter. The same goes for process and post Filter.

        Parameters:
        filter - the Filter to be added
        position - the position of the Filter
        Throws:
        ArrayIndexOutOfBoundsException - if the position is higher than the number of Filter or negative

      • getPreFilter

        List<Filter<ProcessingContext<T>>> getPreFilter()
        Returns a list of all Filter registered in the pre list.
        Returns:
        list of Filter in the pre position

      • removePreFilter

        void removePreFilter​(Filter<ProcessingContext<T>> filter)
        Removes the Filter from the pre list.
        Parameters:
        filter - the Filter to be removed

      • addProcessFilter

        void addProcessFilter​(Filter<ProcessingContext<T>> filter)
        Adds the Filter to the list of process Filter.

        Each Channel has three points, where Filter can be added: pre, process and post. All pre Filter will always be executed before the first process Filter. The same goes for process and post Filter.

        Parameters:
        filter - the Filter to be added

      • addProcessFilter

        void addProcessFilter​(Filter<ProcessingContext<T>> filter,
                      int position)
        Adds the Filter at the given position to the list of process Filter.

        Each Channel has three points, where Filter can be added: pre, process and post. All pre Filter will always be executed before the first process Filter. The same goes for process and post Filter.

        Parameters:
        filter - the Filter to be added
        position - the position of the Filter
        Throws:
        ArrayIndexOutOfBoundsException - if the position is higher than the number of Filter or negative

      • getProcessFilter

        List<Filter<ProcessingContext<T>>> getProcessFilter()
        Returns a list of all Filter registered in the process list.
        Returns:
        list of Filter in the process position

      • removeProcessFilter

        void removeProcessFilter​(Filter<ProcessingContext<T>> filter)
        Removes the Filter from the process list.
        Parameters:
        filter - the Filter to be removed

      • addPostFilter

        void addPostFilter​(Filter<ProcessingContext<T>> filter)
        Adds the Filter to the list of post Filter.

        Each Channel has three points, where Filter can be added: pre, process and post. All pre Filter will always be executed before the first process Filter. The same goes for process and post Filter.

        Parameters:
        filter - the Filter to be added

      • addPostFilter

        void addPostFilter​(Filter<ProcessingContext<T>> filter,
                   int position)
        Adds the Filter at the given position to the list of post Filter.

        Each Channel has three points, where Filter can be added: pre, process and post. All pre Filter will always be executed before the first process Filter. The same goes for process and post Filter.

        Parameters:
        filter - the Filter to be added
        position - the position of the Filter
        Throws:
        ArrayIndexOutOfBoundsException - if the position is higher than the number of Filter or negative

      • getPostFilter

        List<Filter<ProcessingContext<T>>> getPostFilter()
        Returns a list of all Filter registered in the post list.
        Returns:
        list of Filter in the post position

      • removePostFilter

        void removePostFilter​(Filter<ProcessingContext<T>> filter)
        Removes the Filter from the post list.
        Parameters:
        filter - the Filter to be removed

      • getDefaultAction

        Action<T> getDefaultAction()
        Returns the default Action of this Channel.
        Returns:
        the default Action of this Channel

      • getStatusInformation

        ChannelStatusInformation getStatusInformation()
        Returns a ChannelStatusInformation object, which can be used to query the Channel's statistics.
        Returns:
        a ChannelStatusInformation object

      • close

        void close​(boolean finishRemainingTasks)
        Closes the Channel so that it shutdowns.

        When setting the parameter to true, the Channel tries to finish remaining tasks, that are still pending. Setting the parameter to false instructs the Channel to shutdown immediately. It is not defined how unfinished tasks should be handled. Independent of the parameter, the Channel will be closed. All tries to send messages will result in exceptions.

        Parameters:
        finishRemainingTasks - boolean flag indicating, whether the Channel should try to finish pending tasks

      • isClosed

        boolean isClosed()
        Returns true if close has been called on this Channel.
        Returns:
        true, if a close was already called, or false otherwise

      • awaitTermination

        boolean awaitTermination​(int timeout,
                         TimeUnit timeUnit)
                  throws InterruptedException
        Blocks the caller until all remaining tasks have completed execution after a close has been called, the timeout occurs or the current thread is interrupted.
        Parameters:
        timeout - the duration to wait
        timeUnit - the time unit of the timeout
        Returns:
        true if this Channel terminated, false if the timeout elapsed before termination or false if close was not yet called
        Throws:
        InterruptedException - if interrupted while waiting