Package org.apache.mina.core.filterchain

Interface IoFilter

All Known Implementing Classes:

AbstractStreamWriteFilter, BlacklistFilter, BufferedWriteFilter, CommonEventFilter, ConnectionThrottleFilter, ErrorGeneratingFilter, ExecutorFilter, FileRegionWriteFilter, IoFilterAdapter, KeepAliveFilter, LoggingFilter, MdcInjectionFilter, NoopFilter, ProfilerTimerFilter, ProtocolCodecFilter, ProxyFilter, ReferenceCountingFilter, SaslFilter, SessionAttributeInitializingFilter, SslFilter, StreamWriteFilter, WriteRequestFilter

public interface IoFilter

A filter which intercepts IoHandler events like Servlet filters. 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 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 ReferenceCountingFilter if the filter is added at the first time.
2. onPreAdd(IoFilterChain, String, 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, 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, org.apache.mina.core.filterchain.IoFilter.NextFilter) threw an exception. destroy() is also invoked by ReferenceCountingFilter if the filter is the last filter which was added to IoFilterChains.

When you remove an IoFilter from an IoFilterChain:

1. onPreRemove(IoFilterChain, String, 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, NextFilter) is invoked to notify that the filter is removed from the chain.
4. destroy() is invoked by ReferenceCountingFilter if the removed filter was the last one.

Author:

Apache MINA Project

See Also:

IoFilterAdapter

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	IoFilter.NextFilter	Represents the next IoFilter in IoFilterChain.

Method Summary

Modifier and Type	Method	Description
void	destroy()	Invoked by ReferenceCountingFilter when this filter is not used by any IoFilterChain anymore, so you can destroy shared resources.
void	event(IoFilter.NextFilter nextFilter, IoSession session, FilterEvent event)	Propagate an event up to the IoHandler
void	exceptionCaught(IoFilter.NextFilter nextFilter, IoSession session, Throwable cause)	Filters IoHandler.exceptionCaught(IoSession,Throwable) event.
void	filterClose(IoFilter.NextFilter nextFilter, IoSession session)	Filters IoSession.closeNow() or a IoSession.closeOnFlush() method invocations.
void	filterWrite(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)	Filters IoSession.write(Object) method invocation.
void	init()	Invoked by ReferenceCountingFilter when this filter is added to a IoFilterChain at the first time, so you can initialize shared resources.
void	inputClosed(IoFilter.NextFilter nextFilter, IoSession session)	Filters IoHandler.inputClosed(IoSession) event.
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	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 Detail

init

void init()
   throws Exception

Invoked by ReferenceCountingFilter 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 ReferenceCountingFilter.

Throws:

Exception - If an error occurred while processing the event

destroy

void destroy()
      throws Exception

Invoked by ReferenceCountingFilter 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 ReferenceCountingFilter.

Throws:

Exception - If an error occurred while processing the event

onPreAdd

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.

Throws:

Exception - If an error occurred while processing the event

onPostAdd

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.

Throws:

Exception - If an error occurred while processing the event

onPreRemove

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.

Throws:

Exception - If an error occurred while processing the event

onPostRemove

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.

Throws:

Exception - If an error occurred while processing the event

sessionCreated

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

Filters IoHandler.sessionCreated(IoSession) event.

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has received this event

Throws:

Exception - If an error occurred while processing the event

sessionOpened

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

Filters IoHandler.sessionOpened(IoSession) event.

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has received this event

Throws:

Exception - If an error occurred while processing the event

sessionClosed

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

Filters IoHandler.sessionClosed(IoSession) event.

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has received this event

Throws:

Exception - If an error occurred while processing the event

sessionIdle

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

Filters IoHandler.sessionIdle(IoSession,IdleStatus) event.

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has received this event

status - The IdleStatus type

Throws:

Exception - If an error occurred while processing the event

exceptionCaught

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

Filters IoHandler.exceptionCaught(IoSession,Throwable) event.

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has received this event

cause - The exception that cause this event to be received

Throws:

Exception - If an error occurred while processing the event

inputClosed

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

Filters IoHandler.inputClosed(IoSession) event.

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has received this event

Throws:

Exception - If an error occurred while processing the event

messageReceived

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

Filters IoHandler.messageReceived(IoSession,Object) event.

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has received this event

message - The received message

Throws:

Exception - If an error occurred while processing the event

messageSent

void messageSent(IoFilter.NextFilter nextFilter,
                 IoSession session,
                 WriteRequest writeRequest)
          throws Exception

Filters IoHandler.messageSent(IoSession,Object) event.

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has received this event

writeRequest - The WriteRequest that contains the sent message

Throws:

Exception - If an error occurred while processing the event

filterClose

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

Filters IoSession.closeNow() or a IoSession.closeOnFlush() method invocations.

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has to process this method invocation

Throws:

Exception - If an error occurred while processing the event

filterWrite

void filterWrite(IoFilter.NextFilter nextFilter,
                 IoSession session,
                 WriteRequest writeRequest)
          throws Exception

Filters IoSession.write(Object) method invocation.

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has to process this invocation

writeRequest - The WriteRequest to process

Throws:

Exception - If an error occurred while processing the event

event

void event(IoFilter.NextFilter nextFilter,
           IoSession session,
           FilterEvent event)
    throws Exception

Propagate an event up to the IoHandler

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has to process this invocation

event - The event to propagate

Throws:

Exception - If an error occurred while processing the event