KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > mina > common > IoFilter


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 java.net.SocketAddress JavaDoc;
23
24 import org.apache.mina.filter.ReferenceCountingIoFilter;
25
26 /**
27  * A filter which intercepts {@link IoHandler} events like Servlet
28  * filters. Filters can be used for these purposes:
29  * <ul>
30  * <li>Event logging,</li>
31  * <li>Performance measurement,</li>
32  * <li>Authorization,</li>
33  * <li>Overload control,</li>
34  * <li>Message transformation (e.g. encryption and decryption, ...),</li>
35  * <li>and many more.</li>
36  * </ul>
37  * <p>
38  * <strong>Please NEVER implement your filters to wrap
39  * {@link IoSession}s.</strong> Users can cache the reference to the
40  * session, which might malfunction if any filters are added or removed later.
41  *
42  * <h3>The Life Cycle</h3>
43  * {@link IoFilter}s are activated only when they are inside {@link IoFilterChain}.
44  * <p>
45  * When you add an {@link IoFilter} to an {@link IoFilterChain}:
46  * <ol>
47  * <li>{@link #init()} is invoked by {@link ReferenceCountingIoFilter} if
48  * the filter is added at the first time.</li>
49  * <li>{@link #onPreAdd(IoFilterChain, String, NextFilter)} is invoked to notify
50  * that the filter will be added to the chain.</li>
51  * <li>The filter is added to the chain, and all events and I/O requests
52  * pass through the filter from now.</li>
53  * <li>{@link #onPostAdd(IoFilterChain, String, NextFilter)} is invoked to notify
54  * that the filter is added to the chain.</li>
55  * <li>The filter is removed from the chain if {@link #onPostAdd(IoFilterChain, String, org.apache.mina.common.IoFilter.NextFilter)}
56  * threw an exception. {@link #destroy()} is also invoked by
57  * {@link ReferenceCountingIoFilter} if the filter is the last filter which
58  * was added to {@link IoFilterChain}s.</li>
59  * </ol>
60  * <p>
61  * When you remove an {@link IoFilter} from an {@link IoFilterChain}:
62  * <ol>
63  * <li>{@link #onPreRemove(IoFilterChain, String, NextFilter)} is invoked to
64  * notify that the filter will be removed from the chain.</li>
65  * <li>The filter is removed from the chain, and any events and I/O requests
66  * don't pass through the filter from now.</li>
67  * <li>{@link #onPostRemove(IoFilterChain, String, NextFilter)} is invoked to
68  * notify that the filter is removed from the chain.</li>
69  * <li>{@link #destroy()} is invoked by {@link ReferenceCountingIoFilter} if
70  * the removed filter was the last one.</li>
71  * </ol>
72  *
73  * @author The Apache Directory Project (mina-dev@directory.apache.org)
74  * @version $Rev: 555855 $, $Date: 2007-07-13 12:19:00 +0900 (금, 13 7월 2007) $
75  *
76  * @see IoFilterAdapter
77  */

78 public interface IoFilter {
79     /**
80      * Invoked by {@link ReferenceCountingIoFilter} when this filter
81      * is added to a {@link IoFilterChain} at the first time, so you can
82      * initialize shared resources. Please note that this method is never
83      * called if you don't wrap a filter with {@link ReferenceCountingIoFilter}.
84      */

85     void init() throws Exception JavaDoc;
86
87     /**
88      * Invoked by {@link ReferenceCountingIoFilter} when this filter
89      * is not used by any {@link IoFilterChain} anymore, so you can destroy
90      * shared resources. Please note that this method is never called if
91      * you don't wrap a filter with {@link ReferenceCountingIoFilter}.
92      */

93     void destroy() throws Exception JavaDoc;
94
95     /**
96      * Invoked before this filter is added to the specified <tt>parent</tt>.
97      * Please note that this method can be invoked more than once if
98      * this filter is added to more than one parents. This method is not
99      * invoked before {@link #init()} is invoked.
100      *
101      * @param parent the parent who called this method
102      * @param name the name assigned to this filter
103      * @param nextFilter the {@link NextFilter} for this filter. You can reuse
104      * this object until this filter is removed from the chain.
105      */

106     void onPreAdd(IoFilterChain parent, String JavaDoc name, NextFilter nextFilter)
107             throws Exception JavaDoc;
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 JavaDoc name, NextFilter nextFilter)
121             throws Exception JavaDoc;
122
123     /**
124      * Invoked before this filter is removed from the specified <tt>parent</tt>.
125      * Please note that this method can be invoked more than once if
126      * this filter is removed from more than one parents.
127      * This method is always invoked before {@link #destroy()} is invoked.
128      *
129      * @param parent the parent who called this method
130      * @param name the name assigned to this filter
131      * @param nextFilter the {@link NextFilter} for this filter. You can reuse
132      * this object until this filter is removed from the chain.
133      */

