001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: *
019: */
020: package org.apache.mina.common;
021:
022: import org.apache.mina.filter.util.ReferenceCountingFilter;
023:
024: /**
025: * A filter which intercepts {@link IoHandler} events like Servlet
026: * filters. Filters can be used for these purposes:
027: * <ul>
028: * <li>Event logging,</li>
029: * <li>Performance measurement,</li>
030: * <li>Authorization,</li>
031: * <li>Overload control,</li>
032: * <li>Message transformation (e.g. encryption and decryption, ...),</li>
033: * <li>and many more.</li>
034: * </ul>
035: * <p>
036: * <strong>Please NEVER implement your filters to wrap
037: * {@link IoSession}s.</strong> Users can cache the reference to the
038: * session, which might malfunction if any filters are added or removed later.
039: *
040: * <h3>The Life Cycle</h3>
041: * {@link IoFilter}s are activated only when they are inside {@link IoFilterChain}.
042: * <p>
043: * When you add an {@link IoFilter} to an {@link IoFilterChain}:
044: * <ol>
045: * <li>{@link #init()} is invoked by {@link ReferenceCountingFilter} if
046: * the filter is added at the first time.</li>
047: * <li>{@link #onPreAdd(IoFilterChain, String, NextFilter)} is invoked to notify
048: * that the filter will be added to the chain.</li>
049: * <li>The filter is added to the chain, and all events and I/O requests
050: * pass through the filter from now.</li>
051: * <li>{@link #onPostAdd(IoFilterChain, String, NextFilter)} is invoked to notify
052: * that the filter is added to the chain.</li>
053: * <li>The filter is removed from the chain if {@link #onPostAdd(IoFilterChain, String, org.apache.mina.common.IoFilter.NextFilter)}
054: * threw an exception. {@link #destroy()} is also invoked by
055: * {@link ReferenceCountingFilter} if the filter is the last filter which
056: * was added to {@link IoFilterChain}s.</li>
057: * </ol>
058: * <p>
059: * When you remove an {@link IoFilter} from an {@link IoFilterChain}:
060: * <ol>
061: * <li>{@link #onPreRemove(IoFilterChain, String, NextFilter)} is invoked to
062: * notify that the filter will be removed from the chain.</li>
063: * <li>The filter is removed from the chain, and any events and I/O requests
064: * don't pass through the filter from now.</li>
065: * <li>{@link #onPostRemove(IoFilterChain, String, NextFilter)} is invoked to
066: * notify that the filter is removed from the chain.</li>
067: * <li>{@link #destroy()} is invoked by {@link ReferenceCountingFilter} if
068: * the removed filter was the last one.</li>
069: * </ol>
070: *
071: * @author The Apache MINA Project (dev@mina.apache.org)
072: * @version $Rev: 591770 $, $Date: 2007-11-04 05:22:44 -0700 (Sun, 04 Nov 2007) $
073: *
074: * @see IoFilterAdapter
075: */
076: public interface IoFilter {
077: /**
078: * Invoked by {@link ReferenceCountingFilter} when this filter
079: * is added to a {@link IoFilterChain} at the first time, so you can
080: * initialize shared resources. Please note that this method is never
081: * called if you don't wrap a filter with {@link ReferenceCountingFilter}.
082: */
083: void init() throws Exception;
084:
085: /**
086: * Invoked by {@link ReferenceCountingFilter} when this filter
087: * is not used by any {@link IoFilterChain} anymore, so you can destroy
088: * shared resources. Please note that this method is never called if
089: * you don't wrap a filter with {@link ReferenceCountingFilter}.
090: */
091: void destroy() throws Exception;
092:
093: /**
094: * Invoked before this filter is added to the specified <tt>parent</tt>.
095: * Please note that this method can be invoked more than once if
096: * this filter is added to more than one parents. This method is not
097: * invoked before {@link #init()} is invoked.
098: *
099: * @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,
105: NextFilter nextFilter) 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,
119: NextFilter nextFilter) 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,
133: NextFilter nextFilter) 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,
147: NextFilter nextFilter) 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,
172: IdleStatus status) 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)
199: throws Exception;
200:
201: /**
202: * Filters {@link IoSession#write(Object)} method invocation.
203: */
204: void filterWrite(NextFilter nextFilter, IoSession session,
205: WriteRequest writeRequest) throws Exception;
206:
207: /**
208: * Filters {@link IoSession#setTrafficMask(TrafficMask)} method invocation.
209: */
210: void filterSetTrafficMask(NextFilter nextFilter, IoSession session,
211: TrafficMask trafficMask) throws Exception;
212:
213: /**
214: * Represents the next {@link IoFilter} in {@link IoFilterChain}.
215: */
216: public interface NextFilter {
217: /**
218: * Forwards <tt>sessionCreated</tt> event to next filter.
219: */
220: void sessionCreated(IoSession session);
221:
222: /**
223: * Forwards <tt>sessionOpened</tt> event to next filter.
224: */
225: void sessionOpened(IoSession session);
226:
227: /**
228: * Forwards <tt>sessionClosed</tt> event to next filter.
229: */
230: void sessionClosed(IoSession session);
231:
232: /**
233: * Forwards <tt>sessionIdle</tt> event to next filter.
234: */
235: void sessionIdle(IoSession session, IdleStatus status);
236:
237: /**
238: * Forwards <tt>exceptionCaught</tt> event to next filter.
239: */
240: void exceptionCaught(IoSession session, Throwable cause);
241:
242: /**
243: * Forwards <tt>messageReceived</tt> event to next filter.
244: */
245: void messageReceived(IoSession session, Object message);
246:
247: /**
248: * Forwards <tt>messageSent</tt> event to next filter.
249: */
250: void messageSent(IoSession session, WriteRequest writeRequest);
251:
252: /**
253: * Forwards <tt>filterWrite</tt> event to next filter.
254: */
255: void filterWrite(IoSession session, WriteRequest writeRequest);
256:
257: /**
258: * Forwards <tt>filterClose</tt> event to next filter.
259: */
260: void filterClose(IoSession session);
261:
262: /**
263: * Forwards <tt>filterSetTrafficMask</tt> event to next filter.
264: */
265: void filterSetTrafficMask(IoSession session,
266: TrafficMask trafficMask);
267: }
268: }
|