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