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 The Apache MINA Project (dev@mina.apache.org)
76   * @version $Rev: 591770 $, $Date: 2007-11-04 13:22:44 +0100 (Sun, 04 Nov 2007) $
77   *
78   * @see IoFilterAdapter
79   */
80  public interface IoFilter {
81      /**
82       * Invoked by {@link ReferenceCountingFilter} when this filter
83       * is added to a {@link IoFilterChain} at the first time, so you can
84       * initialize shared resources.  Please note that this method is never
85       * called if you don't wrap a filter with {@link ReferenceCountingFilter}.
86       */
87      void init() throws Exception;
88  
89      /**
90       * Invoked by {@link ReferenceCountingFilter} when this filter
91       * is not used by any {@link IoFilterChain} anymore, so you can destroy
92       * shared resources.  Please note that this method is never called if
93       * you don't wrap a filter with {@link ReferenceCountingFilter}.
94       */
95      void destroy() throws Exception;
96  
97      /**
98       * Invoked before this filter is added to the specified <tt>parent</tt>.
99       * Please note that this method can be invoked more than once if
100      * this filter is added to more than one parents.  This method is not
101      * invoked before {@link #init()} is invoked.
102      *
103      * @param parent the parent who called this method
104      * @param name the name assigned to this filter
105      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
106      *                   this object until this filter is removed from the chain.
107      */
108     void onPreAdd(IoFilterChain parent, String name, NextFilter nextFilter)
109             throws Exception;
110 
111     /**
112      * Invoked after this filter is added to the specified <tt>parent</tt>.
113      * Please note that this method can be invoked more than once if
114      * this filter is added to more than one parents.  This method is not
115      * invoked before {@link #init()} is invoked.
116      *
117      * @param parent the parent who called this method
118      * @param name the name assigned to this filter
119      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
120      *                   this object until this filter is removed from the chain.
121      */
122     void onPostAdd(IoFilterChain parent, String name, NextFilter nextFilter)
123             throws Exception;
124 
125     /**
126      * Invoked before this filter is removed from the specified <tt>parent</tt>.
127      * Please note that this method can be invoked more than once if
128      * this filter is removed from more than one parents.
129      * This method is always invoked before {@link #destroy()} is invoked.
130      *
131      * @param parent the parent who called this method
132      * @param name the name assigned to this filter
133      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
134      *                   this object until this filter is removed from the chain.
135      */
136     void onPreRemove(IoFilterChain parent, String name, NextFilter nextFilter)
137             throws Exception;
138 
139     /**
140      * Invoked after this filter is removed from the specified <tt>parent</tt>.
141      * Please note that this method can be invoked more than once if
142      * this filter is removed from more than one parents.
143      * This method is always invoked before {@link #destroy()} is invoked.
144      *
145      * @param parent the parent who called this method
146      * @param name the name assigned to this filter
147      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
148      *                   this object until this filter is removed from the chain.
149      */
150     void onPostRemove(IoFilterChain parent, String name, NextFilter nextFilter)
151             throws Exception;
152 
153     /**
154      * Filters {@link IoHandler#sessionCreated(IoSession)} event.
155      */
156     void sessionCreated(NextFilter nextFilter, IoSession session)
157             throws Exception;
158 
159     /**
160      * Filters {@link IoHandler#sessionOpened(IoSession)} event.
161      */
162     void sessionOpened(NextFilter nextFilter, IoSession session)
163             throws Exception;
164 
165     /**
166      * Filters {@link IoHandler#sessionClosed(IoSession)} event.
167      */
168     void sessionClosed(NextFilter nextFilter, IoSession session)
169             throws Exception;
170 
171     /**
172      * Filters {@link IoHandler#sessionIdle(IoSession,IdleStatus)}
173      * event.
174      */
175     void sessionIdle(NextFilter nextFilter, IoSession session, IdleStatus status)
176             throws Exception;
177 
178     /**
179      * Filters {@link IoHandler#exceptionCaught(IoSession,Throwable)}
180      * event.
181      */
182     void exceptionCaught(NextFilter nextFilter, IoSession session,
183             Throwable cause) throws Exception;
184 
185     /**
186      * Filters {@link IoHandler#messageReceived(IoSession,Object)}
187      * event.
188      */
189     void messageReceived(NextFilter nextFilter, IoSession session,
190             Object message) throws Exception;
191 
192     /**
193      * Filters {@link IoHandler#messageSent(IoSession,Object)}
194      * event.
195      */
196     void messageSent(NextFilter nextFilter, IoSession session,
197             WriteRequest writeRequest) throws Exception;
198 
199     /**
200      * Filters {@link IoSession#close()} method invocation.
201      */
202     void filterClose(NextFilter nextFilter, IoSession session) throws Exception;
203 
204     /**
205      * Filters {@link IoSession#write(Object)} method invocation.
206      */
207     void filterWrite(NextFilter nextFilter, IoSession session,
208             WriteRequest writeRequest) throws Exception;
209     
210     /**
211      * Represents the next {@link IoFilter} in {@link IoFilterChain}.
212      */
213     public interface NextFilter {
214         /**
215          * Forwards <tt>sessionCreated</tt> event to next filter.
216          */
217         void sessionCreated(IoSession session);
218 
219         /**
220          * Forwards <tt>sessionOpened</tt> event to next filter.
221          */
222         void sessionOpened(IoSession session);
223 
224         /**
225          * Forwards <tt>sessionClosed</tt> event to next filter.
226          */
227         void sessionClosed(IoSession session);
228 
229         /**
230          * Forwards <tt>sessionIdle</tt> event to next filter.
231          */
232         void sessionIdle(IoSession session, IdleStatus status);
233 
234         /**
235          * Forwards <tt>exceptionCaught</tt> event to next filter.
236          */
237         void exceptionCaught(IoSession session, Throwable cause);
238 
239         /**
240          * Forwards <tt>messageReceived</tt> event to next filter.
241          */
242         void messageReceived(IoSession session, Object message);
243 
244         /**
245          * Forwards <tt>messageSent</tt> event to next filter.
246          */
247         void messageSent(IoSession session, WriteRequest writeRequest);
248 
249         /**
250          * Forwards <tt>filterWrite</tt> event to next filter.
251          */
252         void filterWrite(IoSession session, WriteRequest writeRequest);
253 
254         /**
255          * Forwards <tt>filterClose</tt> event to next filter.
256          */
257         void filterClose(IoSession session);
258         
259     }
260 }