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