A filter which intercepts {@link IoHandler} events like Servletfilters. Filters can be used for these purposes:
- Event logging,
- Performance measurement,
- Authorization,
- Overload control,
- Message transformation (e.g. encryption and decryption, ...),
- and many more.
Please NEVER implement your filters to wrap {@link IoSession}s. Users can cache the reference to the session, which might malfunction if any filters are added or removed later.
The Life Cycle
{@link IoFilter}s are activated only when they are inside {@link IoFilterChain}.
When you add an {@link IoFilter} to an {@link IoFilterChain}:
- {@link #init()} is invoked by {@link ReferenceCountingIoFilter} ifthe filter is added at the first time.
- {@link #onPreAdd(IoFilterChain,String,NextFilter)} is invoked to notifythat the filter will be added to the chain.
- The filter is added to the chain, and all events and I/O requests pass through the filter from now.
- {@link #onPostAdd(IoFilterChain,String,NextFilter)} is invoked to notifythat the filter is added to the chain.
- The filter is removed from the chain if {@link #onPostAdd(IoFilterChain,String,org.apache.mina.common.IoFilter.NextFilter)}threw an exception. {@link #destroy()} is also invoked by{@link ReferenceCountingIoFilter} if the filter is the last filter whichwas added to {@link IoFilterChain}s.
When you remove an {@link IoFilter} from an {@link IoFilterChain}:
- {@link #onPreRemove(IoFilterChain,String,NextFilter)} is invoked tonotify that the filter will be removed from the chain.
- The filter is removed from the chain, and any events and I/O requests don't pass through the filter from now.
- {@link #onPostRemove(IoFilterChain,String,NextFilter)} is invoked tonotify that the filter is removed from the chain.
- {@link #destroy()} is invoked by {@link ReferenceCountingIoFilter} ifthe removed filter was the last one.
@author The Apache Directory Project (mina-dev@directory.apache.org)
@version $Rev: 555855 $, $Date: 2007-07-13 12:19:00 +0900 (Fri, 13 Jul 2007) $
@see IoFilterAdapter