134     void onPreRemove(IoFilterChain parent, String JavaDoc name, NextFilter nextFilter)
135             throws Exception JavaDoc;
136
137     /**
138      * Invoked after this filter is removed from the specified <tt>parent</tt>.
139      * Please note that this method can be invoked more than once if
140      * this filter is removed from more than one parents.
141      * This method is always invoked before {@link #destroy()} is invoked.
142      *
143      * @param parent the parent who called this method
144      * @param name the name assigned to this filter
145      * @param nextFilter the {@link NextFilter} for this filter. You can reuse
146      * this object until this filter is removed from the chain.
147      */

148     void onPostRemove(IoFilterChain parent, String JavaDoc name, NextFilter nextFilter)
149             throws Exception JavaDoc;
150
151     /**
152      * Filters {@link IoHandler#sessionCreated(IoSession)} event.
153      */

154     void sessionCreated(NextFilter nextFilter, IoSession session)
155             throws Exception JavaDoc;
156
157     /**
158      * Filters {@link IoHandler#sessionOpened(IoSession)} event.
159      */

160     void sessionOpened(NextFilter nextFilter, IoSession session)
161             throws Exception JavaDoc;
162
163     /**
164      * Filters {@link IoHandler#sessionClosed(IoSession)} event.
165      */

166     void sessionClosed(NextFilter nextFilter, IoSession session)
167             throws Exception JavaDoc;
168
169     /**
170      * Filters {@link IoHandler#sessionIdle(IoSession,IdleStatus)}
171      * event.
172      */

173     void sessionIdle(NextFilter nextFilter, IoSession session, IdleStatus status)
174             throws Exception JavaDoc;
175
176     /**
177      * Filters {@link IoHandler#exceptionCaught(IoSession,Throwable)}
178      * event.
179      */

180     void exceptionCaught(NextFilter nextFilter, IoSession session,
181             Throwable JavaDoc cause) throws Exception JavaDoc;
182
183     /**
184      * Filters {@link IoHandler#messageReceived(IoSession,Object)}
185      * event.
186      */

187     void messageReceived(NextFilter nextFilter, IoSession session,
188             Object JavaDoc message) throws Exception JavaDoc;
189
190     /**
191      * Filters {@link IoHandler#messageSent(IoSession,Object)}
192      * event.
193      */

194     void messageSent(NextFilter nextFilter, IoSession session, Object JavaDoc message)
195             throws Exception JavaDoc;
196
197     /**
198      * Filters {@link IoSession#close()} method invocation.
199      */

200     void filterClose(NextFilter nextFilter, IoSession session) throws Exception JavaDoc;
201
202     /**
203      * Filters {@link IoSession#write(Object)} method invocation.
204      */

205     void filterWrite(NextFilter nextFilter, IoSession session,
206             WriteRequest writeRequest) throws Exception JavaDoc;
207
208     /**
209      * Represents the next {@link IoFilter} in {@link IoFilterChain}.
210      */

