View Javadoc

1   /*
2    *   @(#) $Id: ProtocolFilter.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.protocol;
20  
21  import org.apache.mina.common.IdleStatus;
22  
23  /***
24   * A filter which intercepts {@link ProtocolHandler} events like Servlet
25   * filters.  Filters can be used for these purposes:
26   * <ul>
27   *   <li>Event logging,</li>
28   *   <li>Performance measurement,</li>
29   *   <li>Authorization,</li>
30   *   <li>Overload control,</li>
31   *   <li>Message transformation (e.g. encryption and decryption, ...),</li>
32   *   <li>and many more.</li>
33   * </ul>
34   * <p>
35   * <strong>Please NEVER implement your filters to wrap
36   * {@link ProtocolSession}s.</strong> Users can cache the reference to the
37   * session, which might malfunction if any filters are added or removed later.
38   * 
39   * @author Trustin Lee (trustin@apache.org)
40   * @version $Rev: 210062 $, $Date: 2005-07-11 12:52:38 +0900 $
41   * 
42   * @see ProtocolFilterAdapter
43   */
44  public interface ProtocolFilter
45  {
46      /***
47       * Filters {@link ProtocolHandler#sessionOpened(ProtocolSession)} event.
48       */
49      void sessionOpened( NextFilter nextFilter, ProtocolSession session ) throws Exception;
50  
51      /***
52       * Filters {@link ProtocolHandler#sessionClosed(ProtocolSession)} event.
53       */
54      void sessionClosed( NextFilter nextFilter, ProtocolSession session ) throws Exception;
55  
56      /***
57       * Filters {@link ProtocolHandler#sessionIdle(ProtocolSession,IdleStatus)}
58       * event.
59       */
60      void sessionIdle( NextFilter nextFilter, ProtocolSession session,
61                       IdleStatus status ) throws Exception;
62  
63      /***
64       * Filters {@link ProtocolHandler#exceptionCaught(ProtocolSession,Throwable)}
65       * event.
66       */
67      void exceptionCaught( NextFilter nextFilter,
68                           ProtocolSession session, Throwable cause ) throws Exception;
69  
70      /***
71       * Filters {@link ProtocolHandler#messageReceived(ProtocolSession,Object)}
72       * event.
73       */
74      void messageReceived( NextFilter nextFilter,
75                           ProtocolSession session, Object message ) throws Exception;
76  
77      /***
78       * Filters {@link ProtocolHandler#messageSent(ProtocolSession,Object)}
79       * event.
80       */
81      void messageSent( NextFilter nextFilter, ProtocolSession session,
82                       Object message ) throws Exception;
83  
84      /***
85       * Filters {@link ProtocolSession#write(Object)} method invocation.
86       */
87      void filterWrite( NextFilter nextFilter, ProtocolSession session, Object message ) throws Exception;
88      
89      public interface NextFilter
90      {
91          void sessionOpened( ProtocolSession session );
92          void sessionClosed( ProtocolSession session );
93          void sessionIdle( ProtocolSession session, IdleStatus status );
94          void exceptionCaught( ProtocolSession session, Throwable cause );
95          void messageReceived( ProtocolSession session, Object message );
96          void messageSent( ProtocolSession session, Object message );
97          void filterWrite( ProtocolSession session, Object message );
98      }
99  }