View Javadoc

1   /*
2    *   @(#) $Id: IoFilter.java 210062 2005-07-11 03:52:38Z trustin $
3    *
4    *   Copyright 2004 The Apache Software Foundation
5    *
6    *   Licensed under the Apache License, Version 2.0 (the "License");
7    *   you may not use this file except in compliance with the License.
8    *   You may obtain a copy of the License at
9    *
10   *       http://www.apache.org/licenses/LICENSE-2.0
11   *
12   *   Unless required by applicable law or agreed to in writing, software
13   *   distributed under the License is distributed on an "AS IS" BASIS,
14   *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   *   See the License for the specific language governing permissions and
16   *   limitations under the License.
17   *
18   */
19  package org.apache.mina.io;
20  
21  import org.apache.mina.common.ByteBuffer;
22  import org.apache.mina.common.IdleStatus;
23  
24  /***
25   * A filter which intercepts {@link IoHandler} events like Servlet filters.
26   * Filters can be used for these purposes:
27   * <ul>
28   *   <li>Event logging,</li>
29   *   <li>Performance measurement,</li>
30   *   <li>Data transformation (e.g. SSL support),</li>
31   *   <li>Firewalling,</li>
32   *   <li>and many more.</li>
33   * </ul>
34   * <p>
35   * Please refer to <a href="../../../../../xref/org/apache/mina/io/filter/BlacklistFilter.html"><code>BlacklistFilter</code></a>
36   * example.
37   * <p>
38   * <strong>Please NEVER implement your filters to wrap
39   * {@link IoSession}s.</strong> Users can cache the reference to the session,
40   * which might malfunction if any filters are added or removed later.
41   * 
42   * @author Trustin Lee (trustin@apache.org)
43   * @version $Rev: 210062 $, $Date: 2005-07-11 12:52:38 +0900 $
44   * 
45   * @see IoFilterAdapter
46   */
47  public interface IoFilter
48  {
49      /***
50       * Filters {@link IoHandler#sessionOpened(IoSession)} event.
51       */
52      void sessionOpened( NextFilter nextFilter, IoSession session ) throws Exception;
53  
54      /***
55       * Filters {@link IoHandler#sessionClosed(IoSession)} event.
56       */
57      void sessionClosed( NextFilter nextFilter, IoSession session ) throws Exception;
58  
59      /***
60       * Filters {@link IoHandler#sessionIdle(IoSession, IdleStatus)} event.
61       */
62      void sessionIdle( NextFilter nextFilter, IoSession session,
63                        IdleStatus status ) throws Exception;
64  
65      /***
66       * Filters {@link IoHandler#exceptionCaught(IoSession, Throwable)} event.
67       */
68      void exceptionCaught( NextFilter nextFilter, IoSession session,
69                            Throwable cause ) throws Exception;
70  
71      /***
72       * Filters {@link IoHandler#dataRead(IoSession, ByteBuffer)} event.
73       */
74      void dataRead( NextFilter nextFilter, IoSession session, ByteBuffer buf ) throws Exception;
75  
76      /***
77       * Filters {@link IoHandler#dataWritten(IoSession, Object)} event.
78       */
79      void dataWritten( NextFilter nextFilter, IoSession session, Object marker ) throws Exception;
80  
81      /***
82       * Filters {@link IoSession#write(ByteBuffer, Object)} method invocation.
83       */
84      void filterWrite( NextFilter nextFilter, IoSession session, ByteBuffer buf, Object marker ) throws Exception;
85      
86      public interface NextFilter
87      {
88          void sessionOpened( IoSession session );
89          void sessionClosed( IoSession session );
90          void sessionIdle( IoSession session, IdleStatus status );
91          void exceptionCaught( IoSession session, Throwable cause );
92          void dataRead( IoSession session, ByteBuffer buf );
93          void dataWritten( IoSession session, Object marker );
94          void filterWrite( IoSession session, ByteBuffer buf, Object marker );
95      }
96  }