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 26 /** 27 * A container of {@link IoFilter}s that forwards {@link IoHandler} events 28 * to the consisting filters and terminal {@link IoHandler} sequentially. 29 * Every {@link IoSession} has its own {@link IoFilterChain} (1-to-1 relationship). 30 * 31 * @author The Apache MINA Project (dev@mina.apache.org) 32 * @version $Rev: 593474 $, $Date: 2007-11-09 03:14:12 -0700 (Fri, 09 Nov 2007) $ 33 */ 34 public interface IoFilterChain { 35 /** 36 * Returns the parent {@link IoSession} of this chain. 37 * @return {@link IoSession} 38 */ 39 IoSession getSession(); 40 41 /** 42 * Returns the {@link Entry} with the specified <tt>name</tt> in this chain. 43 * @return <tt>null</tt> if there's no such name in this chain 44 */ 45 Entry getEntry(String name); 46 47 /** 48 * Returns the {@link Entry} with the specified <tt>filter</tt> in this chain. 49 * @return <tt>null</tt> if there's no such filter in this chain 50 */ 51 Entry getEntry(IoFilter filter); 52 53 /** 54 * Returns the {@link Entry} with the specified <tt>filterType</tt> 55 * in this chain. If there's more than one filter with the specified 56 * type, the first match will be chosen. 57 * @return <tt>null</tt> if there's no such name in this chain 58 */ 59 Entry getEntry(Class<? extends IoFilter> filterType); 60 61 /** 62 * Returns the {@link IoFilter} with the specified <tt>name</tt> in this chain. 63 * @return <tt>null</tt> if there's no such name in this chain 64 */ 65 IoFilter get(String name); 66 67 /** 68 * Returns the {@link IoFilter} with the specified <tt>filterType</tt> 69 * in this chain. If there's more than one filter with the specified 70 * type, the first match will be chosen. 71 * @return <tt>null</tt> if there's no such name in this chain 72 */ 73 IoFilter get(Class<? extends IoFilter> filterType); 74 75 /** 76 * Returns the {@link NextFilter} of the {@link IoFilter} with the 77 * specified <tt>name</tt> in this chain. 78 * @return <tt>null</tt> if there's no such name in this chain 79 */ 80 NextFilter getNextFilter(String name); 81 82 /** 83 * Returns the {@link NextFilter} of the specified {@link IoFilter} 84 * in this chain. 85 * @return <tt>null</tt> if there's no such name in this chain 86 */ 87 NextFilter getNextFilter(IoFilter filter); 88 89 /** 90 * Returns the {@link NextFilter} of the specified <tt>filterType</tt> 91 * in this chain. If there's more than one filter with the specified 92 * type, the first match will be chosen. 93 * @return <tt>null</tt> if there's no such name in this chain 94 */ 95 NextFilter getNextFilter(Class<? extends IoFilter> filterType); 96 97 /** 98 * Returns the list of all {@link Entry}s this chain contains. 99 */ 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, IoFilter newFilter); 183 184 /** 185 * Removes the filter with the specified name from this chain. 186 * @throws IoFilterLifeCycleException 187 * if {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)} or 188 * {@link IoFilter#destroy()} throws an exception. 189 */ 190 IoFilter remove(String name); 191 192 /** 193 * Replace the filter with the specified name with the specified new 194 * filter. 195 * 196 * @throws IllegalArgumentException if there's no such filter 197 */ 198 void remove(IoFilter filter); 199 200 /** 201 * Replace the filter of the specified type with the specified new 202 * filter. If there's more than one filter with the specified type, 203 * the first match will be replaced. 204 * 205 * @throws IllegalArgumentException if there's no such filter 206 */ 207 IoFilter remove(Class<? extends IoFilter> filterType); 208 209 /** 210 * Removes all filters added to this chain. 211 * @throws Exception if {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)} thrown an exception. 212 */ 213 void clear() throws Exception; 214 215 /** 216 * Fires a {@link IoHandler#sessionCreated(IoSession)} event. Most users don't need to 217 * call this method at all. Please use this method only when you implement a new transport 218 * or fire a virtual event. 219 */ 220 public void fireSessionCreated(); 221 222 /** 223 * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call 224 * this method at all. Please use this method only when you implement a new transport or 225 * fire a virtual event. 226 */ 227 public void fireSessionOpened(); 228 229 /** 230 * Fires a {@link IoHandler#sessionClosed(IoSession)} event. Most users don't need to call 231 * this method at all. Please use this method only when you implement a new transport or 232 * fire a virtual event. 233 */ 234 public void fireSessionClosed(); 235 236 /** 237 * Fires a {@link IoHandler#sessionIdle(IoSession, IdleStatus)} event. Most users don't 238 * need to call this method at all. Please use this method only when you implement a new 239 * transport or fire a virtual event. 240 */ 241 public void fireSessionIdle(IdleStatus status); 242 243 /** 244 * Fires a {@link #fireMessageReceived(Object)} event. Most users don't need to 245 * call this method at all. Please use this method only when you implement a new transport 246 * or fire a virtual event. 247 */ 248 public void fireMessageReceived(Object message); 249 250 /** 251 * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call 252 * this method at all. Please use this method only when you implement a new transport or 253 * fire a virtual event. 254 */ 255 public void fireMessageSent(WriteRequest request); 256 257 /** 258 * Fires a {@link IoHandler#exceptionCaught(IoSession, Throwable)} event. Most users don't 259 * need to call this method at all. Please use this method only when you implement a new 260 * transport or fire a virtual event. 261 */ 262 public void fireExceptionCaught(Throwable cause); 263 264 /** 265 * Fires a {@link IoSession#write(Object)} event. Most users don't need to call this 266 * method at all. Please use this method only when you implement a new transport or fire a 267 * virtual event. 268 */ 269 public void fireFilterWrite(WriteRequest writeRequest); 270 271 /** 272 * Fires a {@link IoSession#close()} event. Most users don't need to call this method at 273 * all. Please use this method only when you implement a new transport or fire a virtual 274 * event. 275 */ 276 public void fireFilterClose(); 277 278 /** 279 * Fires a {@link IoSession#setTrafficMask(TrafficMask)} event. Most users don't need to call this method at 280 * all. Please use this method only when you implement a new transport or fire a virtual 281 * event. 282 */ 283 public void fireFilterSetTrafficMask(TrafficMask trafficMask); 284 285 /** 286 * Represents a name-filter pair that an {@link IoFilterChain} contains. 287 * 288 * @author The Apache MINA Project (dev@mina.apache.org) 289 * @version $Rev: 593474 $, $Date: 2007-11-09 03:14:12 -0700 (Fri, 09 Nov 2007) $ 290 */ 291 public interface Entry { 292 /** 293 * Returns the name of the filter. 294 */ 295 String getName(); 296 297 /** 298 * Returns the filter. 299 */ 300 IoFilter getFilter(); 301 302 /** 303 * Returns the {@link NextFilter} of the filter. 304 * 305 * @throws IllegalStateException if the {@link NextFilter} is not available 306 */ 307 NextFilter getNextFilter(); 308 309 /** 310 * Adds the specified filter with the specified name just before this entry. 311 * @throws IoFilterLifeCycleException 312 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or 313 * {@link IoFilter#init()} throws an exception. 314 */ 315 void addBefore(String name, IoFilter filter); 316 317 /** 318 * Adds the specified filter with the specified name just after this entry. 319 * @throws IoFilterLifeCycleException 320 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or 321 * {@link IoFilter#init()} throws an exception. 322 */ 323 void addAfter(String name, IoFilter filter); 324 325 /** 326 * Replace the filter of this entry with the specified new filter. 327 * 328 * @throws IllegalArgumentException if there's no such filter 329 */ 330 void replace(IoFilter newFilter); 331 332 /** 333 * Removes this entry from the chain it belongs to. 334 */ 335 void remove(); 336 } 337 }