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 import org.apache.mina.common.IoFilter.WriteRequest;
26
27 /**
28 * A container of {@link IoFilter}s that forwards {@link IoHandler} events
29 * to the consisting filters and terminal {@link IoHandler} sequentially.
30 * Every {@link IoSession} has its own {@link IoFilterChain} (1-to-1 relationship).
31 *
32 * @author The Apache Directory Project (mina-dev@directory.apache.org)
33 * @version $Rev: 555855 $, $Date: 2007-07-13 12:19:00 +0900 (Fri, 13 Jul 2007) $
34 */
35 public interface IoFilterChain {
36 /**
37 * Returns the parent {@link IoSession} of this chain.
38 * @return {@link IoSession}
39 */
40 IoSession getSession();
41
42 /**
43 * Returns the {@link Entry} with the specified <tt>name</tt> in this chain.
44 * @return <tt>null</tt> if there's no such name in this chain
45 */
46 Entry getEntry(String name);
47
48 /**
49 * Returns the {@link IoFilter} with the specified <tt>name</tt> in this chain.
50 * @return <tt>null</tt> if there's no such name in this chain
51 */
52 IoFilter get(String name);
53
54 /**
55 * Returns the {@link NextFilter} of the {@link IoFilter} with the
56 * specified <tt>name</tt> in this chain.
57 * @return <tt>null</tt> if there's no such name in this chain
58 */
59 NextFilter getNextFilter(String name);
60
61 /**
62 * Returns the list of all {@link Entry}s this chain contains.
63 */
64 List<Entry> getAll();
65
66 /**
67 * Returns the reversed list of all {@link Entry}s this chain contains.
68 */
69 List<Entry> getAllReversed();
70
71 /**
72 * Returns <tt>true</tt> if this chain contains an {@link IoFilter} with the
73 * specified <tt>name</tt>.
74 */
75 boolean contains(String name);
76
77 /**
78 * Returns <tt>true</tt> if this chain contains the specified <tt>filter</tt>.
79 */
80 boolean contains(IoFilter filter);
81
82 /**
83 * Returns <tt>true</tt> if this chain contains an {@link IoFilter} of the
84 * specified <tt>filterType</tt>.
85 */
86 boolean contains(Class<? extends IoFilter> filterType);
87
88 /**
89 * Adds the specified filter with the specified name at the beginning of this chain.
90 * @throws IoFilterLifeCycleException
91 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
92 * {@link IoFilter#init()} throws an exception.
93 */
94 void addFirst(String name, IoFilter filter);
95
96 /**
97 * Adds the specified filter with the specified name at the end of this chain.
98 * @throws IoFilterLifeCycleException
99 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
100 * {@link IoFilter#init()} throws an exception.
101 */
102 void addLast(String name, IoFilter filter);
103
104 /**
105 * Adds the specified filter with the specified name just before the filter whose name is
106 * <code>baseName</code> in this chain.
107 * @throws IoFilterLifeCycleException
108 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
109 * {@link IoFilter#init()} throws an exception.
110 */
111 void addBefore(String baseName, String name, IoFilter filter);
112
113 /**
114 * Adds the specified filter with the specified name just after the filter whose name is
115 * <code>baseName</code> in this chain.
116 * @throws IoFilterLifeCycleException
117 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or
118 * {@link IoFilter#init()} throws an exception.
119 */
120 void addAfter(String baseName, String name, IoFilter filter);
121
122 /**
123 * Removes the filter with the specified name from this chain.
124 * @throws IoFilterLifeCycleException
125 * if {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)} or
126 * {@link IoFilter#destroy()} throws an exception.
127 */
128 IoFilter remove(String name);
129
130 /**
131 * Removes all filters added to this chain.
132 * @throws Exception if {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)} thrown an exception.
133 */
134 void clear() throws Exception;
135
136 /**
137 * Fires a {@link IoHandler#sessionCreated(IoSession)} event. Most users don't need to
138 * call this method at all. Please use this method only when you implement a new transport
139 * or fire a virtual event.
140 */
141 public void fireSessionCreated(IoSession session);
142
143 /**
144 * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call
145 * this method at all. Please use this method only when you implement a new transport or
146 * fire a virtual event.
147 */
148 public void fireSessionOpened(IoSession session);
149
150 /**
151 * Fires a {@link IoHandler#sessionClosed(IoSession)} event. Most users don't need to call
152 * this method at all. Please use this method only when you implement a new transport or
153 * fire a virtual event.
154 */
155 public void fireSessionClosed(IoSession session);
156
157 /**
158 * Fires a {@link IoHandler#sessionIdle(IoSession, IdleStatus)} event. Most users don't
159 * need to call this method at all. Please use this method only when you implement a new
160 * transport or fire a virtual event.
161 */
162 public void fireSessionIdle(IoSession session, IdleStatus status);
163
164 /**
165 * Fires a {@link #fireMessageReceived(IoSession, Object)} event. Most users don't need to
166 * call this method at all. Please use this method only when you implement a new transport
167 * or fire a virtual event.
168 */
169 public void fireMessageReceived(IoSession session, Object message);
170
171 /**
172 * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call
173 * this method at all. Please use this method only when you implement a new transport or
174 * fire a virtual event.
175 */
176 public void fireMessageSent(IoSession session, WriteRequest request);
177
178 /**
179 * Fires a {@link IoHandler#exceptionCaught(IoSession, Throwable)} event. Most users don't
180 * need to call this method at all. Please use this method only when you implement a new
181 * transport or fire a virtual event.
182 */
183 public void fireExceptionCaught(IoSession session, Throwable cause);
184
185 /**
186 * Fires a {@link IoSession#write(Object)} event. Most users don't need to call this
187 * method at all. Please use this method only when you implement a new transport or fire a
188 * virtual event.
189 */
190 public void fireFilterWrite(IoSession session, WriteRequest writeRequest);
191
192 /**
193 * Fires a {@link IoSession#close()} event. Most users don't need to call this method at
194 * all. Please use this method only when you implement a new transport or fire a virtual
195 * event.
196 */
197 public void fireFilterClose(IoSession session);
198
199 /**
200 * Represents a name-filter pair that an {@link IoFilterChain} contains.
201 *
202 * @author The Apache Directory Project (mina-dev@directory.apache.org)
203 * @version $Rev: 555855 $, $Date: 2007-07-13 12:19:00 +0900 (Fri, 13 Jul 2007) $
204 */
205 public interface Entry {
206 /**
207 * Returns the name of the filter.
208 */
209 String getName();
210
211 /**
212 * Returns the filter.
213 */
214 IoFilter getFilter();
215
216 /**
217 * Returns the {@link NextFilter} of the filter.
218 *
219 * @throws IllegalStateException if the {@link NextFilter} is not available
220 */
221 NextFilter getNextFilter();
222 }
223 }