org.apache.mina.common

Interface IoFilter

Known Implementing Classes:
BlacklistFilter, CompressionFilter, ExecutorFilter, IoFilterAdapter, LoggingFilter, ProtocolCodecFilter, ReferenceCountingIoFilter, SSLFilter, StreamWriteFilter

public interface IoFilter

A filter which intercepts IoHandler events like Servlet filters. Filters can be used for these purposes:

Please NEVER implement your filters to wrap IoSessions. Users can cache the reference to the session, which might malfunction if any filters are added or removed later.

The Life Cycle

IoFilters are activated only when they are inside IoFilterChain.

When you add an IoFilter to an IoFilterChain:

  1. init() is invoked by ReferenceCountingIoFilter if the filter is added at the first time.
  2. onPreAdd(IoFilterChain,String,IoFilter.NextFilter) is invoked to notify that the filter will be added to the chain.
  3. The filter is added to the chain, and all events and I/O requests pass through the filter from now.
  4. onPostAdd(IoFilterChain,String,IoFilter.NextFilter) is invoked to notify that the filter is added to the chain.
  5. The filter is removed from the chain if onPostAdd(IoFilterChain,String,IoFilter.NextFilter) threw an exception. destroy() is also invoked by ReferenceCountingIoFilter if the filter is the last filter which was added to IoFilterChains.

When you remove an IoFilter from an IoFilterChain:

  1. onPreRemove(IoFilterChain,String,IoFilter.NextFilter) is invoked to notify that the filter will be removed from the chain.
  2. The filter is removed from the chain, and any events and I/O requests don't pass through the filter from now.
  3. onPostRemove(IoFilterChain,String,IoFilter.NextFilter) is invoked to notify that the filter is removed from the chain.
  4. destroy() is invoked by ReferenceCountingIoFilter if the removed filter was the last one.
See Also:
IoFilterAdapter

Nested Class Summary

static interface
IoFilter.NextFilter
Represents the next IoFilter in IoFilterChain.
static class
IoFilter.WriteRequest
Represents write request fired by IoSession.write(Object).

Method Summary

void
destroy()
Invoked by ReferenceCountingIoFilter when this filter is not used by any IoFilterChain anymore, so you can destroy shared resources.
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, IoFilter.WriteRequest writeRequest)
Filters IoSession.write(Object) method invocation.
void
init()
Invoked by ReferenceCountingIoFilter when this filter is added to a IoFilterChain at the first time, so you can initialize shared resources.
void
messageReceived(IoFilter.NextFilter nextFilter, IoSession session, Object message)
Filters IoHandler.messageReceived(IoSession,Object) event.
void
messageSent(IoFilter.NextFilter nextFilter, IoSession session, Object message)
Filters IoHandler.messageSent(IoSession,Object) event.
void
onPostAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)
Invoked after this filter is added to the specified parent.
void
onPostRemove(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)
Invoked after this filter is removed from the specified parent.
void
onPreAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)
Invoked before this filter is added to the specified parent.
void
onPreRemove(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)
Invoked before this filter is removed from the specified parent.
void
sessionClosed(IoFilter.NextFilter nextFilter, IoSession session)
Filters IoHandler.sessionClosed(IoSession) event.
void
sessionCreated(IoFilter.NextFilter nextFilter, IoSession session)
Filters IoHandler.sessionCreated(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.

Method Details

destroy

public void destroy()
            throws Exception
Invoked by ReferenceCountingIoFilter when this filter is not used by any IoFilterChain anymore, so you can destroy shared resources. Please note that this method is never called if you don't wrap a filter with ReferenceCountingIoFilter.

exceptionCaught

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

filterClose

public void filterClose(IoFilter.NextFilter nextFilter,
                        IoSession session)
            throws Exception
Filters IoSession.close() method invocation.

filterWrite

public void filterWrite(IoFilter.NextFilter nextFilter,
                        IoSession session,
                        IoFilter.WriteRequest writeRequest)
            throws Exception
Filters IoSession.write(Object) method invocation.

init

public void init()
            throws Exception
Invoked by ReferenceCountingIoFilter when this filter is added to a IoFilterChain at the first time, so you can initialize shared resources. Please note that this method is never called if you don't wrap a filter with ReferenceCountingIoFilter.

messageReceived

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

messageSent

public void messageSent(IoFilter.NextFilter nextFilter,
                        IoSession session,
                        Object message)
            throws Exception

onPostAdd

public void onPostAdd(IoFilterChain parent,
                      String name,
                      IoFilter.NextFilter nextFilter)
            throws Exception
Invoked after 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 init() is invoked.
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.

onPostRemove

public void onPostRemove(IoFilterChain parent,
                         String name,
                         IoFilter.NextFilter nextFilter)
            throws Exception
Invoked after this filter is removed from the specified parent. Please note that this method can be invoked more than once if this filter is removed from more than one parents. This method is always invoked before destroy() is invoked.
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.

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 init() is invoked.
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.

onPreRemove

public void onPreRemove(IoFilterChain parent,
                        String name,
                        IoFilter.NextFilter nextFilter)
            throws Exception
Invoked before this filter is removed from the specified parent. Please note that this method can be invoked more than once if this filter is removed from more than one parents. This method is always invoked before destroy() is invoked.
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.

sessionClosed

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

sessionCreated

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

sessionIdle

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

sessionOpened

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