org.apache.mina.filter.executor
Class ExecutorFilter

java.lang.Object
  extended by org.apache.mina.core.filterchain.IoFilterAdapter
      extended by 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: 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. 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
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
 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.