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       * 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 filter.
225      * 
226      * @param filter
227      *            The filter to remove
228      */
229     void remove(IoFilter filter);
230 
231     /**
232      * Replace the filter of the specified type with the specified new filter.
233      * If there's more than one filter with the specified type, the first match
234      * will be replaced.
235      * 
236      * @param filterType
237      *            The filter class to remove
238      * @return The removed filter
239      */
240     IoFilter remove(Class<? extends IoFilter> filterType);
241 
242     /**
243      * Removes all filters added to this chain.
244      */
245     void clear() throws Exception;
246 
247     /**
248      * Fires a {@link IoHandler#sessionCreated(IoSession)} event. Most users don't need to
249      * call this method at all. Please use this method only when you implement a new transport
250      * or fire a virtual event.
251      */
252     public void fireSessionCreated();
253 
254     /**
255      * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call
256      * this method at all. Please use this method only when you implement a new transport or
257      * fire a virtual event.
258      */
259     public void fireSessionOpened();
260 
261     /**
262      * Fires a {@link IoHandler#sessionClosed(IoSession)} event. Most users don't need to call
263      * this method at all. Please use this method only when you implement a new transport or
264      * fire a virtual event.
265      */
266     public void fireSessionClosed();
267 
268     /**
269      * Fires a {@link IoHandler#sessionIdle(IoSession, IdleStatus)} event. Most users don't
270      * need to call this method at all. Please use this method only when you implement a new
271      * transport or fire a virtual event.
272      * 
273      * @param status The current status to propagate
274      */
275     public void fireSessionIdle(IdleStatus status);
276 
277     /**
278      * Fires a {@link IoHandler#messageReceived(IoSession, Object)} event. Most
279      * users don't need to call this method at all. Please use this method only
280      * when you implement a new transport or fire a virtual event.
281      * 
282      * @param message
283      *            The received message
284      */
285     public void fireMessageReceived(Object message);
286 
287     /**
288      * Fires a {@link IoHandler#messageSent(IoSession, Object)} event. Most
289      * users don't need to call this method at all. Please use this method only
290      * when you implement a new transport or fire a virtual event.
291      * 
292      * @param request
293      *            The sent request
294      */
295     public void fireMessageSent(WriteRequest request);
296 
297     /**
298      * Fires a {@link IoHandler#exceptionCaught(IoSession, Throwable)} event. Most users don't
299      * need to call this method at all. Please use this method only when you implement a new
300      * transport or fire a virtual event.
301      * 
302      * @param cause The exception cause
303      */
304     public void fireExceptionCaught(Throwable cause);
305 
306     /**
307      * Fires a {@link IoHandler#inputClosed(IoSession)} event. Most users don't
308      * need to call this method at all. Please use this method only when you
309      * implement a new transport or fire a virtual event.
310      */
311     public void fireInputClosed();
312 
313     /**
314      * Fires a {@link IoSession#write(Object)} event. Most users don't need to
315      * call this method at all. Please use this method only when you implement a
316      * new transport or fire a virtual event.
317      * 
318      * @param writeRequest
319      *            The message to write
320      */
321     public void fireFilterWrite(WriteRequest writeRequest);
322 
323     /**
324      * Fires a {@link IoSession#close()} event. Most users don't need to call this method at
325      * all. Please use this method only when you implement a new transport or fire a virtual
326      * event.
327      */
328     public void fireFilterClose();
329 
330     /**
331      * Represents a name-filter pair that an {@link IoFilterChain} contains.
332      *
333      * @author <a href="http://mina.apache.org">Apache MINA Project</a>
334      */
335     public interface Entry {
336         /**
337          * Returns the name of the filter.
338          */
339         String getName();
340 
341         /**
342          * Returns the filter.
343          */
344         IoFilter getFilter();
345 
346         /**
347          * @return The {@link NextFilter} of the filter.
348          */
349         NextFilter getNextFilter();
350 
351         /**
352          * Adds the specified filter with the specified name just before this entry.
353          */
354         void addBefore(String name, IoFilter filter);
355 
356         /**
357          * Adds the specified filter with the specified name just after this entry.
358          */
359         void addAfter(String name, IoFilter filter);
360 
361         /**
362          * Replace the filter of this entry with the specified new filter.
363          */
364         void replace(IoFilter newFilter);
365 
366         /**
367          * Removes this entry from the chain it belongs to.
368          */
369         void remove();
370     }
371 }