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: */
020: package org.apache.mina.common;
021:
022: import java.util.List;
023:
024: import org.apache.mina.common.IoFilter.NextFilter;
025:
026: /**
027: * A container of {@link IoFilter}s that forwards {@link IoHandler} events
028: * to the consisting filters and terminal {@link IoHandler} sequentially.
029: * Every {@link IoSession} has its own {@link IoFilterChain} (1-to-1 relationship).
030: *
031: * @author The Apache MINA Project (dev@mina.apache.org)
032: * @version $Rev: 593474 $, $Date: 2007-11-09 03:14:12 -0700 (Fri, 09 Nov 2007) $
033: */
034: public interface IoFilterChain {
035: /**
036: * Returns the parent {@link IoSession} of this chain.
037: * @return {@link IoSession}
038: */
039: IoSession getSession();
040:
041: /**
042: * Returns the {@link Entry} with the specified <tt>name</tt> in this chain.
043: * @return <tt>null</tt> if there's no such name in this chain
044: */
045: Entry getEntry(String name);
046:
047: /**
048: * Returns the {@link Entry} with the specified <tt>filter</tt> in this chain.
049: * @return <tt>null</tt> if there's no such filter in this chain
050: */
051: Entry getEntry(IoFilter filter);
052:
053: /**
054: * Returns the {@link Entry} with the specified <tt>filterType</tt>
055: * in this chain. If there's more than one filter with the specified
056: * type, the first match will be chosen.
057: * @return <tt>null</tt> if there's no such name in this chain
058: */
059: Entry getEntry(Class<? extends IoFilter> filterType);
060:
061: /**
062: * Returns the {@link IoFilter} with the specified <tt>name</tt> in this chain.
063: * @return <tt>null</tt> if there's no such name in this chain
064: */
065: IoFilter get(String name);
066:
067: /**
068: * Returns the {@link IoFilter} with the specified <tt>filterType</tt>
069: * in this chain. If there's more than one filter with the specified
070: * type, the first match will be chosen.
071: * @return <tt>null</tt> if there's no such name in this chain
072: */
073: IoFilter get(Class<? extends IoFilter> filterType);
074:
075: /**
076: * Returns the {@link NextFilter} of the {@link IoFilter} with the
077: * specified <tt>name</tt> in this chain.
078: * @return <tt>null</tt> if there's no such name in this chain
079: */
080: NextFilter getNextFilter(String name);
081:
082: /**
083: * Returns the {@link NextFilter} of the specified {@link IoFilter}
084: * in this chain.
085: * @return <tt>null</tt> if there's no such name in this chain
086: */
087: NextFilter getNextFilter(IoFilter filter);
088:
089: /**
090: * Returns the {@link NextFilter} of the specified <tt>filterType</tt>
091: * in this chain. If there's more than one filter with the specified
092: * type, the first match will be chosen.
093: * @return <tt>null</tt> if there's no such name in this chain
094: */
095: NextFilter getNextFilter(Class<? extends IoFilter> filterType);
096:
097: /**
098: * Returns the list of all {@link Entry}s this chain contains.
099: */
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,
183: IoFilter newFilter);
184:
185: /**
186: * Removes the filter with the specified name from this chain.
187: * @throws IoFilterLifeCycleException
188: * if {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)} or
189: * {@link IoFilter#destroy()} throws an exception.
190: */
191: IoFilter remove(String name);
192:
193: /**
194: * Replace the filter with the specified name with the specified new
195: * filter.
196: *
197: * @throws IllegalArgumentException if there's no such filter
198: */
199: void remove(IoFilter filter);
200:
201: /**
202: * Replace the filter of the specified type with the specified new
203: * filter. If there's more than one filter with the specified type,
204: * the first match will be replaced.
205: *
206: * @throws IllegalArgumentException if there's no such filter
207: */
208: IoFilter remove(Class<? extends IoFilter> filterType);
209:
210: /**
211: * Removes all filters added to this chain.
212: * @throws Exception if {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)} thrown an exception.
213: */
214: void clear() throws Exception;
215:
216: /**
217: * Fires a {@link IoHandler#sessionCreated(IoSession)} event. Most users don't need to
218: * call this method at all. Please use this method only when you implement a new transport
219: * or fire a virtual event.
220: */
221: public void fireSessionCreated();
222:
223: /**
224: * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call
225: * this method at all. Please use this method only when you implement a new transport or
226: * fire a virtual event.
227: */
228: public void fireSessionOpened();
229:
230: /**
231: * Fires a {@link IoHandler#sessionClosed(IoSession)} event. Most users don't need to call
232: * this method at all. Please use this method only when you implement a new transport or
233: * fire a virtual event.
234: */
235: public void fireSessionClosed();
236:
237: /**
238: * Fires a {@link IoHandler#sessionIdle(IoSession, IdleStatus)} event. Most users don't
239: * need to call this method at all. Please use this method only when you implement a new
240: * transport or fire a virtual event.
241: */
242: public void fireSessionIdle(IdleStatus status);
243:
244: /**
245: * Fires a {@link #fireMessageReceived(Object)} event. Most users don't need to
246: * call this method at all. Please use this method only when you implement a new transport
247: * or fire a virtual event.
248: */
249: public void fireMessageReceived(Object message);
250:
251: /**
252: * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call
253: * this method at all. Please use this method only when you implement a new transport or
254: * fire a virtual event.
255: */
256: public void fireMessageSent(WriteRequest request);
257:
258: /**
259: * Fires a {@link IoHandler#exceptionCaught(IoSession, Throwable)} event. Most users don't
260: * need to call this method at all. Please use this method only when you implement a new
261: * transport or fire a virtual event.
262: */
263: public void fireExceptionCaught(Throwable cause);
264:
265: /**
266: * Fires a {@link IoSession#write(Object)} event. Most users don't need to call this
267: * method at all. Please use this method only when you implement a new transport or fire a
268: * virtual event.
269: */
270: public void fireFilterWrite(WriteRequest writeRequest);
271:
272: /**
273: * Fires a {@link IoSession#close()} event. Most users don't need to call this method at
274: * all. Please use this method only when you implement a new transport or fire a virtual
275: * event.
276: */
277: public void fireFilterClose();
278:
279: /**
280: * Fires a {@link IoSession#setTrafficMask(TrafficMask)} event. Most users don't need to call this method at
281: * all. Please use this method only when you implement a new transport or fire a virtual
282: * event.
283: */
284: public void fireFilterSetTrafficMask(TrafficMask trafficMask);
285:
286: /**
287: * Represents a name-filter pair that an {@link IoFilterChain} contains.
288: *
289: * @author The Apache MINA Project (dev@mina.apache.org)
290: * @version $Rev: 593474 $, $Date: 2007-11-09 03:14:12 -0700 (Fri, 09 Nov 2007) $
291: */
292: public interface Entry {
293: /**
294: * Returns the name of the filter.
295: */
296: String getName();
297:
298: /**
299: * Returns the filter.
300: */
301: IoFilter getFilter();
302:
303: /**
304: * Returns the {@link NextFilter} of the filter.
305: *
306: * @throws IllegalStateException if the {@link NextFilter} is not available
307: */
308: NextFilter getNextFilter();
309:
310: /**
311: * Adds the specified filter with the specified name just before this entry.
312: * @throws IoFilterLifeCycleException
313: * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
314: * {@link IoFilter#init()} throws an exception.
315: */
316: void addBefore(String name, IoFilter filter);
317:
318: /**
319: * Adds the specified filter with the specified name just after this entry.
320: * @throws IoFilterLifeCycleException
321: * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
322: * {@link IoFilter#init()} throws an exception.
323: */
324: void addAfter(String name, IoFilter filter);
325:
326: /**
327: * Replace the filter of this entry with the specified new filter.
328: *
329: * @throws IllegalArgumentException if there's no such filter
330: */
331: void replace(IoFilter newFilter);
332:
333: /**
334: * Removes this entry from the chain it belongs to.
335: */
336: void remove();
337: }
338: }
|