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#close(boolean)} 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}