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