1/*2 * Licensed to the Apache Software Foundation (ASF) under one3 * or more contributor license agreements. See the NOTICE file4 * distributed with this work for additional information5 * regarding copyright ownership. The ASF licenses this file6 * to you under the Apache License, Version 2.0 (the7 * "License"); you may not use this file except in compliance8 * with the License. You may obtain a copy of the License at9 *10 * http://www.apache.org/licenses/LICENSE-2.011 *12 * Unless required by applicable law or agreed to in writing,13 * software distributed under the License is distributed on an14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY15 * KIND, either express or implied. See the License for the16 * specific language governing permissions and limitations17 * under the License.18 *19 */20package org.apache.mina.core.filterchain;
2122import org.apache.mina.core.service.IoHandler;
23import org.apache.mina.core.session.IdleStatus;
24import org.apache.mina.core.session.IoSession;
25import org.apache.mina.core.write.WriteRequest;
26import org.apache.mina.filter.util.ReferenceCountingFilter;
2728/**29 * A filter which intercepts {@link IoHandler} events like Servlet30 * 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 wrap41 * {@link IoSession}s.</strong> Users can cache the reference to the42 * 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} if50 * the filter is added at the first time.</li>51 * <li>{@link #onPreAdd(IoFilterChain, String, NextFilter)} is invoked to notify52 * 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 requests54 * pass through the filter from now.</li>55 * <li>{@link #onPostAdd(IoFilterChain, String, NextFilter)} is invoked to notify56 * 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 by59 * {@link ReferenceCountingFilter} if the filter is the last filter which60 * 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 to66 * 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 requests68 * don't pass through the filter from now.</li>69 * <li>{@link #onPostRemove(IoFilterChain, String, NextFilter)} is invoked to70 * notify that the filter is removed from the chain.</li>71 * <li>{@link #destroy()} is invoked by {@link ReferenceCountingFilter} if72 * the removed filter was the last one.</li>73 * </ol>74 *75 * @author <a href="http://mina.apache.org">Apache MINA Project</a>76 *77 * @see IoFilterAdapter78 */79publicinterfaceIoFilter {
80/**81 * Invoked by {@link ReferenceCountingFilter} when this filter82 * is added to a {@link IoFilterChain} at the first time, so you can83 * initialize shared resources. Please note that this method is never84 * called if you don't wrap a filter with {@link ReferenceCountingFilter}.85 */86void init() throws Exception;
8788/**89 * Invoked by {@link ReferenceCountingFilter} when this filter90 * is not used by any {@link IoFilterChain} anymore, so you can destroy91 * shared resources. Please note that this method is never called if92 * you don't wrap a filter with {@link ReferenceCountingFilter}.93 */94void destroy() throws Exception;
9596/**97 * Invoked before this filter is added to the specified <tt>parent</tt>.98 * Please note that this method can be invoked more than once if99 * this filter is added to more than one parents. This method is not100 * invoked before {@link #init()} is invoked.101 *102 * @param parent the parent who called this method103 * @param name the name assigned to this filter104 * @param nextFilter the {@link NextFilter} for this filter. You can reuse105 * this object until this filter is removed from the chain.106 */107void onPreAdd(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
108109/**110 * Invoked after this filter is added to the specified <tt>parent</tt>.111 * Please note that this method can be invoked more than once if112 * this filter is added to more than one parents. This method is not113 * invoked before {@link #init()} is invoked.114 *115 * @param parent the parent who called this method116 * @param name the name assigned to this filter117 * @param nextFilter the {@link NextFilter} for this filter. You can reuse118 * this object until this filter is removed from the chain.119 */120void onPostAdd(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
121122/**123 * Invoked before this filter is removed from the specified <tt>parent</tt>.124 * Please note that this method can be invoked more than once if125 * this filter is removed from more than one parents.126 * This method is always invoked before {@link #destroy()} is invoked.127 *128 * @param parent the parent who called this method129 * @param name the name assigned to this filter130 * @param nextFilter the {@link NextFilter} for this filter. You can reuse131 * this object until this filter is removed from the chain.132 */133void onPreRemove(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
134135/**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 if138 * 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 method142 * @param name the name assigned to this filter143 * @param nextFilter the {@link NextFilter} for this filter. You can reuse144 * this object until this filter is removed from the chain.145 */146void onPostRemove(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
147148/**149 * Filters {@link IoHandler#sessionCreated(IoSession)} event.150 * 151 * @param nextFilter152 * the {@link NextFilter} for this filter. You can reuse this153 * object until this filter is removed from the chain.154 * @param session155 * The {@link IoSession} which has received this event156 */157void sessionCreated(NextFilter nextFilter, IoSession session) throws Exception;
158159/**160 * Filters {@link IoHandler#sessionOpened(IoSession)} event.161 * 162 * @param nextFilter163 * the {@link NextFilter} for this filter. You can reuse this164 * object until this filter is removed from the chain.165 * @param session166 * The {@link IoSession} which has received this event167 */168void sessionOpened(NextFilter nextFilter, IoSession session) throws Exception;
169170/**171 * Filters {@link IoHandler#sessionClosed(IoSession)} event.172 * 173 * @param nextFilter174 * the {@link NextFilter} for this filter. You can reuse this175 * object until this filter is removed from the chain.176 * @param session177 * The {@link IoSession} which has received this event178 */179void sessionClosed(NextFilter nextFilter, IoSession session) throws Exception;
180181/**182 * Filters {@link IoHandler#sessionIdle(IoSession,IdleStatus)} event.183 * 184 * @param nextFilter185 * the {@link NextFilter} for this filter. You can reuse this186 * object until this filter is removed from the chain.187 * @param session188 * The {@link IoSession} which has received this event189 * @param status190 * The {@link IdleStatus} type191 */192void sessionIdle(NextFilter nextFilter, IoSession session, IdleStatus status) throws Exception;
193194/**195 * Filters {@link IoHandler#exceptionCaught(IoSession,Throwable)} event.196 * 197 * @param nextFilter198 * the {@link NextFilter} for this filter. You can reuse this199 * object until this filter is removed from the chain.200 * @param session201 * The {@link IoSession} which has received this event202 * @param cause203 * The exception that cause this event to be received204 */205void exceptionCaught(NextFilter nextFilter, IoSession session, Throwable cause) throws Exception;
206207/**208 * Filters {@link IoHandler#inputClosed(IoSession)} event.209 * 210 * @param nextFilter211 * the {@link NextFilter} for this filter. You can reuse this212 * object until this filter is removed from the chain.213 * @param session214 * The {@link IoSession} which has received this event215 */216void inputClosed(NextFilter nextFilter, IoSession session) throws Exception;
217218/**219 * Filters {@link IoHandler#messageReceived(IoSession,Object)} event.220 * 221 * @param nextFilter222 * the {@link NextFilter} for this filter. You can reuse this223 * object until this filter is removed from the chain.224 * @param session225 * The {@link IoSession} which has received this event226 * @param message227 * The received message228 */229void messageReceived(NextFilter nextFilter, IoSession session, Object message) throws Exception;
230231/**232 * Filters {@link IoHandler#messageSent(IoSession,Object)} event.233 * 234 * @param nextFilter235 * the {@link NextFilter} for this filter. You can reuse this236 * object until this filter is removed from the chain.237 * @param session238 * The {@link IoSession} which has received this event239 * @param writeRequest240 * The {@link WriteRequest} that contains the sent message241 */242void messageSent(NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws Exception;
243244/**245 * Filters {@link IoSession#close()} method invocation.246 * 247 * @param nextFilter248 * the {@link NextFilter} for this filter. You can reuse this249 * object until this filter is removed from the chain.250 * @param session251 * The {@link IoSession} which has to process this method252 * invocation253 */254void filterClose(NextFilter nextFilter, IoSession session) throws Exception;
255256/**257 * Filters {@link IoSession#write(Object)} method invocation.258 * 259 * @param nextFilter260 * the {@link NextFilter} for this filter. You can reuse this261 * object until this filter is removed from the chain.262 * @param session263 * The {@link IoSession} which has to process this invocation264 * @param writeRequest265 * The {@link WriteRequest} to process266 */267void filterWrite(NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws Exception;
268269/**270 * Represents the next {@link IoFilter} in {@link IoFilterChain}.271 */272publicinterfaceNextFilter {
273/**274 * Forwards <tt>sessionCreated</tt> event to next filter.275 */276void sessionCreated(IoSession session);
277278/**279 * Forwards <tt>sessionOpened</tt> event to next filter.280 */281void sessionOpened(IoSession session);
282283/**284 * Forwards <tt>sessionClosed</tt> event to next filter.285 */286void sessionClosed(IoSession session);
287288/**289 * Forwards <tt>sessionIdle</tt> event to next filter.290 */291void sessionIdle(IoSession session, IdleStatus status);
292293/**294 * Forwards <tt>exceptionCaught</tt> event to next filter.295 */296void exceptionCaught(IoSession session, Throwable cause);
297298void inputClosed(IoSession session);
299300/**301 * Forwards <tt>messageReceived</tt> event to next filter.302 */303void messageReceived(IoSession session, Object message);
304305/**306 * Forwards <tt>messageSent</tt> event to next filter.307 */308void messageSent(IoSession session, WriteRequest writeRequest);
309310/**311 * Forwards <tt>filterWrite</tt> event to next filter.312 */313void filterWrite(IoSession session, WriteRequest writeRequest);
314315/**316 * Forwards <tt>filterClose</tt> event to next filter.317 */318void filterClose(IoSession session);
319320 }
321 }