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 import org.apache.mina.filter.FilterEvent; 30 31 /** 32 * A container of {@link IoFilter}s that forwards {@link IoHandler} events 33 * to the consisting filters and terminal {@link IoHandler} sequentially. 34 * Every {@link IoSession} has its own {@link IoFilterChain} (1-to-1 relationship). 35 * 36 * @author <a href="http://mina.apache.org">Apache MINA Project</a> 37 */ 38 public interface IoFilterChain { 39 /** 40 * @return the parent {@link IoSession} of this chain. 41 */ 42 IoSession getSession(); 43 44 /** 45 * Returns the {@link Entry} with the specified <tt>name</tt> in this chain. 46 * 47 * @param name The filter's name we are looking for 48 * @return <tt>null</tt> if there's no such name in this chain 49 */ 50 Entry getEntry(String name); 51 52 /** 53 * Returns the {@link Entry} with the specified <tt>filter</tt> in this chain. 54 * 55 * @param filter The Filter we are looking for 56 * @return <tt>null</tt> if there's no such filter in this chain 57 */ 58 Entry getEntry(IoFilter filter); 59 60 /** 61 * Returns the {@link Entry} with the specified <tt>filterType</tt> 62 * in this chain. If there's more than one filter with the specified 63 * type, the first match will be chosen. 64 * 65 * @param filterType The filter class we are looking for 66 * @return <tt>null</tt> if there's no such name in this chain 67 */ 68 Entry getEntry(Class<? extends IoFilter> filterType); 69 70 /** 71 * Returns the {@link IoFilter} with the specified <tt>name</tt> in this chain. 72 * 73 * @param name the filter's name 74 * @return <tt>null</tt> if there's no such name in this chain 75 */ 76 IoFilter get(String name); 77 78 /** 79 * Returns the {@link IoFilter} with the specified <tt>filterType</tt> 80 * in this chain. If there's more than one filter with the specified 81 * type, the first match will be chosen. 82 * 83 * @param filterType The filter class 84 * @return <tt>null</tt> if there's no such name in this chain 85 */ 86 IoFilter get(Class<? extends IoFilter> filterType); 87 88 /** 89 * Returns the {@link NextFilter} of the {@link IoFilter} with the 90 * specified <tt>name</tt> in this chain. 91 * 92 * @param name The filter's name we want the next filter 93 * @return <tt>null</tt> if there's no such name in this chain 94 */ 95 NextFilter getNextFilter(String name); 96 97 /** 98 * Returns the {@link NextFilter} of the specified {@link IoFilter} 99 * in this chain. 100 * 101 * @param filter The filter for which we want the next filter 102 * @return <tt>null</tt> if there's no such name in this chain 103 */ 104 NextFilter getNextFilter(IoFilter filter); 105 106 /** 107 * Returns the {@link NextFilter} of the specified <tt>filterType</tt> 108 * in this chain. If there's more than one filter with the specified 109 * type, the first match will be chosen. 110 * 111 * @param filterType The Filter class for which we want the next filter 112 * @return <tt>null</tt> if there's no such name in this chain 113 */ 114 NextFilter getNextFilter(Class<? extends IoFilter> filterType); 115 116 /** 117 * @return The list of all {@link Entry}s this chain contains. 118 */ 119 List<Entry> getAll(); 120 121 /** 122 * @return The reversed list of all {@link Entry}s this chain contains. 123 */ 124 List<Entry> getAllReversed(); 125 126 /** 127 * @param name The filter's name we are looking for 128 * 129 * @return <tt>true</tt> if this chain contains an {@link IoFilter} with the 130 * specified <tt>name</tt>. 131 */ 132 boolean contains(String name); 133 134 /** 135 * @param filter The filter we are looking for 136 * 137 * @return <tt>true</tt> if this chain contains the specified <tt>filter</tt>. 138 */ 139 boolean contains(IoFilter filter); 140 141 /** 142 * @param filterType The filter's class we are looking for 143 * 144 * @return <tt>true</tt> if this chain contains an {@link IoFilter} of the 145 * specified <tt>filterType</tt>. 146 */ 147 boolean contains(Class<? extends IoFilter> filterType); 148 149 /** 150 * Adds the specified filter with the specified name at the beginning of this chain. 151 * 152 * @param name The filter's name 153 * @param filter The filter to add 154 */ 155 void addFirst(String name, IoFilter filter); 156 157 /** 158 * Adds the specified filter with the specified name at the end of this chain. 159 * 160 * @param name The filter's name 161 * @param filter The filter to add 162 */ 163 void addLast(String name, IoFilter filter); 164 165 /** 166 * Adds the specified filter with the specified name just before the filter whose name is 167 * <code>baseName</code> in this chain. 168 * 169 * @param baseName The targeted Filter's name 170 * @param name The filter's name 171 * @param filter The filter to add 172 */ 173 void addBefore(String baseName, String name, IoFilter filter); 174 175 /** 176 * Adds the specified filter with the specified name just after the filter whose name is 177 * <code>baseName</code> in this chain. 178 * 179 * @param baseName The targeted Filter's name 180 * @param name The filter's name 181 * @param filter The filter to add 182 */ 183 void addAfter(String baseName, String name, IoFilter filter); 184 185 /** 186 * Replace the filter with the specified name with the specified new 187 * filter. 188 * 189 * @param name The name of the filter we want to replace 190 * @param newFilter The new filter 191 * @return the old filter 192 */ 193 IoFilter./org/apache/mina/core/filterchain/IoFilter.html#IoFilter">IoFilter replace(String name, IoFilter newFilter); 194 195 /** 196 * Replace the filter with the specified name with the specified new 197 * filter. 198 * 199 * @param oldFilter The filter we want to replace 200 * @param newFilter The new filter 201 */ 202 void replace(IoFilter../../../../org/apache/mina/core/filterchain/IoFilter.html#IoFilter">IoFilter oldFilter, IoFilter newFilter); 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 * @param oldFilterType The filter class we want to replace 210 * @param newFilter The new filter 211 * @return The replaced IoFilter 212 */ 213 IoFiIoFilter replace(Class<? extends IoFilter> oldFilterType, IoFilter newFilter); 214 215 /** 216 * Removes the filter with the specified name from this chain. 217 * 218 * @param name The name of the filter to remove 219 * @return The removed filter 220 */ 221 IoFilter remove(String name); 222 223 /** 224 * Replace the filter with the specified name with the specified new filter. 225 * 226 * @param filter 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 The filter class to remove 236 * @return The removed filter 237 */ 238 IoFilter remove(Class<? extends IoFilter> filterType); 239 240 /** 241 * Removes all filters added to this chain. 242 * 243 * @throws Exception If we weren't able to clear the filters 244 */ 245 void clear() throws Exception; 246 247 /** 248 * Fires a {@link IoHandler#sessionCreated(IoSession)} 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 void fireSessionCreated(); 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 void fireSessionOpened(); 260 261 /** 262 * Fires a {@link IoHandler#sessionClosed(IoSession)} event. Most users don't need to call 263 * this method at all. Please use this method only when you implement a new transport or 264 * fire a virtual event. 265 */ 266 void fireSessionClosed(); 267 268 /** 269 * Fires a {@link IoHandler#sessionIdle(IoSession, IdleStatus)} event. Most users don't 270 * need to call this method at all. Please use this method only when you implement a new 271 * transport or fire a virtual event. 272 * 273 * @param status The current status to propagate 274 */ 275 void fireSessionIdle(IdleStatus status); 276 277 /** 278 * Fires a {@link IoHandler#messageReceived(IoSession, Object)} event. Most 279 * users don't need to call this method at all. Please use this method only 280 * when you implement a new transport or fire a virtual event. 281 * 282 * @param message The received message 283 */ 284 void fireMessageReceived(Object message); 285 286 /** 287 * Fires a {@link IoHandler#messageSent(IoSession, Object)} event. Most 288 * users don't need to call this method at all. Please use this method only 289 * when you implement a new transport or fire a virtual event. 290 * 291 * @param request The sent request 292 */ 293 void fireMessageSent(WriteRequest request); 294 295 /** 296 * Fires a {@link IoHandler#exceptionCaught(IoSession, Throwable)} event. Most users don't 297 * need to call this method at all. Please use this method only when you implement a new 298 * transport or fire a virtual event. 299 * 300 * @param cause The exception cause 301 */ 302 void fireExceptionCaught(Throwable cause); 303 304 /** 305 * Fires a {@link IoHandler#inputClosed(IoSession)} event. Most users don't 306 * need to call this method at all. Please use this method only when you 307 * implement a new transport or fire a virtual event. 308 */ 309 void fireInputClosed(); 310 311 /** 312 * Fires a {@link IoSession#write(Object)} event. Most users don't need to 313 * call this method at all. Please use this method only when you implement a 314 * new transport or fire a virtual event. 315 * 316 * @param writeRequest The message to write 317 */ 318 void fireFilterWrite(WriteRequest writeRequest); 319 320 /** 321 * Fires a {@link IoSession#closeNow()} or a {@link IoSession#closeOnFlush()} event. Most users don't need to call this method at 322 * all. Please use this method only when you implement a new transport or fire a virtual 323 * event. 324 */ 325 void fireFilterClose(); 326 327 328 /** 329 * Fires a {@link IoHandler#event(IoSession, FilterEvent)} event. Most users don't need to call this method at 330 * all. Please use this method only when you implement a new transport or fire a virtual 331 * event. 332 * 333 * @param event The specific event being fired 334 */ 335 void fireEvent(FilterEvent event); 336 337 /** 338 * Represents a name-filter pair that an {@link IoFilterChain} contains. 339 * 340 * @author <a href="http://mina.apache.org">Apache MINA Project</a> 341 */ 342 interface Entry { 343 /** 344 * @return the name of the filter. 345 */ 346 String getName(); 347 348 /** 349 * @return the filter. 350 */ 351 IoFilter getFilter(); 352 353 /** 354 * @return The {@link NextFilter} of the filter. 355 */ 356 NextFilter getNextFilter(); 357 358 /** 359 * Adds the specified filter with the specified name just before this entry. 360 * 361 * @param name The Filter's name 362 * @param filter The added Filter 363 */ 364 void addBefore(String name, IoFilter filter); 365 366 /** 367 * Adds the specified filter with the specified name just after this entry. 368 * 369 * @param name The Filter's name 370 * @param filter The added Filter 371 */ 372 void addAfter(String name, IoFilter filter); 373 374 /** 375 * Replace the filter of this entry with the specified new filter. 376 * 377 * @param newFilter The new filter that will be put in the chain 378 */ 379 void replace(IoFilter newFilter); 380 381 /** 382 * Removes this entry from the chain it belongs to. 383 */ 384 void remove(); 385 } 386 }