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