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 * @throws Exception If an error occurred while processing the event
87 */
88 void init() throws Exception;
89
90 /**
91 * Invoked by {@link ReferenceCountingFilter} when this filter
92 * is not used by any {@link IoFilterChain} anymore, so you can destroy
93 * shared resources. Please note that this method is never called if
94 * you don't wrap a filter with {@link ReferenceCountingFilter}.
95 *
96 * @throws Exception If an error occurred while processing the event
97 */
98 void destroy() throws Exception;
99
100 /**
101 * Invoked before this filter is added to the specified <tt>parent</tt>.
102 * Please note that this method can be invoked more than once if
103 * this filter is added to more than one parents. This method is not
104 * invoked before {@link #init()} is invoked.
105 *
106 * @param parent the parent who called this method
107 * @param name the name assigned to this filter
108 * @param nextFilter the {@link NextFilter} for this filter. You can reuse
109 * this object until this filter is removed from the chain.
110 * @throws Exception If an error occurred while processing the event
111 */
112 void onPreAdd(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
113
114 /**
115 * Invoked after this filter is added to the specified <tt>parent</tt>.
116 * Please note that this method can be invoked more than once if
117 * this filter is added to more than one parents. This method is not
118 * invoked before {@link #init()} is invoked.
119 *
120 * @param parent the parent who called this method
121 * @param name the name assigned to this filter
122 * @param nextFilter the {@link NextFilter} for this filter. You can reuse
123 * this object until this filter is removed from the chain.
124 * @throws Exception If an error occurred while processing the event
125 */
126 void onPostAdd(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
127
128 /**
129 * Invoked before this filter is removed from the specified <tt>parent</tt>.
130 * Please note that this method can be invoked more than once if
131 * this filter is removed from more than one parents.
132 * This method is always invoked before {@link #destroy()} is invoked.
133 *
134 * @param parent the parent who called this method
135 * @param name the name assigned to this filter
136 * @param nextFilter the {@link NextFilter} for this filter. You can reuse
137 * this object until this filter is removed from the chain.
138 * @throws Exception If an error occurred while processing the event
139 */
140 void onPreRemove(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
141
142 /**
143 * Invoked after this filter is removed from the specified <tt>parent</tt>.
144 * Please note that this method can be invoked more than once if
145 * this filter is removed from more than one parents.
146 * This method is always invoked before {@link #destroy()} is invoked.
147 *
148 * @param parent the parent who called this method
149 * @param name the name assigned to this filter
150 * @param nextFilter the {@link NextFilter} for this filter. You can reuse
151 * this object until this filter is removed from the chain.
152 * @throws Exception If an error occurred while processing the event
153 */
154 void onPostRemove(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
155
156 /**
157 * Filters {@link IoHandler#sessionCreated(IoSession)} event.
158 *
159 * @param nextFilter
160 * the {@link NextFilter} for this filter. You can reuse this
161 * object until this filter is removed from the chain.
162 * @param session The {@link IoSession} which has received this event
163 * @throws Exception If an error occurred while processing the event
164 */
165 void sessionCreated(NextFilter nextFilter, IoSession session) throws Exception;
166
167 /**
168 * Filters {@link IoHandler#sessionOpened(IoSession)} event.
169 *
170 * @param nextFilter
171 * the {@link NextFilter} for this filter. You can reuse this
172 * object until this filter is removed from the chain.
173 * @param session The {@link IoSession} which has received this event
174 * @throws Exception If an error occurred while processing the event
175 */
176 void sessionOpened(NextFilter nextFilter, IoSession session) throws Exception;
177
178 /**
179 * Filters {@link IoHandler#sessionClosed(IoSession)} event.
180 *
181 * @param nextFilter
182 * the {@link NextFilter} for this filter. You can reuse this
183 * object until this filter is removed from the chain.
184 * @param session The {@link IoSession} which has received this event
185 * @throws Exception If an error occurred while processing the event
186 */
187 void sessionClosed(NextFilter nextFilter, IoSession session) throws Exception;
188
189 /**
190 * Filters {@link IoHandler#sessionIdle(IoSession,IdleStatus)} event.
191 *
192 * @param nextFilter
193 * the {@link NextFilter} for this filter. You can reuse this
194 * object until this filter is removed from the chain.
195 * @param session The {@link IoSession} which has received this event
196 * @param status The {@link IdleStatus} type
197 * @throws Exception If an error occurred while processing the event
198 */
199 void sessionIdle(NextFilter nextFilter, IoSession session, IdleStatus status) throws Exception;
200
201 /**
202 * Filters {@link IoHandler#exceptionCaught(IoSession,Throwable)} event.
203 *
204 * @param nextFilter
205 * the {@link NextFilter} for this filter. You can reuse this
206 * object until this filter is removed from the chain.
207 * @param session The {@link IoSession} which has received this event
208 * @param cause The exception that cause this event to be received
209 * @throws Exception If an error occurred while processing the event
210 */
211 void exceptionCaught(NextFilter nextFilter, IoSession session, Throwable cause) throws Exception;
212
213 /**
214 * Filters {@link IoHandler#inputClosed(IoSession)} event.
215 *
216 * @param nextFilter
217 * the {@link NextFilter} for this filter. You can reuse this
218 * object until this filter is removed from the chain.
219 * @param session The {@link IoSession} which has received this event
220 * @throws Exception If an error occurred while processing the event
221 */
222 void inputClosed(NextFilter nextFilter, IoSession session) throws Exception;
223
224 /**
225 * Filters {@link IoHandler#messageReceived(IoSession,Object)} event.
226 *
227 * @param nextFilter
228 * the {@link NextFilter} for this filter. You can reuse this
229 * object until this filter is removed from the chain.
230 * @param session The {@link IoSession} which has received this event
231 * @param message The received message
232 * @throws Exception If an error occurred while processing the event
233 */
234 void messageReceived(NextFilter nextFilter, IoSession session, Object message) throws Exception;
235
236 /**
237 * Filters {@link IoHandler#messageSent(IoSession,Object)} event.
238 *
239 * @param nextFilter
240 * the {@link NextFilter} for this filter. You can reuse this
241 * object until this filter is removed from the chain.
242 * @param session The {@link IoSession} which has received this event
243 * @param writeRequest The {@link WriteRequest} that contains the sent message
244 * @throws Exception If an error occurred while processing the event
245 */
246 void messageSent(NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws Exception;
247
248 /**
249 * Filters {@link IoSession#closeNow()} or a {@link IoSession#closeOnFlush()} method invocations.
250 *
251 * @param nextFilter
252 * the {@link NextFilter} for this filter. You can reuse this
253 * object until this filter is removed from the chain.
254 * @param session
255 * The {@link IoSession} which has to process this method
256 * invocation
257 * @throws Exception If an error occurred while processing the event
258 */
259 void filterClose(NextFilter nextFilter, IoSession session) throws Exception;
260
261 /**
262 * Filters {@link IoSession#write(Object)} method invocation.
263 *
264 * @param nextFilter
265 * the {@link NextFilter} for this filter. You can reuse this
266 * object until this filter is removed from the chain.
267 * @param session The {@link IoSession} which has to process this invocation
268 * @param writeRequest The {@link WriteRequest} to process
269 * @throws Exception If an error occurred while processing the event
270 */
271 void filterWrite(NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws Exception;
272
273 /**
274 * Represents the next {@link IoFilter} in {@link IoFilterChain}.
275 */
276 interface NextFilter {
277 /**
278 * Forwards <tt>sessionCreated</tt> event to next filter.
279 *
280 * @param session The {@link IoSession} which has to process this invocation
281 */
282 void sessionCreated(IoSession session);
283
284 /**
285 * Forwards <tt>sessionOpened</tt> event to next filter.
286 *
287 * @param session The {@link IoSession} which has to process this invocation
288 */
289 void sessionOpened(IoSession session);
290
291 /**
292 * Forwards <tt>sessionClosed</tt> event to next filter.
293 *
294 * @param session The {@link IoSession} which has to process this invocation
295 */
296 void sessionClosed(IoSession session);
297
298 /**
299 * Forwards <tt>sessionIdle</tt> event to next filter.
300 *
301 * @param session The {@link IoSession} which has to process this invocation
302 * @param status The {@link IdleStatus} type
303 */
304 void sessionIdle(IoSession session, IdleStatus status);
305
306 /**
307 * Forwards <tt>exceptionCaught</tt> event to next filter.
308 *
309 * @param session The {@link IoSession} which has to process this invocation
310 * @param cause The exception that cause this event to be received
311 */
312 void exceptionCaught(IoSession session, Throwable cause);
313
314 /**
315 *
316 * @param session The {@link IoSession} which has to process this invocation
317 */
318 void inputClosed(IoSession session);
319
320 /**
321 * Forwards <tt>messageReceived</tt> event to next filter.
322 *
323 * @param session The {@link IoSession} which has to process this invocation
324 * @param message The received message
325 */
326 void messageReceived(IoSession session, Object message);
327
328 /**
329 * Forwards <tt>messageSent</tt> event to next filter.
330 *
331 * @param session The {@link IoSession} which has to process this invocation
332 * @param writeRequest The {@link WriteRequest} to process
333 */
334 void messageSent(IoSession session, WriteRequest writeRequest);
335
336 /**
337 * Forwards <tt>filterWrite</tt> event to next filter.
338 *
339 * @param session The {@link IoSession} which has to process this invocation
340 * @param writeRequest The {@link WriteRequest} to process
341 */
342 void filterWrite(IoSession session, WriteRequest writeRequest);
343
344 /**
345 * Forwards <tt>filterClose</tt> event to next filter.
346 *
347 * @param session The {@link IoSession} which has to process this invocation
348 */
349 void filterClose(IoSession session);
350 }
351 }