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