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 java.util.List;
23
24 import org.apache.mina.core.filterchain.IoFilter.NextFilter;
25 import org.apache.mina.core.service.IoHandler;
26 import org.apache.mina.core.session.IdleStatus;
27 import org.apache.mina.core.session.IoSession;
28 import org.apache.mina.core.session.TrafficMask;
29 import org.apache.mina.core.write.WriteRequest;
30
31 /**
32 * A container of {@link IoFilter}s that forwards {@link IoHandler} events
33 * to the consisting filters and terminal {@link IoHandler} sequentially.
34 * Every {@link IoSession} has its own {@link IoFilterChain} (1-to-1 relationship).
35 *
36 * @author The Apache MINA Project (dev@mina.apache.org)
37 * @version $Rev: 593474 $, $Date: 2007-11-09 11:14:12 +0100 (Fri, 09 Nov 2007) $
38 */
39 public interface IoFilterChain {
40 /**
41 * Returns the parent {@link IoSession} of this chain.
42 * @return {@link IoSession}
43 */
44 IoSession getSession();
45
46 /**
47 * Returns the {@link Entry} with the specified <tt>name</tt> in this chain.
48 * @return <tt>null</tt> if there's no such name in this chain
49 */
50 Entry getEntry(String name);
51
52 /**
53 * Returns the {@link Entry} with the specified <tt>filter</tt> in this chain.
54 * @return <tt>null</tt> if there's no such filter in this chain
55 */
56 Entry getEntry(IoFilter filter);
57
58 /**
59 * Returns the {@link Entry} with the specified <tt>filterType</tt>
60 * in this chain. If there's more than one filter with the specified
61 * type, the first match will be chosen.
62 * @return <tt>null</tt> if there's no such name in this chain
63 */
64 Entry getEntry(Class<? extends IoFilter> filterType);
65
66 /**
67 * Returns the {@link IoFilter} with the specified <tt>name</tt> in this chain.
68 * @return <tt>null</tt> if there's no such name in this chain
69 */
70 IoFilter get(String name);
71
72 /**
73 * Returns the {@link IoFilter} with the specified <tt>filterType</tt>
74 * in this chain. If there's more than one filter with the specified
75 * type, the first match will be chosen.
76 * @return <tt>null</tt> if there's no such name in this chain
77 */
78 IoFilter get(Class<? extends IoFilter> filterType);
79
80 /**
81 * Returns the {@link NextFilter} of the {@link IoFilter} with the
82 * specified <tt>name</tt> in this chain.
83 * @return <tt>null</tt> if there's no such name in this chain
84 */
85 NextFilter getNextFilter(String name);
86
87 /**
88 * Returns the {@link NextFilter} of the specified {@link IoFilter}
89 * in this chain.
90 * @return <tt>null</tt> if there's no such name in this chain
91 */
92 NextFilter getNextFilter(IoFilter filter);
93
94 /**
95 * Returns the {@link NextFilter} of the specified <tt>filterType</tt>
96 * in this chain. If there's more than one filter with the specified
97 * type, the first match will be chosen.
98 * @return <tt>null</tt> if there's no such name in this chain
99 */
100 NextFilter getNextFilter(Class<? extends IoFilter> filterType);
101
102 /**
103 * Returns the list of all {@link Entry}s this chain contains.
104 */
105 List<Entry> getAll();
106
107 /**
108 * Returns the reversed list of all {@link Entry}s this chain contains.
109 */
110 List<Entry> getAllReversed();
111
112 /**
113 * Returns <tt>true</tt> if this chain contains an {@link IoFilter} with the
114 * specified <tt>name</tt>.
115 */
116 boolean contains(String name);
117
118 /**
119 * Returns <tt>true</tt> if this chain contains the specified <tt>filter</tt>.
120 */
121 boolean contains(IoFilter filter);
122
123 /**
124 * Returns <tt>true</tt> if this chain contains an {@link IoFilter} of the
125 * specified <tt>filterType</tt>.
126 */
127 boolean contains(Class<? extends IoFilter> filterType);
128
129 /**
130 * Adds the specified filter with the specified name at the beginning of this chain.
131 * @throws IoFilterLifeCycleException
132 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
133 * {@link IoFilter#init()} throws an exception.
134 */
135 void addFirst(String name, IoFilter filter);
136
137 /**
138 * Adds the specified filter with the specified name at the end of this chain.
139 * @throws IoFilterLifeCycleException
140 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
141 * {@link IoFilter#init()} throws an exception.
142 */
143 void addLast(String name, IoFilter filter);
144
145 /**
146 * Adds the specified filter with the specified name just before the filter whose name is
147 * <code>baseName</code> in this chain.
148 * @throws IoFilterLifeCycleException
149 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
150 * {@link IoFilter#init()} throws an exception.
151 */
152 void addBefore(String baseName, String name, IoFilter filter);
153
154 /**
155 * Adds the specified filter with the specified name just after the filter whose name is
156 * <code>baseName</code> in this chain.
157 * @throws IoFilterLifeCycleException
158 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
159 * {@link IoFilter#init()} throws an exception.
160 */
161 void addAfter(String baseName, String name, IoFilter filter);
162
163 /**
164 * Replace the filter with the specified name with the specified new
165 * filter.
166 *
167 * @return the old filter
168 * @throws IllegalArgumentException if there's no such filter
169 */
170 IoFilter replace(String name, IoFilter newFilter);
171
172 /**
173 * Replace the filter with the specified name with the specified new
174 * filter.
175 *
176 * @throws IllegalArgumentException if there's no such filter
177 */
178 void replace(IoFilter oldFilter, IoFilter newFilter);
179
180 /**
181 * Replace the filter of the specified type with the specified new
182 * filter. If there's more than one filter with the specified type,
183 * the first match will be replaced.
184 *
185 * @throws IllegalArgumentException if there's no such filter
186 */
187 IoFilter replace(Class<? extends IoFilter> oldFilterType, IoFilter newFilter);
188
189 /**
190 * Removes the filter with the specified name from this chain.
191 * @throws IoFilterLifeCycleException
192 * if {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)} or
193 * {@link IoFilter#destroy()} throws an exception.
194 */
195 IoFilter remove(String name);
196
197 /**
198 * Replace the filter with the specified name with the specified new
199 * filter.
200 *
201 * @throws IllegalArgumentException if there's no such filter
202 */
203 void remove(IoFilter filter);
204
205 /**
206 * Replace the filter of the specified type with the specified new
207 * filter. If there's more than one filter with the specified type,
208 * the first match will be replaced.
209 *
210 * @throws IllegalArgumentException if there's no such filter
211 */
212 IoFilter remove(Class<? extends IoFilter> filterType);
213
214 /**
215 * Removes all filters added to this chain.
216 * @throws Exception if {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)} thrown an exception.
217 */
218 void clear() throws Exception;
219
220 /**
221 * Fires a {@link IoHandler#sessionCreated(IoSession)} event. Most users don't need to
222 * call this method at all. Please use this method only when you implement a new transport
223 * or fire a virtual event.
224 */
225 public void fireSessionCreated();
226
227 /**
228 * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call
229 * this method at all. Please use this method only when you implement a new transport or
230 * fire a virtual event.
231 */
232 public void fireSessionOpened();
233
234 /**
235 * Fires a {@link IoHandler#sessionClosed(IoSession)} event. Most users don't need to call
236 * this method at all. Please use this method only when you implement a new transport or
237 * fire a virtual event.
238 */
239 public void fireSessionClosed();
240
241 /**
242 * Fires a {@link IoHandler#sessionIdle(IoSession, IdleStatus)} event. Most users don't
243 * need to call this method at all. Please use this method only when you implement a new
244 * transport or fire a virtual event.
245 */
246 public void fireSessionIdle(IdleStatus status);
247
248 /**
249 * Fires a {@link #fireMessageReceived(Object)} event. Most users don't need to
250 * call this method at all. Please use this method only when you implement a new transport
251 * or fire a virtual event.
252 */
253 public void fireMessageReceived(Object message);
254
255 /**
256 * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call
257 * this method at all. Please use this method only when you implement a new transport or
258 * fire a virtual event.
259 */
260 public void fireMessageSent(WriteRequest request);
261
262 /**
263 * Fires a {@link IoHandler#exceptionCaught(IoSession, Throwable)} event. Most users don't
264 * need to call this method at all. Please use this method only when you implement a new
265 * transport or fire a virtual event.
266 */
267 public void fireExceptionCaught(Throwable cause);
268
269 /**
270 * Fires a {@link IoSession#write(Object)} event. Most users don't need to call this
271 * method at all. Please use this method only when you implement a new transport or fire a
272 * virtual event.
273 */
274 public void fireFilterWrite(WriteRequest writeRequest);
275
276 /**
277 * Fires a {@link IoSession#close()} event. Most users don't need to call this method at
278 * all. Please use this method only when you implement a new transport or fire a virtual
279 * event.
280 */
281 public void fireFilterClose();
282
283 /**
284 * Fires a {@link IoSession#setTrafficMask(TrafficMask)} event. Most users don't need to call this method at
285 * all. Please use this method only when you implement a new transport or fire a virtual
286 * event.
287 */
288 public void fireFilterSetTrafficMask(TrafficMask trafficMask);
289
290 /**
291 * Represents a name-filter pair that an {@link IoFilterChain} contains.
292 *
293 * @author The Apache MINA Project (dev@mina.apache.org)
294 * @version $Rev: 593474 $, $Date: 2007-11-09 11:14:12 +0100 (Fri, 09 Nov 2007) $
295 */
296 public interface Entry {
297 /**
298 * Returns the name of the filter.
299 */
300 String getName();
301
302 /**
303 * Returns the filter.
304 */
305 IoFilter getFilter();
306
307 /**
308 * Returns the {@link NextFilter} of the filter.
309 *
310 * @throws IllegalStateException if the {@link NextFilter} is not available
311 */
312 NextFilter getNextFilter();
313
314 /**
315 * Adds the specified filter with the specified name just before this entry.
316 * @throws IoFilterLifeCycleException
317 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
318 * {@link IoFilter#init()} throws an exception.
319 */
320 void addBefore(String name, IoFilter filter);
321
322 /**
323 * Adds the specified filter with the specified name just after this entry.
324 * @throws IoFilterLifeCycleException
325 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
326 * {@link IoFilter#init()} throws an exception.
327 */
328 void addAfter(String name, IoFilter filter);
329
330 /**
331 * Replace the filter of this entry with the specified new filter.
332 *
333 * @throws IllegalArgumentException if there's no such filter
334 */
335 void replace(IoFilter newFilter);
336
337 /**
338 * Removes this entry from the chain it belongs to.
339 */
340 void remove();
341 }
342 }