001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 *
019 */
020package org.apache.mina.core.filterchain;
021
022import java.util.List;
023
024import org.apache.mina.core.filterchain.IoFilter.NextFilter;
025import org.apache.mina.core.service.IoHandler;
026import org.apache.mina.core.session.IdleStatus;
027import org.apache.mina.core.session.IoSession;
028import org.apache.mina.core.write.WriteRequest;
029
030/**
031 * A container of {@link IoFilter}s that forwards {@link IoHandler} events
032 * to the consisting filters and terminal {@link IoHandler} sequentially.
033 * Every {@link IoSession} has its own {@link IoFilterChain} (1-to-1 relationship).
034 *
035 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
036 */
037public interface IoFilterChain {
038    /**
039     * @return the parent {@link IoSession} of this chain.
040     */
041    IoSession getSession();
042
043    /**
044     * Returns the {@link Entry} with the specified <tt>name</tt> in this chain.
045     * 
046     * @param name The filter's name we are looking for
047     * @return <tt>null</tt> if there's no such name in this chain
048     */
049    Entry getEntry(String name);
050
051    /**
052     * Returns the {@link Entry} with the specified <tt>filter</tt> in this chain.
053     * 
054     * @param filter  The Filter we are looking for
055     * @return <tt>null</tt> if there's no such filter in this chain
056     */
057    Entry getEntry(IoFilter filter);
058
059    /**
060     * Returns the {@link Entry} with the specified <tt>filterType</tt>
061     * in this chain. If there's more than one filter with the specified
062     * type, the first match will be chosen.
063     * 
064     * @param filterType The filter class we are looking for
065     * @return <tt>null</tt> if there's no such name in this chain
066     */
067    Entry getEntry(Class<? extends IoFilter> filterType);
068
069    /**
070     * Returns the {@link IoFilter} with the specified <tt>name</tt> in this chain.
071     * 
072     * @param name the filter's name
073     * @return <tt>null</tt> if there's no such name in this chain
074     */
075    IoFilter get(String name);
076
077    /**
078     * Returns the {@link IoFilter} with the specified <tt>filterType</tt>
079     * in this chain. If there's more than one filter with the specified
080     * type, the first match will be chosen.
081     * 
082     * @param filterType The filter class
083     * @return <tt>null</tt> if there's no such name in this chain
084     */
085    IoFilter get(Class<? extends IoFilter> filterType);
086
087    /**
088     * Returns the {@link NextFilter} of the {@link IoFilter} with the
089     * specified <tt>name</tt> in this chain.
090     * 
091     * @param name The filter's name we want the next filter
092     * @return <tt>null</tt> if there's no such name in this chain
093     */
094    NextFilter getNextFilter(String name);
095
096    /**
097     * Returns the {@link NextFilter} of the specified {@link IoFilter}
098     * in this chain.
099     * 
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
226     *            The filter to remove
227     */
228    void remove(IoFilter filter);
229
230    /**
231     * Replace the filter of the specified type with the specified new filter.
232     * If there's more than one filter with the specified type, the first match
233     * will be replaced.
234     * 
235     * @param filterType
236     *            The filter class to remove
237     * @return The removed filter
238     */
239    IoFilter remove(Class<? extends IoFilter> filterType);
240
241    /**
242     * Removes all filters added to this chain.
243     * 
244     * @throws Exception If we weren't able to clear the filters
245     */
246    void clear() throws Exception;
247
248    /**
249     * Fires a {@link IoHandler#sessionCreated(IoSession)} event. Most users don't need to
250     * call this method at all. Please use this method only when you implement a new transport
251     * or fire a virtual event.
252     */
253    void fireSessionCreated();
254
255    /**
256     * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call
257     * this method at all. Please use this method only when you implement a new transport or
258     * fire a virtual event.
259     */
260    void fireSessionOpened();
261
262    /**
263     * Fires a {@link IoHandler#sessionClosed(IoSession)} event. Most users don't need to call
264     * this method at all. Please use this method only when you implement a new transport or
265     * fire a virtual event.
266     */
267    void fireSessionClosed();
268
269    /**
270     * Fires a {@link IoHandler#sessionIdle(IoSession, IdleStatus)} event. Most users don't
271     * need to call this method at all. Please use this method only when you implement a new
272     * transport or fire a virtual event.
273     * 
274     * @param status The current status to propagate
275     */
276    void fireSessionIdle(IdleStatus status);
277
278    /**
279     * Fires a {@link IoHandler#messageReceived(IoSession, Object)} event. Most
280     * users don't need to call this method at all. Please use this method only
281     * when you implement a new transport or fire a virtual event.
282     * 
283     * @param message
284     *            The received message
285     */
286    void fireMessageReceived(Object message);
287
288    /**
289     * Fires a {@link IoHandler#messageSent(IoSession, Object)} event. Most
290     * users don't need to call this method at all. Please use this method only
291     * when you implement a new transport or fire a virtual event.
292     * 
293     * @param request
294     *            The sent request
295     */
296    void fireMessageSent(WriteRequest request);
297
298    /**
299     * Fires a {@link IoHandler#exceptionCaught(IoSession, Throwable)} event. Most users don't
300     * need to call this method at all. Please use this method only when you implement a new
301     * transport or fire a virtual event.
302     * 
303     * @param cause The exception cause
304     */
305    void fireExceptionCaught(Throwable cause);
306
307    /**
308     * Fires a {@link IoHandler#inputClosed(IoSession)} event. Most users don't
309     * need to call this method at all. Please use this method only when you
310     * implement a new transport or fire a virtual event.
311     */
312    void fireInputClosed();
313
314    /**
315     * Fires a {@link IoSession#write(Object)} event. Most users don't need to
316     * call this method at all. Please use this method only when you implement a
317     * new transport or fire a virtual event.
318     * 
319     * @param writeRequest
320     *            The message to write
321     */
322    void fireFilterWrite(WriteRequest writeRequest);
323
324    /**
325     * Fires a {@link IoSession#closeNow()} or a {@link IoSession#closeOnFlush()} event. Most users don't need to call this method at
326     * all. Please use this method only when you implement a new transport or fire a virtual
327     * event.
328     */
329    void fireFilterClose();
330
331    /**
332     * Represents a name-filter pair that an {@link IoFilterChain} contains.
333     *
334     * @author <a href="http://mina.apache.org">Apache MINA Project</a>
335     */
336    interface Entry {
337        /**
338         * @return the name of the filter.
339         */
340        String getName();
341
342        /**
343         * @return the filter.
344         */
345        IoFilter getFilter();
346
347        /**
348         * @return The {@link NextFilter} of the filter.
349         */
350        NextFilter getNextFilter();
351
352        /**
353         * Adds the specified filter with the specified name just before this entry.
354         * 
355         * @param name The Filter's name
356         * @param filter The added Filter 
357         */
358        void addBefore(String name, IoFilter filter);
359
360        /**
361         * Adds the specified filter with the specified name just after this entry.
362         * 
363         * @param name The Filter's name
364         * @param filter The added Filter 
365         */
366        void addAfter(String name, IoFilter filter);
367
368        /**
369         * Replace the filter of this entry with the specified new filter.
370         * 
371         * @param newFilter The new filter that will be put in the chain 
372         */
373        void replace(IoFilter newFilter);
374
375        /**
376         * Removes this entry from the chain it belongs to.
377         */
378        void remove();
379    }
380}