View Javadoc

1   /*
2    *  Licensed to the Apache Software Foundation (ASF) under one
3    *  or more contributor license agreements.  See the NOTICE file
4    *  distributed with this work for additional information
5    *  regarding copyright ownership.  The ASF licenses this file
6    *  to you under the Apache License, Version 2.0 (the
7    *  "License"); you may not use this file except in compliance
8    *  with the License.  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,
13   *  software distributed under the License is distributed on an
14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   *  KIND, either express or implied.  See the License for the
16   *  specific language governing permissions and limitations
17   *  under the License.
18   *
19   */
20  package org.apache.mina.common;
21  
22  import org.apache.mina.filter.util.ReferenceCountingFilter;
23  
24  /**
25   * A filter which intercepts {@link IoHandler} events like Servlet
26   * filters.  Filters can be used for these purposes:
27   * <ul>
28   *   <li>Event logging,</li>
29   *   <li>Performance measurement,</li>
30   *   <li>Authorization,</li>
31   *   <li>Overload control,</li>
32   *   <li>Message transformation (e.g. encryption and decryption, ...),</li>
33   *   <li>and many more.</li>
34   * </ul>
35   * <p>
36   * <strong>Please NEVER implement your filters to wrap
37   * {@link IoSession}s.</strong> Users can cache the reference to the
38   * session, which might malfunction if any filters are added or removed later.
39   *
40   * <h3>The Life Cycle</h3>
41   * {@link IoFilter}s are activated only when they are inside {@link IoFilterChain}.
42   * <p>
43   * When you add an {@link IoFilter} to an {@link IoFilterChain}:
44   * <ol>
45   *   <li>{@link #init()} is invoked by {@link ReferenceCountingFilter} if
46   *       the filter is added at the first time.</li>
47   *   <li>{@link #onPreAdd(IoFilterChain, String, NextFilter)} is invoked to notify
48   *       that the filter will be added to the chain.</li>
49   *   <li>The filter is added to the chain, and all events and I/O requests
50   *       pass through the filter from now.</li>
51   *   <li>{@link #onPostAdd(IoFilterChain, String, NextFilter)} is invoked to notify
52   *       that the filter is added to the chain.</li>
53   *   <li>The filter is removed from the chain if {@link #onPostAdd(IoFilterChain, String, org.apache.mina.common.IoFilter.NextFilter)}
54   *       threw an exception.  {@link #destroy()} is also invoked by
55   *       {@link ReferenceCountingFilter} if the filter is the last filter which
56   *       was added to {@link IoFilterChain}s.</li>
57   * </ol>
58   * <p>
59   * When you remove an {@link IoFilter} from an {@link IoFilterChain}:
60   * <ol>
61   *   <li>{@link #onPreRemove(IoFilterChain, String, NextFilter)} is invoked to
62   *       notify that the filter will be removed from the chain.</li>
63   *   <li>The filter is removed from the chain, and any events and I/O requests
64   *       don't pass through the filter from now.</li>
65   *   <li>{@link #onPostRemove(IoFilterChain, String, NextFilter)} is invoked to
66   *       notify that the filter is removed from the chain.</li>
67   *   <li>{@link #destroy()} is invoked by {@link ReferenceCountingFilter} if
68   *       the removed filter was the last one.</li>
69   * </ol>
70   *
71   * @author The Apache MINA Project (dev@mina.apache.org)
72   * @version $Rev: 591770 $, $Date: 2007-11-04 05:22:44 -0700 (Sun, 04 Nov 2007) $
73   *
74   * @see IoFilterAdapter
75   */
76  public interface IoFilter {
77      /**
78       * Invoked by {@link ReferenceCountingFilter} when this filter
79       * is added to a {@link IoFilterChain} at the first time, so you can
80       * initialize shared resources.  Please note that this method is never
81       * called if you don't wrap a filter with {@link ReferenceCountingFilter}.
82       */
83      void init() throws Exception;
84  
85      /**
86       * Invoked by {@link ReferenceCountingFilter} when this filter
87       * is not used by any {@link IoFilterChain} anymore, so you can destroy
88       * shared resources.  Please note that this method is never called if
89       * you don't wrap a filter with {@link ReferenceCountingFilter}.
90       */
91      void destroy() throws Exception;
92  
93      /**
94       * Invoked before this filter is added to the specified <tt>parent</tt>.
95       * Please note that this method can be invoked more than once if
96       * this filter is added to more than one parents.  This method is not
97       * invoked before {@link #init()} is invoked.
98       *
99       * @param parent the parent who called this method
100      * @param name the name assigned to this filter
101      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
102      *                   this object until this filter is removed from the chain.
103      */
104     void onPreAdd(IoFilterChain parent, String name, NextFilter nextFilter)
105             throws Exception;
106 
107     /**
108      * Invoked after this filter is added to the specified <tt>parent</tt>.
109      * Please note that this method can be invoked more than once if
110      * this filter is added to more than one parents.  This method is not
111      * invoked before {@link #init()} is invoked.
112      *
113      * @param parent the parent who called this method
114      * @param name the name assigned to this filter
115      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
116      *                   this object until this filter is removed from the chain.
117      */
118     void onPostAdd(IoFilterChain parent, String name, NextFilter nextFilter)
119             throws Exception;
120 
121     /**
122      * Invoked before this filter is removed from the specified <tt>parent</tt>.
123      * Please note that this method can be invoked more than once if
124      * this filter is removed from more than one parents.
125      * This method is always invoked before {@link #destroy()} is invoked.
126      *
127      * @param parent the parent who called this method
128      * @param name the name assigned to this filter
129      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
130      *                   this object until this filter is removed from the chain.
131      */
132     void onPreRemove(IoFilterChain parent, String name, NextFilter nextFilter)
133             throws Exception;
134 
135     /**
136      * Invoked after this filter is removed from the specified <tt>parent</tt>.
137      * Please note that this method can be invoked more than once if
138      * this filter is removed from more than one parents.
139      * This method is always invoked before {@link #destroy()} is invoked.
140      *
141      * @param parent the parent who called this method
142      * @param name the name assigned to this filter
143      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
144      *                   this object until this filter is removed from the chain.
145      */
146     void onPostRemove(IoFilterChain parent, String name, NextFilter nextFilter)
147             throws Exception;
148 
149     /**
150      * Filters {@link IoHandler#sessionCreated(IoSession)} event.
151      */
152     void sessionCreated(NextFilter nextFilter, IoSession session)
153             throws Exception;
154 
155     /**
156      * Filters {@link IoHandler#sessionOpened(IoSession)} event.
157      */
158     void sessionOpened(NextFilter nextFilter, IoSession session)
159             throws Exception;
160 
161     /**
162      * Filters {@link IoHandler#sessionClosed(IoSession)} event.
163      */
164     void sessionClosed(NextFilter nextFilter, IoSession session)
165             throws Exception;
166 
167     /**
168      * Filters {@link IoHandler#sessionIdle(IoSession,IdleStatus)}
169      * event.
170      */
171     void sessionIdle(NextFilter nextFilter, IoSession session, IdleStatus status)
172             throws Exception;
173 
174     /**
175      * Filters {@link IoHandler#exceptionCaught(IoSession,Throwable)}
176      * event.
177      */
178     void exceptionCaught(NextFilter nextFilter, IoSession session,
179             Throwable cause) throws Exception;
180 
181     /**
182      * Filters {@link IoHandler#messageReceived(IoSession,Object)}
183      * event.
184      */
185     void messageReceived(NextFilter nextFilter, IoSession session,
186             Object message) throws Exception;
187 
188     /**
189      * Filters {@link IoHandler#messageSent(IoSession,Object)}
190      * event.
191      */
192     void messageSent(NextFilter nextFilter, IoSession session,
193             WriteRequest writeRequest) throws Exception;
194 
195     /**
196      * Filters {@link IoSession#close()} method invocation.
197      */
198     void filterClose(NextFilter nextFilter, IoSession session) throws Exception;
199 
200     /**
201      * Filters {@link IoSession#write(Object)} method invocation.
202      */
203     void filterWrite(NextFilter nextFilter, IoSession session,
204             WriteRequest writeRequest) throws Exception;
205     
206     /**
207      * Filters {@link IoSession#setTrafficMask(TrafficMask)} method invocation.
208      */
209     void filterSetTrafficMask(
210             NextFilter nextFilter, IoSession session, TrafficMask trafficMask) throws Exception;
211 
212     /**
213      * Represents the next {@link IoFilter} in {@link IoFilterChain}.
214      */
215     public interface NextFilter {
216         /**
217          * Forwards <tt>sessionCreated</tt> event to next filter.
218          */
219         void sessionCreated(IoSession session);
220 
221         /**
222          * Forwards <tt>sessionOpened</tt> event to next filter.
223          */
224         void sessionOpened(IoSession session);
225 
226         /**
227          * Forwards <tt>sessionClosed</tt> event to next filter.
228          */
229         void sessionClosed(IoSession session);
230 
231         /**
232          * Forwards <tt>sessionIdle</tt> event to next filter.
233          */
234         void sessionIdle(IoSession session, IdleStatus status);
235 
236         /**
237          * Forwards <tt>exceptionCaught</tt> event to next filter.
238          */
239         void exceptionCaught(IoSession session, Throwable cause);
240 
241         /**
242          * Forwards <tt>messageReceived</tt> event to next filter.
243          */
244         void messageReceived(IoSession session, Object message);
245 
246         /**
247          * Forwards <tt>messageSent</tt> event to next filter.
248          */
249         void messageSent(IoSession session, WriteRequest writeRequest);
250 
251         /**
252          * Forwards <tt>filterWrite</tt> event to next filter.
253          */
254         void filterWrite(IoSession session, WriteRequest writeRequest);
255 
256         /**
257          * Forwards <tt>filterClose</tt> event to next filter.
258          */
259         void filterClose(IoSession session);
260         
261         /**
262          * Forwards <tt>filterSetTrafficMask</tt> event to next filter.
263          */
264         void filterSetTrafficMask(IoSession session, TrafficMask trafficMask);
265     }
266 }