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 *
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)
108 throws Exception;
109
110 /**
111 * Invoked after this filter is added to the specified <tt>parent</tt>.
112 * Please note that this method can be invoked more than once if
113 * this filter is added to more than one parents. This method is not
114 * invoked before {@link #init()} is invoked.
115 *
116 * @param parent the parent who called this method
117 * @param name the name assigned to this filter
118 * @param nextFilter the {@link NextFilter} for this filter. You can reuse
119 * this object until this filter is removed from the chain.
120 */
121 void onPostAdd(IoFilterChain parent, String name, NextFilter nextFilter)
122 throws Exception;
123
124 /**
125 * Invoked before this filter is removed from the specified <tt>parent</tt>.
126 * Please note that this method can be invoked more than once if
127 * this filter is removed from more than one parents.
128 * This method is always invoked before {@link #destroy()} is invoked.
129 *
130 * @param parent the parent who called this method
131 * @param name the name assigned to this filter
132 * @param nextFilter the {@link NextFilter} for this filter. You can reuse
133 * this object until this filter is removed from the chain.
134 */
135 void onPreRemove(IoFilterChain parent, String name, NextFilter nextFilter)
136 throws Exception;
137
138 /**
139 * Invoked after this filter is removed from the specified <tt>parent</tt>.
140 * Please note that this method can be invoked more than once if
141 * this filter is removed from more than one parents.
142 * This method is always invoked before {@link #destroy()} is invoked.
143 *
144 * @param parent the parent who called this method
145 * @param name the name assigned to this filter
146 * @param nextFilter the {@link NextFilter} for this filter. You can reuse
147 * this object until this filter is removed from the chain.
148 */
149 void onPostRemove(IoFilterChain parent, String name, NextFilter nextFilter)
150 throws Exception;
151
152 /**
153 * Filters {@link IoHandler#sessionCreated(IoSession)} event.
154 */
155 void sessionCreated(NextFilter nextFilter, IoSession session)
156 throws Exception;
157
158 /**
159 * Filters {@link IoHandler#sessionOpened(IoSession)} event.
160 */
161 void sessionOpened(NextFilter nextFilter, IoSession session)
162 throws Exception;
163
164 /**
165 * Filters {@link IoHandler#sessionClosed(IoSession)} event.
166 */
167 void sessionClosed(NextFilter nextFilter, IoSession session)
168 throws Exception;
169
170 /**
171 * Filters {@link IoHandler#sessionIdle(IoSession,IdleStatus)}
172 * event.
173 */
174 void sessionIdle(NextFilter nextFilter, IoSession session, IdleStatus status)
175 throws Exception;
176
177 /**
178 * Filters {@link IoHandler#exceptionCaught(IoSession,Throwable)}
179 * event.
180 */
181 void exceptionCaught(NextFilter nextFilter, IoSession session,
182 Throwable cause) throws Exception;
183
184 /**
185 * Filters {@link IoHandler#messageReceived(IoSession,Object)}
186 * event.
187 */
188 void messageReceived(NextFilter nextFilter, IoSession session,
189 Object message) throws Exception;
190
191 /**
192 * Filters {@link IoHandler#messageSent(IoSession,Object)}
193 * event.
194 */
195 void messageSent(NextFilter nextFilter, IoSession session,
196 WriteRequest writeRequest) throws Exception;
197
198 /**
199 * Filters {@link IoSession#close()} method invocation.
200 */
201 void filterClose(NextFilter nextFilter, IoSession session) throws Exception;
202
203 /**
204 * Filters {@link IoSession#write(Object)} method invocation.
205 */
206 void filterWrite(NextFilter nextFilter, IoSession session,
207 WriteRequest writeRequest) throws Exception;
208
209 /**
210 * Represents the next {@link IoFilter} in {@link IoFilterChain}.
211 */
212 public interface NextFilter {
213 /**
214 * Forwards <tt>sessionCreated</tt> event to next filter.
215 */
216 void sessionCreated(IoSession session);
217
218 /**
219 * Forwards <tt>sessionOpened</tt> event to next filter.
220 */
221 void sessionOpened(IoSession session);
222
223 /**
224 * Forwards <tt>sessionClosed</tt> event to next filter.
225 */
226 void sessionClosed(IoSession session);
227
228 /**
229 * Forwards <tt>sessionIdle</tt> event to next filter.
230 */
231 void sessionIdle(IoSession session, IdleStatus status);
232
233 /**
234 * Forwards <tt>exceptionCaught</tt> event to next filter.
235 */
236 void exceptionCaught(IoSession session, Throwable cause);
237
238 /**
239 * Forwards <tt>messageReceived</tt> event to next filter.
240 */
241 void messageReceived(IoSession session, Object message);
242
243 /**
244 * Forwards <tt>messageSent</tt> event to next filter.
245 */
246 void messageSent(IoSession session, WriteRequest writeRequest);
247
248 /**
249 * Forwards <tt>filterWrite</tt> event to next filter.
250 */
251 void filterWrite(IoSession session, WriteRequest writeRequest);
252
253 /**
254 * Forwards <tt>filterClose</tt> event to next filter.
255 */
256 void filterClose(IoSession session);
257
258 }
259 }