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 org.apache.mina.core.service.IoHandler; 23 import org.apache.mina.core.session.IdleStatus; 24 import org.apache.mina.core.session.IoSession; 25 import org.apache.mina.core.session.TrafficMask; 26 import org.apache.mina.core.write.WriteRequest; 27 import org.apache.mina.filter.util.ReferenceCountingFilter; 28 29 /** 30 * A filter which intercepts {@link IoHandler} events like Servlet 31 * filters. Filters can be used for these purposes: 32 * <ul> 33 * <li>Event logging,</li> 34 * <li>Performance measurement,</li> 35 * <li>Authorization,</li> 36 * <li>Overload control,</li> 37 * <li>Message transformation (e.g. encryption and decryption, ...),</li> 38 * <li>and many more.</li> 39 * </ul> 40 * <p> 41 * <strong>Please NEVER implement your filters to wrap 42 * {@link IoSession}s.</strong> Users can cache the reference to the 43 * session, which might malfunction if any filters are added or removed later. 44 * 45 * <h3>The Life Cycle</h3> 46 * {@link IoFilter}s are activated only when they are inside {@link IoFilterChain}. 47 * <p> 48 * When you add an {@link IoFilter} to an {@link IoFilterChain}: 49 * <ol> 50 * <li>{@link #init()} is invoked by {@link ReferenceCountingFilter} if 51 * the filter is added at the first time.</li> 52 * <li>{@link #onPreAdd(IoFilterChain, String, NextFilter)} is invoked to notify 53 * that the filter will be added to the chain.</li> 54 * <li>The filter is added to the chain, and all events and I/O requests 55 * pass through the filter from now.</li> 56 * <li>{@link #onPostAdd(IoFilterChain, String, NextFilter)} is invoked to notify 57 * that the filter is added to the chain.</li> 58 * <li>The filter is removed from the chain if {@link #onPostAdd(IoFilterChain, String, org.apache.mina.core.filterchain.IoFilter.NextFilter)} 59 * threw an exception. {@link #destroy()} is also invoked by 60 * {@link ReferenceCountingFilter} if the filter is the last filter which 61 * was added to {@link IoFilterChain}s.</li> 62 * </ol> 63 * <p> 64 * When you remove an {@link IoFilter} from an {@link IoFilterChain}: 65 * <ol> 66 * <li>{@link #onPreRemove(IoFilterChain, String, NextFilter)} is invoked to 67 * notify that the filter will be removed from the chain.</li> 68 * <li>The filter is removed from the chain, and any events and I/O requests 69 * don't pass through the filter from now.</li> 70 * <li>{@link #onPostRemove(IoFilterChain, String, NextFilter)} is invoked to 71 * notify that the filter is removed from the chain.</li> 72 * <li>{@link #destroy()} is invoked by {@link ReferenceCountingFilter} if 73 * the removed filter was the last one.</li> 74 * </ol> 75 * 76 * @author The Apache MINA Project (dev@mina.apache.org) 77 * @version $Rev: 591770 $, $Date: 2007-11-04 13:22:44 +0100 (Sun, 04 Nov 2007) $ 78 * 79 * @see IoFilterAdapter 80 */ 81 public interface IoFilter { 82 /** 83 * Invoked by {@link ReferenceCountingFilter} when this filter 84 * is added to a {@link IoFilterChain} at the first time, so you can 85 * initialize shared resources. Please note that this method is never 86 * called if you don't wrap a filter with {@link ReferenceCountingFilter}. 87 */ 88 void init() throws Exception; 89 90 /** 91 * Invoked by {@link ReferenceCountingFilter} when this filter 92 * is not used by any {@link IoFilterChain} anymore, so you can destroy 93 * shared resources. Please note that this method is never called if 94 * you don't wrap a filter with {@link ReferenceCountingFilter}. 95 */ 96 void destroy() throws Exception; 97 98 /** 99 * Invoked before this filter is added to the specified <tt>parent</tt>. 100 * Please note that this method can be invoked more than once if 101 * this filter is added to more than one parents. This method is not 102 * invoked before {@link #init()} is invoked. 103 * 104 * @param parent the parent who called this method 105 * @param name the name assigned to this filter 106 * @param nextFilter the {@link NextFilter} for this filter. You can reuse 107 * this object until this filter is removed from the chain. 108 */ 109 void onPreAdd(IoFilterChain parent, String name, NextFilter nextFilter) 110 throws Exception; 111 112 /** 113 * Invoked after this filter is added to the specified <tt>parent</tt>. 114 * Please note that this method can be invoked more than once if 115 * this filter is added to more than one parents. This method is not 116 * invoked before {@link #init()} is invoked. 117 * 118 * @param parent the parent who called this method 119 * @param name the name assigned to this filter 120 * @param nextFilter the {@link NextFilter} for this filter. You can reuse 121 * this object until this filter is removed from the chain. 122 */ 123 void onPostAdd(IoFilterChain parent, String name, NextFilter nextFilter) 124 throws Exception; 125 126 /** 127 * Invoked before this filter is removed from the specified <tt>parent</tt>. 128 * Please note that this method can be invoked more than once if 129 * this filter is removed from more than one parents. 130 * This method is always invoked before {@link #destroy()} is invoked. 131 * 132 * @param parent the parent who called this method 133 * @param name the name assigned to this filter 134 * @param nextFilter the {@link NextFilter} for this filter. You can reuse 135 * this object until this filter is removed from the chain. 136 */ 137 void onPreRemove(IoFilterChain parent, String name, NextFilter nextFilter) 138 throws Exception; 139 140 /** 141 * Invoked after this filter is removed from the specified <tt>parent</tt>. 142 * Please note that this method can be invoked more than once if 143 * this filter is removed from more than one parents. 144 * This method is always invoked before {@link #destroy()} is invoked. 145 * 146 * @param parent the parent who called this method 147 * @param name the name assigned to this filter 148 * @param nextFilter the {@link NextFilter} for this filter. You can reuse 149 * this object until this filter is removed from the chain. 150 */ 151 void onPostRemove(IoFilterChain parent, String name, NextFilter nextFilter) 152 throws Exception; 153 154 /** 155 * Filters {@link IoHandler#sessionCreated(IoSession)} event. 156 */ 157 void sessionCreated(NextFilter nextFilter, IoSession session) 158 throws Exception; 159 160 /** 161 * Filters {@link IoHandler#sessionOpened(IoSession)} event. 162 */ 163 void sessionOpened(NextFilter nextFilter, IoSession session) 164 throws Exception; 165 166 /** 167 * Filters {@link IoHandler#sessionClosed(IoSession)} event. 168 */ 169 void sessionClosed(NextFilter nextFilter, IoSession session) 170 throws Exception; 171 172 /** 173 * Filters {@link IoHandler#sessionIdle(IoSession,IdleStatus)} 174 * event. 175 */ 176 void sessionIdle(NextFilter nextFilter, IoSession session, IdleStatus status) 177 throws Exception; 178 179 /** 180 * Filters {@link IoHandler#exceptionCaught(IoSession,Throwable)} 181 * event. 182 */ 183 void exceptionCaught(NextFilter nextFilter, IoSession session, 184 Throwable cause) throws Exception; 185 186 /** 187 * Filters {@link IoHandler#messageReceived(IoSession,Object)} 188 * event. 189 */ 190 void messageReceived(NextFilter nextFilter, IoSession session, 191 Object message) throws Exception; 192 193 /** 194 * Filters {@link IoHandler#messageSent(IoSession,Object)} 195 * event. 196 */ 197 void messageSent(NextFilter nextFilter, IoSession session, 198 WriteRequest writeRequest) throws Exception; 199 200 /** 201 * Filters {@link IoSession#close()} method invocation. 202 */ 203 void filterClose(NextFilter nextFilter, IoSession session) throws Exception; 204 205 /** 206 * Filters {@link IoSession#write(Object)} method invocation. 207 */ 208 void filterWrite(NextFilter nextFilter, IoSession session, 209 WriteRequest writeRequest) throws Exception; 210 211 /** 212 * Filters {@link IoSession#setTrafficMask(TrafficMask)} method invocation. 213 */ 214 void filterSetTrafficMask( 215 NextFilter nextFilter, IoSession session, TrafficMask trafficMask) throws Exception; 216 217 /** 218 * Represents the next {@link IoFilter} in {@link IoFilterChain}. 219 */ 220 public interface NextFilter { 221 /** 222 * Forwards <tt>sessionCreated</tt> event to next filter. 223 */ 224 void sessionCreated(IoSession session); 225 226 /** 227 * Forwards <tt>sessionOpened</tt> event to next filter. 228 */ 229 void sessionOpened(IoSession session); 230 231 /** 232 * Forwards <tt>sessionClosed</tt> event to next filter. 233 */ 234 void sessionClosed(IoSession session); 235 236 /** 237 * Forwards <tt>sessionIdle</tt> event to next filter. 238 */ 239 void sessionIdle(IoSession session, IdleStatus status); 240 241 /** 242 * Forwards <tt>exceptionCaught</tt> event to next filter. 243 */ 244 void exceptionCaught(IoSession session, Throwable cause); 245 246 /** 247 * Forwards <tt>messageReceived</tt> event to next filter. 248 */ 249 void messageReceived(IoSession session, Object message); 250 251 /** 252 * Forwards <tt>messageSent</tt> event to next filter. 253 */ 254 void messageSent(IoSession session, WriteRequest writeRequest); 255 256 /** 257 * Forwards <tt>filterWrite</tt> event to next filter. 258 */ 259 void filterWrite(IoSession session, WriteRequest writeRequest); 260 261 /** 262 * Forwards <tt>filterClose</tt> event to next filter. 263 */ 264 void filterClose(IoSession session); 265 266 /** 267 * Forwards <tt>filterSetTrafficMask</tt> event to next filter. 268 */ 269 void filterSetTrafficMask(IoSession session, TrafficMask trafficMask); 270 } 271 }