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