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.
See Also:

  • Field Details

    • eventTypes

      private EnumSet<IoEventType> eventTypes
      The list of handled events

    • executor

      private Executor executor
      The associated executor

    • manageableExecutor

      private boolean manageableExecutor
      A flag set if the executor can be managed

    • DEFAULT_MAX_POOL_SIZE

      private static final int DEFAULT_MAX_POOL_SIZE
      The default pool size
      See Also:

    • BASE_THREAD_NUMBER

      private static final int BASE_THREAD_NUMBER
      The number of thread to create at startup
      See Also:

    • DEFAULT_KEEPALIVE_TIME

      private static final long DEFAULT_KEEPALIVE_TIME
      The default KeepAlive time, in seconds
      See Also:

    • MANAGEABLE_EXECUTOR

      private static final boolean MANAGEABLE_EXECUTOR
      A set of flags used to tell if the Executor has been created in the constructor or passed as an argument. In the second case, the executor state can be managed.
      See Also:

    • NOT_MANAGEABLE_EXECUTOR

      private static final boolean NOT_MANAGEABLE_EXECUTOR
      See Also:

    • DEFAULT_EVENT_SET

      private static final IoEventType[] DEFAULT_EVENT_SET
      A list of default EventTypes to be handled by the executor

  • Constructor Details

    • 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 Details