org.apache.mina.filter.executor

## Class ExecutorFilter

- java.lang.Object
- - org.apache.mina.core.filterchain.IoFilterAdapter
  - - org.apache.mina.filter.executor.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`

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.apache.mina.core.filterchain.IoFilter

      `IoFilter.NextFilter`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `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.
    `ExecutorFilter(Executor executor)` Creates a new instance with the specified `Executor`.
    `ExecutorFilter(Executor executor, IoEventType... eventTypes)` Creates a new instance with the specified `Executor`.
    `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.
    `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.
    `ExecutorFilter(int corePoolSize, int maximumPoolSize, IoEventType... eventTypes)` (Convenience constructor) Creates a new instance with a new `OrderedThreadPoolExecutor`.
    `ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit)` (Convenience constructor) Creates a new instance with a new `OrderedThreadPoolExecutor`.
    `ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, IoEventQueueHandler queueHandler)` (Convenience constructor) Creates a new instance with a new `OrderedThreadPoolExecutor`.
    `ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, IoEventQueueHandler queueHandler, IoEventType... eventTypes)` (Convenience constructor) Creates a new instance with a new `OrderedThreadPoolExecutor`.
    `ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, IoEventType... eventTypes)` (Convenience constructor) Creates a new instance with a new `OrderedThreadPoolExecutor`.
    `ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, ThreadFactory threadFactory)` (Convenience constructor) Creates a new instance with a new `OrderedThreadPoolExecutor`.
    `ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, ThreadFactory threadFactory, IoEventQueueHandler queueHandler)` (Convenience constructor) Creates a new instance with a new `OrderedThreadPoolExecutor`.
    `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`.
    `ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, ThreadFactory threadFactory, IoEventType... eventTypes)` (Convenience constructor) Creates a new instance with a new `OrderedThreadPoolExecutor`.
    `ExecutorFilter(int maximumPoolSize, IoEventType... eventTypes)` (Convenience constructor) Creates a new instance with a new `OrderedThreadPoolExecutor`.
    `ExecutorFilter(IoEventType... eventTypes)` (Convenience constructor) Creates a new instance with a new `OrderedThreadPoolExecutor`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` Shuts down the underlying executor if this filter hase been created via a convenience constructor.
    `void` | `exceptionCaught(IoFilter.NextFilter nextFilter, IoSession session, Throwable cause)` Filters `IoHandler.exceptionCaught(IoSession,Throwable)` event.
    `void` | `filterClose(IoFilter.NextFilter nextFilter, IoSession session)` Filters `IoSession.close()` method invocation.
    `void` | `filterWrite(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)` Filters `IoSession.write(Object)` method invocation.
    `protected void` | `fireEvent(IoFilterEvent event)` Fires the specified event through the underlying executor.
    `Executor` | `getExecutor()` Returns the underlying `Executor` instance this filter uses.
    `void` | `messageReceived(IoFilter.NextFilter nextFilter, IoSession session, Object message)` Filters `IoHandler.messageReceived(IoSession,Object)` event.
    `void` | `messageSent(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)` Filters `IoHandler.messageSent(IoSession,Object)` event.
    `void` | `onPreAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)` Invoked before this filter is added to the specified `parent`.
    `void` | `sessionClosed(IoFilter.NextFilter nextFilter, IoSession session)` Filters `IoHandler.sessionClosed(IoSession)` event.
    `void` | `sessionIdle(IoFilter.NextFilter nextFilter, IoSession session, IdleStatus status)` Filters `IoHandler.sessionIdle(IoSession,IdleStatus)` event.
    `void` | `sessionOpened(IoFilter.NextFilter nextFilter, IoSession session)` Filters `IoHandler.sessionOpened(IoSession)` event.

    - ### Methods inherited from class org.apache.mina.core.filterchain.IoFilterAdapter

      `init, onPostAdd, onPostRemove, onPreRemove, sessionCreated, toString`

    - ### Methods inherited from class java.lang.Object

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

- - ### 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

  - ### Method Detail

    - #### destroy

          public void destroy()

      Shuts down the underlying executor if this filter hase been created via a convenience constructor.
      Specified by:
        `destroy` in interface `IoFilter`
      Overrides:
        `destroy` in class `IoFilterAdapter`

    - #### getExecutor

          public final Executor getExecutor()

      Returns the underlying `Executor` instance this filter uses.
      Returns:
        The underlying `Executor`

    - #### fireEvent

          protected void fireEvent(IoFilterEvent event)

      Fires the specified event through the underlying executor.
      Parameters:
        `event` - The filtered event

    - #### onPreAdd

          public void onPreAdd(IoFilterChain parent,
                      String name,
                      IoFilter.NextFilter nextFilter)
                        throws Exception

      Invoked before this filter is added to the specified `parent`. Please note that this method can be invoked more than once if this filter is added to more than one parents. This method is not invoked before `IoFilter.init()` is invoked.
      Specified by:
        `onPreAdd` in interface `IoFilter`
      Overrides:
        `onPreAdd` in class `IoFilterAdapter`
      Parameters:
        `parent` - the parent who called this method
        `name` - the name assigned to this filter
        `nextFilter` - the `IoFilter.NextFilter` for this filter. You can reuse this object until this filter is removed from the chain.
      Throws:
        `Exception`

    - #### sessionOpened

          public final void sessionOpened(IoFilter.NextFilter nextFilter,
                           IoSession session)

      Filters `IoHandler.sessionOpened(IoSession)` event.
      Specified by:
        `sessionOpened` in interface `IoFilter`
      Overrides:
        `sessionOpened` in class `IoFilterAdapter`

    - #### sessionClosed

          public final void sessionClosed(IoFilter.NextFilter nextFilter,
                           IoSession session)

      Filters `IoHandler.sessionClosed(IoSession)` event.
      Specified by:
        `sessionClosed` in interface `IoFilter`
      Overrides:
        `sessionClosed` in class `IoFilterAdapter`

    - #### sessionIdle

          public final void sessionIdle(IoFilter.NextFilter nextFilter,
                         IoSession session,
                         IdleStatus status)

      Filters `IoHandler.sessionIdle(IoSession,IdleStatus)` event.
      Specified by:
        `sessionIdle` in interface `IoFilter`
      Overrides:
        `sessionIdle` in class `IoFilterAdapter`

    - #### exceptionCaught

          public final void exceptionCaught(IoFilter.NextFilter nextFilter,
                             IoSession session,
                             Throwable cause)

      Filters `IoHandler.exceptionCaught(IoSession,Throwable)` event.
      Specified by:
        `exceptionCaught` in interface `IoFilter`
      Overrides:
        `exceptionCaught` in class `IoFilterAdapter`

    - #### messageReceived

          public final void messageReceived(IoFilter.NextFilter nextFilter,
                             IoSession session,
                             Object message)

      Filters `IoHandler.messageReceived(IoSession,Object)` event.
      Specified by:
        `messageReceived` in interface `IoFilter`
      Overrides:
        `messageReceived` in class `IoFilterAdapter`

    - #### messageSent

          public final void messageSent(IoFilter.NextFilter nextFilter,
                         IoSession session,
                         WriteRequest writeRequest)

      Filters `IoHandler.messageSent(IoSession,Object)` event.
      Specified by:
        `messageSent` in interface `IoFilter`
      Overrides:
        `messageSent` in class `IoFilterAdapter`

    - #### filterWrite

          public final void filterWrite(IoFilter.NextFilter nextFilter,
                         IoSession session,
                         WriteRequest writeRequest)

      Filters `IoSession.write(Object)` method invocation.
      Specified by:
        `filterWrite` in interface `IoFilter`
      Overrides:
        `filterWrite` in class `IoFilterAdapter`

    - #### filterClose

          public final void filterClose(IoFilter.NextFilter nextFilter,
                         IoSession session)
                                 throws Exception

      Filters `IoSession.close()` method invocation.
      Specified by:
        `filterClose` in interface `IoFilter`
      Overrides:
        `filterClose` in class `IoFilterAdapter`
      Throws:
        `Exception`

Copyright © 2004-2012 Apache MINA Project. All Rights Reserved.