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