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.core.filterchain;
21  
22  import org.apache.mina.core.service.IoHandler;
23  import org.apache.mina.core.session.IdleStatus;
24  import org.apache.mina.core.session.IoSession;
25  import org.apache.mina.core.write.WriteRequest;
26  import org.apache.mina.filter.util.ReferenceCountingFilter;
27  
28  /**
29   * A filter which intercepts {@link IoHandler} events like Servlet
30   * filters.  Filters can be used for these purposes:
31   * <ul>
32   *   <li>Event logging,</li>
33   *   <li>Performance measurement,</li>
34   *   <li>Authorization,</li>
35   *   <li>Overload control,</li>
36   *   <li>Message transformation (e.g. encryption and decryption, ...),</li>
37   *   <li>and many more.</li>
38   * </ul>
39   * <p>
40   * <strong>Please NEVER implement your filters to wrap
41   * {@link IoSession}s.</strong> Users can cache the reference to the
42   * session, which might malfunction if any filters are added or removed later.
43   *
44   * <h3>The Life Cycle</h3>
45   * {@link IoFilter}s are activated only when they are inside {@link IoFilterChain}.
46   * <p>
47   * When you add an {@link IoFilter} to an {@link IoFilterChain}:
48   * <ol>
49   *   <li>{@link #init()} is invoked by {@link ReferenceCountingFilter} if
50   *       the filter is added at the first time.</li>
51   *   <li>{@link #onPreAdd(IoFilterChain, String, NextFilter)} is invoked to notify
52   *       that the filter will be added to the chain.</li>
53   *   <li>The filter is added to the chain, and all events and I/O requests
54   *       pass through the filter from now.</li>
55   *   <li>{@link #onPostAdd(IoFilterChain, String, NextFilter)} is invoked to notify
56   *       that the filter is added to the chain.</li>
57   *   <li>The filter is removed from the chain if {@link #onPostAdd(IoFilterChain, String, org.apache.mina.core.filterchain.IoFilter.NextFilter)}
58   *       threw an exception.  {@link #destroy()} is also invoked by
59   *       {@link ReferenceCountingFilter} if the filter is the last filter which
60   *       was added to {@link IoFilterChain}s.</li>
61   * </ol>
62   * <p>
63   * When you remove an {@link IoFilter} from an {@link IoFilterChain}:
64   * <ol>
65   *   <li>{@link #onPreRemove(IoFilterChain, String, NextFilter)} is invoked to
66   *       notify that the filter will be removed from the chain.</li>
67   *   <li>The filter is removed from the chain, and any events and I/O requests
68   *       don't pass through the filter from now.</li>
69   *   <li>{@link #onPostRemove(IoFilterChain, String, NextFilter)} is invoked to
70   *       notify that the filter is removed from the chain.</li>
71   *   <li>{@link #destroy()} is invoked by {@link ReferenceCountingFilter} if
72   *       the removed filter was the last one.</li>
73   * </ol>
74   *
75   * @author <a href="http://mina.apache.org">Apache MINA Project</a>
76   *
77   * @see IoFilterAdapter
78   */
79  public interface IoFilter {
80      /**
81       * Invoked by {@link ReferenceCountingFilter} when this filter
82       * is added to a {@link IoFilterChain} at the first time, so you can
83       * initialize shared resources.  Please note that this method is never
84       * called if you don't wrap a filter with {@link ReferenceCountingFilter}.
85       */
86      void init() throws Exception;
87  
88      /**
89       * Invoked by {@link ReferenceCountingFilter} when this filter
90       * is not used by any {@link IoFilterChain} anymore, so you can destroy
91       * shared resources.  Please note that this method is never called if
92       * you don't wrap a filter with {@link ReferenceCountingFilter}.
93       */
94      void destroy() throws Exception;
95  
96      /**
97       * Invoked before this filter is added to the specified <tt>parent</tt>.
98       * Please note that this method can be invoked more than once if
99       * this filter is added to more than one parents.  This method is not
100      * invoked before {@link #init()} is invoked.
101      *
102      * @param parent the parent who called this method
103      * @param name the name assigned to this filter
104      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
105      *                   this object until this filter is removed from the chain.
106      */
107     void onPreAdd(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
108 
109     /**
110      * Invoked after this filter is added to the specified <tt>parent</tt>.
111      * Please note that this method can be invoked more than once if
112      * this filter is added to more than one parents.  This method is not
113      * invoked before {@link #init()} is invoked.
114      *
115      * @param parent the parent who called this method
116      * @param name the name assigned to this filter
117      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
118      *                   this object until this filter is removed from the chain.
119      */
120     void onPostAdd(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
121 
122     /**
123      * Invoked before this filter is removed from the specified <tt>parent</tt>.
124      * Please note that this method can be invoked more than once if
125      * this filter is removed from more than one parents.
126      * This method is always invoked before {@link #destroy()} is invoked.
127      *
128      * @param parent the parent who called this method
129      * @param name the name assigned to this filter
130      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
131      *                   this object until this filter is removed from the chain.
132      */
133     void onPreRemove(IoFilterChain parent, String name, NextFilter nextFilter) 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) throws Exception;
147 
148     /**
149      * Filters {@link IoHandler#sessionCreated(IoSession)} event.
150      * 
151      * @param nextFilter
152      *            the {@link NextFilter} for this filter. You can reuse this
153      *            object until this filter is removed from the chain.
154      * @param session
155      *            The {@link IoSession} which has received this event
156      */
157     void sessionCreated(NextFilter nextFilter, IoSession session) throws Exception;
158 
159     /**
160      * Filters {@link IoHandler#sessionOpened(IoSession)} event.
161      * 
162      * @param nextFilter
163      *            the {@link NextFilter} for this filter. You can reuse this
164      *            object until this filter is removed from the chain.
165      * @param session
166      *            The {@link IoSession} which has received this event
167      */
168     void sessionOpened(NextFilter nextFilter, IoSession session) throws Exception;
169 
170     /**
171      * Filters {@link IoHandler#sessionClosed(IoSession)} event.
172      * 
173      * @param nextFilter
174      *            the {@link NextFilter} for this filter. You can reuse this
175      *            object until this filter is removed from the chain.
176      * @param session
177      *            The {@link IoSession} which has received this event
178      */
179     void sessionClosed(NextFilter nextFilter, IoSession session) throws Exception;
180 
181     /**
182      * Filters {@link IoHandler#sessionIdle(IoSession,IdleStatus)} event.
183      * 
184      * @param nextFilter
185      *            the {@link NextFilter} for this filter. You can reuse this
186      *            object until this filter is removed from the chain.
187      * @param session
188      *            The {@link IoSession} which has received this event
189      * @param status
190      *            The {@link IdleStatus} type
191      */
192     void sessionIdle(NextFilter nextFilter, IoSession session, IdleStatus status) throws Exception;
193 
194     /**
195      * Filters {@link IoHandler#exceptionCaught(IoSession,Throwable)} event.
196      * 
197      * @param nextFilter
198      *            the {@link NextFilter} for this filter. You can reuse this
199      *            object until this filter is removed from the chain.
200      * @param session
201      *            The {@link IoSession} which has received this event
202      * @param cause
203      *            The exception that cause this event to be received
204      */
205     void exceptionCaught(NextFilter nextFilter, IoSession session, Throwable cause) throws Exception;
206 
207     /**
208      * Filters {@link IoHandler#inputClosed(IoSession)} event.
209      * 
210      * @param nextFilter
211      *            the {@link NextFilter} for this filter. You can reuse this
212      *            object until this filter is removed from the chain.
213      * @param session
214      *            The {@link IoSession} which has received this event
215      */
216     void inputClosed(NextFilter nextFilter, IoSession session) throws Exception;
217 
218     /**
219      * Filters {@link IoHandler#messageReceived(IoSession,Object)} event.
220      * 
221      * @param nextFilter
222      *            the {@link NextFilter} for this filter. You can reuse this
223      *            object until this filter is removed from the chain.
224      * @param session
225      *            The {@link IoSession} which has received this event
226      * @param message
227      *            The received message
228      */
229     void messageReceived(NextFilter nextFilter, IoSession session, Object message) throws Exception;
230 
231     /**
232      * Filters {@link IoHandler#messageSent(IoSession,Object)} event.
233      * 
234      * @param nextFilter
235      *            the {@link NextFilter} for this filter. You can reuse this
236      *            object until this filter is removed from the chain.
237      * @param session
238      *            The {@link IoSession} which has received this event
239      * @param writeRequest
240      *            The {@link WriteRequest} that contains the sent message
241      */
242     void messageSent(NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws Exception;
243 
244     /**
245      * Filters {@link IoSession#close()} method invocation.
246      * 
247      * @param nextFilter
248      *            the {@link NextFilter} for this filter. You can reuse this
249      *            object until this filter is removed from the chain.
250      * @param session
251      *            The {@link IoSession} which has to process this method
252      *            invocation
253      */
254     void filterClose(NextFilter nextFilter, IoSession session) throws Exception;
255 
256     /**
257      * Filters {@link IoSession#write(Object)} method invocation.
258      * 
259      * @param nextFilter
260      *            the {@link NextFilter} for this filter. You can reuse this
261      *            object until this filter is removed from the chain.
262      * @param session
263      *            The {@link IoSession} which has to process this invocation
264      * @param writeRequest
265      *            The {@link WriteRequest} to process
266      */
267     void filterWrite(NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws Exception;
268 
269     /**
270      * Represents the next {@link IoFilter} in {@link IoFilterChain}.
271      */
272     public interface NextFilter {
273         /**
274          * Forwards <tt>sessionCreated</tt> event to next filter.
275          */
276         void sessionCreated(IoSession session);
277 
278         /**
279          * Forwards <tt>sessionOpened</tt> event to next filter.
280          */
281         void sessionOpened(IoSession session);
282 
283         /**
284          * Forwards <tt>sessionClosed</tt> event to next filter.
285          */
286         void sessionClosed(IoSession session);
287 
288         /**
289          * Forwards <tt>sessionIdle</tt> event to next filter.
290          */
291         void sessionIdle(IoSession session, IdleStatus status);
292 
293         /**
294          * Forwards <tt>exceptionCaught</tt> event to next filter.
295          */
296         void exceptionCaught(IoSession session, Throwable cause);
297 
298         void inputClosed(IoSession session);
299 
300         /**
301          * Forwards <tt>messageReceived</tt> event to next filter.
302          */
303         void messageReceived(IoSession session, Object message);
304 
305         /**
306          * Forwards <tt>messageSent</tt> event to next filter.
307          */
308         void messageSent(IoSession session, WriteRequest writeRequest);
309 
310         /**
311          * Forwards <tt>filterWrite</tt> event to next filter.
312          */
313         void filterWrite(IoSession session, WriteRequest writeRequest);
314 
315         /**
316          * Forwards <tt>filterClose</tt> event to next filter.
317          */
318         void filterClose(IoSession session);
319 
320     }
321 }