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 30 /** 31 * A container of {@link IoFilter}s that forwards {@link IoHandler} events 32 * to the consisting filters and terminal {@link IoHandler} sequentially. 33 * Every {@link IoSession} has its own {@link IoFilterChain} (1-to-1 relationship). 34 * 35 * @author The Apache MINA Project (dev@mina.apache.org) 36 * @version $Rev: 593474 $, $Date: 2007-11-09 11:14:12 +0100 (Fri, 09 Nov 2007) $ 37 */ 38 public interface IoFilterChain { 39 /** 40 * Returns the parent {@link IoSession} of this chain. 41 * @return {@link IoSession} 42 */ 43 IoSession getSession(); 44 45 /** 46 * Returns the {@link Entry} with the specified <tt>name</tt> in this chain. 47 * @return <tt>null</tt> if there's no such name in this chain 48 */ 49 Entry getEntry(String name); 50 51 /** 52 * Returns the {@link Entry} with the specified <tt>filter</tt> in this chain. 53 * @return <tt>null</tt> if there's no such filter in this chain 54 */ 55 Entry getEntry(IoFilter filter); 56 57 /** 58 * Returns the {@link Entry} with the specified <tt>filterType</tt> 59 * in this chain. If there's more than one filter with the specified 60 * type, the first match will be chosen. 61 * @return <tt>null</tt> if there's no such name in this chain 62 */ 63 Entry getEntry(Class<? extends IoFilter> filterType); 64 65 /** 66 * Returns the {@link IoFilter} with the specified <tt>name</tt> in this chain. 67 * @return <tt>null</tt> if there's no such name in this chain 68 */ 69 IoFilter get(String name); 70 71 /** 72 * Returns the {@link IoFilter} with the specified <tt>filterType</tt> 73 * in this chain. If there's more than one filter with the specified 74 * type, the first match will be chosen. 75 * @return <tt>null</tt> if there's no such name in this chain 76 */ 77 IoFilter get(Class<? extends IoFilter> filterType); 78 79 /** 80 * Returns the {@link NextFilter} of the {@link IoFilter} with the 81 * specified <tt>name</tt> in this chain. 82 * @return <tt>null</tt> if there's no such name in this chain 83 */ 84 NextFilter getNextFilter(String name); 85 86 /** 87 * Returns the {@link NextFilter} of the specified {@link IoFilter} 88 * in this chain. 89 * @return <tt>null</tt> if there's no such name in this chain 90 */ 91 NextFilter getNextFilter(IoFilter filter); 92 93 /** 94 * Returns the {@link NextFilter} of the specified <tt>filterType</tt> 95 * in this chain. If there's more than one filter with the specified 96 * type, the first match will be chosen. 97 * @return <tt>null</tt> if there's no such name in this chain 98 */ 99 NextFilter getNextFilter(Class<? extends IoFilter> filterType); 100 101 /** 102 * Returns the list of all {@link Entry}s this chain contains. 103 */ 104 List<Entry> getAll(); 105 106 /** 107 * Returns the reversed list of all {@link Entry}s this chain contains. 108 */ 109 List<Entry> getAllReversed(); 110 111 /** 112 * Returns <tt>true</tt> if this chain contains an {@link IoFilter} with the 113 * specified <tt>name</tt>. 114 */ 115 boolean contains(String name); 116 117 /** 118 * Returns <tt>true</tt> if this chain contains the specified <tt>filter</tt>. 119 */ 120 boolean contains(IoFilter filter); 121 122 /** 123 * Returns <tt>true</tt> if this chain contains an {@link IoFilter} of the 124 * specified <tt>filterType</tt>. 125 */ 126 boolean contains(Class<? extends IoFilter> filterType); 127 128 /** 129 * Adds the specified filter with the specified name at the beginning of this chain. 130 * @throws IoFilterLifeCycleException 131 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or 132 * {@link IoFilter#init()} throws an exception. 133 */ 134 void addFirst(String name, IoFilter filter); 135 136 /** 137 * Adds the specified filter with the specified name at the end of this chain. 138 * @throws IoFilterLifeCycleException 139 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or 140 * {@link IoFilter#init()} throws an exception. 141 */ 142 void addLast(String name, IoFilter filter); 143 144 /** 145 * Adds the specified filter with the specified name just before the filter whose name is 146 * <code>baseName</code> in this chain. 147 * @throws IoFilterLifeCycleException 148 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or 149 * {@link IoFilter#init()} throws an exception. 150 */ 151 void addBefore(String baseName, String name, IoFilter filter); 152 153 /** 154 * Adds the specified filter with the specified name just after the filter whose name is 155 * <code>baseName</code> in this chain. 156 * @throws IoFilterLifeCycleException 157 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or 158 * {@link IoFilter#init()} throws an exception. 159 */ 160 void addAfter(String baseName, String name, IoFilter filter); 161 162 /** 163 * Replace the filter with the specified name with the specified new 164 * filter. 165 * 166 * @return the old filter 167 * @throws IllegalArgumentException if there's no such filter 168 */ 169 IoFilter replace(String name, IoFilter newFilter); 170 171 /** 172 * Replace the filter with the specified name with the specified new 173 * filter. 174 * 175 * @throws IllegalArgumentException if there's no such filter 176 */ 177 void replace(IoFilter oldFilter, IoFilter newFilter); 178 179 /** 180 * Replace the filter of the specified type with the specified new 181 * filter. If there's more than one filter with the specified type, 182 * the first match will be replaced. 183 * 184 * @throws IllegalArgumentException if there's no such filter 185 */ 186 IoFilter replace(Class<? extends IoFilter> oldFilterType, IoFilter newFilter); 187 188 /** 189 * Removes the filter with the specified name from this chain. 190 * @throws IoFilterLifeCycleException 191 * if {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)} or 192 * {@link IoFilter#destroy()} throws an exception. 193 */ 194 IoFilter remove(String name); 195 196 /** 197 * Replace the filter with the specified name with the specified new 198 * filter. 199 * 200 * @throws IllegalArgumentException if there's no such filter 201 */ 202 void remove(IoFilter filter); 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 * @throws IllegalArgumentException if there's no such filter 210 */ 211 IoFilter remove(Class<? extends IoFilter> filterType); 212 213 /** 214 * Removes all filters added to this chain. 215 * @throws Exception if {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)} thrown an exception. 216 */ 217 void clear() throws Exception; 218 219 /** 220 * Fires a {@link IoHandler#sessionCreated(IoSession)} event. Most users don't need to 221 * call this method at all. Please use this method only when you implement a new transport 222 * or fire a virtual event. 223 */ 224 public void fireSessionCreated(); 225 226 /** 227 * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call 228 * this method at all. Please use this method only when you implement a new transport or 229 * fire a virtual event. 230 */ 231 public void fireSessionOpened(); 232 233 /** 234 * Fires a {@link IoHandler#sessionClosed(IoSession)} event. Most users don't need to call 235 * this method at all. Please use this method only when you implement a new transport or 236 * fire a virtual event. 237 */ 238 public void fireSessionClosed(); 239 240 /** 241 * Fires a {@link IoHandler#sessionIdle(IoSession, IdleStatus)} event. Most users don't 242 * need to call this method at all. Please use this method only when you implement a new 243 * transport or fire a virtual event. 244 */ 245 public void fireSessionIdle(IdleStatus status); 246 247 /** 248 * Fires a {@link #fireMessageReceived(Object)} 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 public void fireMessageReceived(Object message); 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 public void fireMessageSent(WriteRequest request); 260 261 /** 262 * Fires a {@link IoHandler#exceptionCaught(IoSession, Throwable)} event. Most users don't 263 * need to call this method at all. Please use this method only when you implement a new 264 * transport or fire a virtual event. 265 */ 266 public void fireExceptionCaught(Throwable cause); 267 268 /** 269 * Fires a {@link IoSession#write(Object)} event. Most users don't need to call this 270 * method at all. Please use this method only when you implement a new transport or fire a 271 * virtual event. 272 */ 273 public void fireFilterWrite(WriteRequest writeRequest); 274 275 /** 276 * Fires a {@link IoSession#close()} event. Most users don't need to call this method at 277 * all. Please use this method only when you implement a new transport or fire a virtual 278 * event. 279 */ 280 public void fireFilterClose(); 281 282 /** 283 * Represents a name-filter pair that an {@link IoFilterChain} contains. 284 * 285 * @author The Apache MINA Project (dev@mina.apache.org) 286 * @version $Rev: 593474 $, $Date: 2007-11-09 11:14:12 +0100 (Fri, 09 Nov 2007) $ 287 */ 288 public interface Entry { 289 /** 290 * Returns the name of the filter. 291 */ 292 String getName(); 293 294 /** 295 * Returns the filter. 296 */ 297 IoFilter getFilter(); 298 299 /** 300 * Returns the {@link NextFilter} of the filter. 301 * 302 * @throws IllegalStateException if the {@link NextFilter} is not available 303 */ 304 NextFilter getNextFilter(); 305 306 /** 307 * Adds the specified filter with the specified name just before this entry. 308 * @throws IoFilterLifeCycleException 309 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or 310 * {@link IoFilter#init()} throws an exception. 311 */ 312 void addBefore(String name, IoFilter filter); 313 314 /** 315 * Adds the specified filter with the specified name just after this entry. 316 * @throws IoFilterLifeCycleException 317 * if {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)} or 318 * {@link IoFilter#init()} throws an exception. 319 */ 320 void addAfter(String name, IoFilter filter); 321 322 /** 323 * Replace the filter of this entry with the specified new filter. 324 * 325 * @throws IllegalArgumentException if there's no such filter 326 */ 327 void replace(IoFilter newFilter); 328 329 /** 330 * Removes this entry from the chain it belongs to. 331 */ 332 void remove(); 333 } 334 }