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