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 The filter to remove
226      */
227     void remove(IoFilter filter);
228 
229     /**
230      * Replace the filter of the specified type with the specified new filter.
231      * If there's more than one filter with the specified type, the first match
232      * will be replaced.
233      * 
234      * @param filterType The filter class to remove
235      * @return The removed filter
236      */
237     IoFilter remove(Class<? extends IoFilter> filterType);
238 
239     /**
240      * Removes all filters added to this chain.
241      * 
242      * @throws Exception If we weren't able to clear the filters
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     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     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     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     void fireSessionIdle(IdleStatus status);
275 
276     /**
277      * Fires a {@link IoHandler#messageReceived(IoSession, Object)} event. Most
278      * users don't need to call this method at all. Please use this method only
279      * when you implement a new transport or fire a virtual event.
280      * 
281      * @param message The received message
282      */
283     void fireMessageReceived(Object message);
284 
285     /**
286      * Fires a {@link IoHandler#messageSent(IoSession, Object)} event. Most
287      * users don't need to call this method at all. Please use this method only
288      * when you implement a new transport or fire a virtual event.
289      * 
290      * @param request The sent request
291      */
292     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     void fireExceptionCaught(Throwable cause);
302 
303     /**
304      * Fires a {@link IoHandler#inputClosed(IoSession)} event. Most users don't
305      * need to call this method at all. Please use this method only when you
306      * implement a new transport or fire a virtual event.
307      */
308     void fireInputClosed();
309 
310     /**
311      * Fires a {@link IoSession#write(Object)} event. Most users don't need to
312      * call this method at all. Please use this method only when you implement a
313      * new transport or fire a virtual event.
314      * 
315      * @param writeRequest The message to write
316      */
317     void fireFilterWrite(WriteRequest writeRequest);
318 
319     /**
320      * Fires a {@link IoSession#closeNow()} or a {@link IoSession#closeOnFlush()} event. Most users don't need to call this method at
321      * all. Please use this method only when you implement a new transport or fire a virtual
322      * event.
323      */
324     void fireFilterClose();
325 
326     /**
327      * Represents a name-filter pair that an {@link IoFilterChain} contains.
328      *
329      * @author <a href="http://mina.apache.org">Apache MINA Project</a>
330      */
331     interface Entry {
332         /**
333          * @return the name of the filter.
334          */
335         String getName();
336 
337         /**
338          * @return the filter.
339          */
340         IoFilter getFilter();
341 
342         /**
343          * @return The {@link NextFilter} of the filter.
344          */
345         NextFilter getNextFilter();
346 
347         /**
348          * Adds the specified filter with the specified name just before this entry.
349          * 
350          * @param name The Filter's name
351          * @param filter The added Filter 
352          */
353         void addBefore(String name, IoFilter filter);
354 
355         /**
356          * Adds the specified filter with the specified name just after this entry.
357          * 
358          * @param name The Filter's name
359          * @param filter The added Filter 
360          */
361         void addAfter(String name, IoFilter filter);
362 
363         /**
364          * Replace the filter of this entry with the specified new filter.
365          * 
366          * @param newFilter The new filter that will be put in the chain 
367          */
368         void replace(IoFilter newFilter);
369 
370         /**
371          * Removes this entry from the chain it belongs to.
372          */
373         void remove();
374     }
375 }