211     public interface NextFilter {
212         /**
213          * Forwards <tt>sessionCreated</tt> event to next filter.
214          */

215         void sessionCreated(IoSession session);
216
217         /**
218          * Forwards <tt>sessionOpened</tt> event to next filter.
219          */

220         void sessionOpened(IoSession session);
221
222         /**
223          * Forwards <tt>sessionClosed</tt> event to next filter.
224          */

225         void sessionClosed(IoSession session);
226
227         /**
228          * Forwards <tt>sessionIdle</tt> event to next filter.
229          */

230         void sessionIdle(IoSession session, IdleStatus status);
231
232         /**
233          * Forwards <tt>exceptionCaught</tt> event to next filter.
234          */

235         void exceptionCaught(IoSession session, Throwable JavaDoc cause);
236
237         /**
238          * Forwards <tt>messageReceived</tt> event to next filter.
239          */

240         void messageReceived(IoSession session, Object JavaDoc message);
241
242         /**
243          * Forwards <tt>messageSent</tt> event to next filter.
244          */

245         void messageSent(IoSession session, Object JavaDoc message);
246
247         /**
248          * Forwards <tt>filterWrite</tt> event to next filter.
249          */

250         void filterWrite(IoSession session, WriteRequest writeRequest);
251
252         /**
253          * Forwards <tt>filterClose</tt> event to next filter.
254          */

255         void filterClose(IoSession session);
256     }
257
258     /**
259      * Represents write request fired by {@link IoSession#write(Object)}.
260      */

261     public static class WriteRequest {
262         private static final WriteFuture UNUSED_FUTURE = new WriteFuture() {
263             public boolean isWritten() {
264                 return false;
265             }
266
267             public void setWritten(boolean written) {
268             }
269
270             public IoSession getSession() {
271                 return null;
272             }
273
274             public void join() {
275             }
276
277             public boolean join(long timeoutInMillis) {
278                 return true;
279             }
280
281             public boolean isReady() {
282                 return true;
283             }
284
285             public void addListener(IoFutureListener listener) {
286                 throw new IllegalStateException JavaDoc(
287                         "You can't add a listener to a dummy future.");
288             }
289
290             public void removeListener(IoFutureListener listener) {
291                 throw new IllegalStateException JavaDoc(
292                         "You can't add a listener to a dummy future.");
293             }
294         };
295
296         private final Object JavaDoc message;
297
298         private final WriteFuture future;
299
300         private final SocketAddress JavaDoc destination;
301
302         /**
303          * Creates a new instance without {@link WriteFuture}. You'll get
304          * an instance of {@link WriteFuture} even if you called this constructor
305          * because {@link #getFuture()} will return a bogus future.
306          */

307         public WriteRequest(Object JavaDoc message) {
308             this(message, null, null);
309         }
310
311         /**
312          * Creates a new instance with {@link WriteFuture}.
313          */

314         public WriteRequest(Object JavaDoc message, WriteFuture future) {
315             this(message, future, null);
316         }
317
318         /**
319          * Creates a new instance.
320          *
321          * @param message a message to write
322          * @param future a future that needs to be notified when an operation is finished
323          * @param destination the destination of the message. This property will be
324          * ignored unless the transport supports it.
325          */

326         public WriteRequest(Object JavaDoc message, WriteFuture future,
327                 SocketAddress JavaDoc destination) {
328             if (message == null) {
329                 throw new NullPointerException JavaDoc("message");
330             }
331
332             if (future == null) {
333                 future = UNUSED_FUTURE;
334             }
335
336             this.message = message;
337             this.future = future;
338             this.destination = destination;
339         }
340
341         /**
342          * Returns {@link WriteFuture} that is associated with this write request.
343          */

344         public WriteFuture getFuture() {
345             return future;
346         }
347
348         /**
349          * Returns a message object to be written.
350          */

351         public Object JavaDoc getMessage() {
352             return message;
353         }
354
355         /**
356          * Returne the destination of this write request.
357          *
358          * @return <tt>null</tt> for the default destination
359          */

360         public SocketAddress JavaDoc getDestination() {
361             return destination;
362         }
363
364         public String JavaDoc toString() {
365             return message.toString();
366         }
367     }
368 }
369
Popular Tags