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