Package org.apache.mina.filter.executor

Class ExecutorFilter

  • All Implemented Interfaces:
    IoFilter
    public class ExecutorFilter
extends IoFilterAdapter
    A filter that forwards I/O events to Executor to enforce a certain thread model while allowing the events per session to be processed simultaneously. You can apply various thread model by inserting this filter to a IoFilterChain.

    Life Cycle Management

    Please note that this filter doesn't manage the life cycle of the Executor. If you created this filter using ExecutorFilter(Executor) or similar constructor that accepts an Executor that you've instantiated, you have full control and responsibility of managing its life cycle (e.g. calling ExecutorService.shutdown().

    If you created this filter using convenience constructors like ExecutorFilter(int), then you can shut down the executor by calling destroy() explicitly.

    Event Ordering

    All convenience constructors of this filter creates a new OrderedThreadPoolExecutor instance. Therefore, the order of event is maintained like the following:
    • All event handler methods are called exclusively. (e.g. messageReceived and messageSent can't be invoked at the same time.)
    • The event order is never mixed up. (e.g. messageReceived is always invoked before sessionClosed or messageSent.)
    However, if you specified other Executor instance in the constructor, the order of events are not maintained at all. This means more than one event handler methods can be invoked at the same time with mixed order. For example, let's assume that messageReceived, messageSent, and sessionClosed events are fired.
    • All event handler methods can be called simultaneously. (e.g. messageReceived and messageSent can be invoked at the same time.)
    • The event order can be mixed up. (e.g. sessionClosed or messageSent can be invoked before messageReceived is invoked.)
    If you need to maintain the order of events per session, please specify an OrderedThreadPoolExecutor instance or use the convenience constructors.

    Selective Filtering

    By default, all event types but sessionCreated, filterWrite, filterClose and filterSetTrafficMask are submitted to the underlying executor, which is most common setting.

    If you want to submit only a certain set of event types, you can specify them in the constructor. For example, you could configure a thread pool for write operation for the maximum performance: 

    
 IoService service = ...;
 DefaultIoFilterChainBuilder chain = service.getFilterChain();
 
 chain.addLast("codec", new ProtocolCodecFilter(...));
 // Use one thread pool for most events.
 chain.addLast("executor1", new ExecutorFilter());
 // and another dedicated thread pool for 'filterWrite' events.
 chain.addLast("executor2", new ExecutorFilter(IoEventType.WRITE));

    Preventing OutOfMemoryError

    Please refer to IoEventQueueThrottle, which is specified as a parameter of the convenience constructors.
    Author:
    Apache MINA Project
    See Also:
    OrderedThreadPoolExecutor, UnorderedThreadPoolExecutor

    • Constructor Detail

      • ExecutorFilter

        public ExecutorFilter()
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor, no thread in the pool, and a maximum of 16 threads in the pool. All the event will be handled by this default executor.

      • ExecutorFilter

        public ExecutorFilter​(int maximumPoolSize)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor, no thread in the pool, but a maximum of threads in the pool is given. All the event will be handled by this default executor.
        Parameters:
        maximumPoolSize - The maximum pool size

      • ExecutorFilter

        public ExecutorFilter​(int corePoolSize,
                      int maximumPoolSize)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor, a number of thread to start with, a maximum of threads the pool can contain. All the event will be handled by this default executor.
        Parameters:
        corePoolSize - The initial pool size
        maximumPoolSize - The maximum pool size

      • ExecutorFilter

        public ExecutorFilter​(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
        Parameters:
        corePoolSize - The initial pool size
        maximumPoolSize - The maximum pool size
        keepAliveTime - Default duration for a thread
        unit - Time unit used for the keepAlive value

      • ExecutorFilter

        public ExecutorFilter​(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      IoEventQueueHandler queueHandler)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
        Parameters:
        corePoolSize - The initial pool size
        maximumPoolSize - The maximum pool size
        keepAliveTime - Default duration for a thread
        unit - Time unit used for the keepAlive value
        queueHandler - The queue used to store events

      • ExecutorFilter

        public ExecutorFilter​(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      ThreadFactory threadFactory)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
        Parameters:
        corePoolSize - The initial pool size
        maximumPoolSize - The maximum pool size
        keepAliveTime - Default duration for a thread
        unit - Time unit used for the keepAlive value
        threadFactory - The factory used to create threads

      • ExecutorFilter

        public ExecutorFilter​(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      ThreadFactory threadFactory,
                      IoEventQueueHandler queueHandler)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
        Parameters:
        corePoolSize - The initial pool size
        maximumPoolSize - The maximum pool size
        keepAliveTime - Default duration for a thread
        unit - Time unit used for the keepAlive value
        threadFactory - The factory used to create threads
        queueHandler - The queue used to store events

      • ExecutorFilter

        public ExecutorFilter​(IoEventType... eventTypes)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
        Parameters:
        eventTypes - The event for which the executor will be used

      • ExecutorFilter

        public ExecutorFilter​(int maximumPoolSize,
                      IoEventType... eventTypes)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
        Parameters:
        maximumPoolSize - The maximum pool size
        eventTypes - The event for which the executor will be used

      • ExecutorFilter

        public ExecutorFilter​(int corePoolSize,
                      int maximumPoolSize,
                      IoEventType... eventTypes)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
        Parameters:
        corePoolSize - The initial pool size
        maximumPoolSize - The maximum pool size
        eventTypes - The event for which the executor will be used

      • ExecutorFilter

        public ExecutorFilter​(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      IoEventType... eventTypes)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
        Parameters:
        corePoolSize - The initial pool size
        maximumPoolSize - The maximum pool size
        keepAliveTime - Default duration for a thread
        unit - Time unit used for the keepAlive value
        eventTypes - The event for which the executor will be used

      • ExecutorFilter

        public ExecutorFilter​(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      IoEventQueueHandler queueHandler,
                      IoEventType... eventTypes)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
        Parameters:
        corePoolSize - The initial pool size
        maximumPoolSize - The maximum pool size
        keepAliveTime - Default duration for a thread
        unit - Time unit used for the keepAlive value
        queueHandler - The queue used to store events
        eventTypes - The event for which the executor will be used

      • ExecutorFilter

        public ExecutorFilter​(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      ThreadFactory threadFactory,
                      IoEventType... eventTypes)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
        Parameters:
        corePoolSize - The initial pool size
        maximumPoolSize - The maximum pool size
        keepAliveTime - Default duration for a thread
        unit - Time unit used for the keepAlive value
        threadFactory - The factory used to create threads
        eventTypes - The event for which the executor will be used

      • ExecutorFilter

        public ExecutorFilter​(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      ThreadFactory threadFactory,
                      IoEventQueueHandler queueHandler,
                      IoEventType... eventTypes)
        (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
        Parameters:
        corePoolSize - The initial pool size
        maximumPoolSize - The maximum pool size
        keepAliveTime - Default duration for a thread
        unit - Time unit used for the keepAlive value
        threadFactory - The factory used to create threads
        queueHandler - The queue used to store events
        eventTypes - The event for which the executor will be used

      • ExecutorFilter

        public ExecutorFilter​(Executor executor)
        Creates a new instance with the specified Executor.
        Parameters:
        executor - the user's managed Executor to use in this filter

      • ExecutorFilter

        public ExecutorFilter​(Executor executor,
                      IoEventType... eventTypes)
        Creates a new instance with the specified Executor.
        Parameters:
        executor - the user's managed Executor to use in this filter
        eventTypes - The event for which the executor will be used