mina/common/IoFilter.java

/*
 *   @(#) $Id$
 *
 *   Copyright 2004 The Apache Software Foundation
 *
 *   Licensed under the Apache License, Version 2.0 (the "License");
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *   limitations under the License.
 *
 */
package org.apache.mina.common;


/**
 * A filter which intercepts {@link IoHandler} events like Servlet
 * filters.  Filters can be used for these purposes:
 * <ul>
 *   <li>Event logging,</li>
 *   <li>Performance measurement,</li>
 *   <li>Authorization,</li>
 *   <li>Overload control,</li>
 *   <li>Message transformation (e.g. encryption and decryption, ...),</li>
 *   <li>and many more.</li>
 * </ul>
 * <p>
 * <strong>Please NEVER implement your filters to wrap
 * {@link IoSession}s.</strong> Users can cache the reference to the
 * session, which might malfunction if any filters are added or removed later.
 * 
 * <h3>The Life Cycle</h3>
 * {@link IoFilter}s are activated only when they are inside {@link IoFilterChain}.
 * <p>
 * When you add an {@link IoFilter} to an {@link IoFilterChain}:
 * <ol>
 *   <li>{@link #init()} is invoked by {@link IoFilterChain} if the filter is
 *       added at the first time.</li>
 *   <li>{@link #onPreAdd(IoFilterChain, String, NextFilter)} is invoked to notify
 *       that the filter will be added to the chain.</li>
 *   <li>The filter is added to the chain, and all events and I/O requests
 *       pass through the filter from now.</li>
 *   <li>{@link #onPostAdd(IoFilterChain, String, NextFilter)} is invoked to notify
 *       that the filter is added to the chain.</li>
 *   <li>The filter is removed from the chain if {@link #onPostAdd(IoFilterChain, String, org.apache.mina.common.IoFilter.NextFilter)}
 *       threw an exception.  {@link #destroy()} is also invoked if the filter
 *       is the last filter which was added to {@link IoFilterChain}s.</li>
 * </ol>
 * <p>
 * When you remove an {@link IoFilter} from an {@link IoFilterChain}:
 * <ol>
 *   <li>{@link #onPreRemove(IoFilterChain, String, NextFilter)} is invoked to
 *       notify that the filter will be removed from the chain.</li>
 *   <li>The filter is removed from the chain, and any events and I/O requests
 *       don't pass through the filter from now.</li>
 *   <li>{@link #onPostRemove(IoFilterChain, String, NextFilter)} is invoked to
 *       notify that the filter is removed from the chain.</li>
 *   <li>{@link #destroy()} is invoked if the removed filter was the last one.</li>
 * </ol>      
 * 
 * @author The Apache Directory Project (dev@directory.apache.org)
 * @version $Rev$, $Date$
 * 
 * @see IoFilterAdapter
 */
public interface IoFilter
{
    /**
     * Invoked when this filter is added to a {@link IoFilterChain}
     * at the first time, so you can initialize shared resources.
     */
    void init() throws Exception;

    /**
     * Invoked when this filter is not used by any {@link IoFilterChain}
     * anymore, so you can destroy shared resources.
     */
    void destroy() throws Exception;
    
    /**
     * Invoked before this filter is added to the specified <tt>parent</tt>.
     * Please note that this method can be invoked more than once if
     * this filter is added to more than one parents.  This method is not
     * invoked before {@link #init()} is invoked. 
     *
     * @param parent the parent who called this method
     * @param name the name assigned to this filter
     * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
     *                   this object until this filter is removed from the chain.
     */
    void onPreAdd( IoFilterChain parent, String name, NextFilter nextFilter ) throws Exception;
    
    /**
     * Invoked after this filter is added to the specified <tt>parent</tt>.
     * Please note that this method can be invoked more than once if
     * this filter is added to more than one parents.  This method is not
     * invoked before {@link #init()} is invoked. 
     *
     * @param parent the parent who called this method
     * @param name the name assigned to this filter
     * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
     *                   this object until this filter is removed from the chain.
     */
    void onPostAdd( IoFilterChain parent, String name, NextFilter nextFilter ) throws Exception;
    
    /**
     * Invoked before this filter is removed from the specified <tt>parent</tt>.
     * Please note that this method can be invoked more than once if
     * this filter is removed from more than one parents.
     * This method is always invoked before {@link #destroy()} is invoked.
     *  
     * @param parent the parent who called this method
     * @param name the name assigned to this filter
     * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
     *                   this object until this filter is removed from the chain.
     */
    void onPreRemove( IoFilterChain parent, String name, NextFilter nextFilter ) throws Exception;
    
    /**
     * Invoked after this filter is removed from the specified <tt>parent</tt>.
     * Please note that this method can be invoked more than once if
     * this filter is removed from more than one parents.
     * This method is always invoked before {@link #destroy()} is invoked.
     *  
     * @param parent the parent who called this method
     * @param name the name assigned to this filter
     * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
     *                   this object until this filter is removed from the chain.
     */
    void onPostRemove( IoFilterChain parent, String name, NextFilter nextFilter ) throws Exception;
    
    /**
     * Filters {@link IoHandler#sessionCreated(IoSession)} event.
     */
    void sessionCreated( NextFilter nextFilter, IoSession session ) throws Exception;
    
    /**
     * Filters {@link IoHandler#sessionOpened(IoSession)} event.
     */
    void sessionOpened( NextFilter nextFilter, IoSession session ) throws Exception;

    /**
     * Filters {@link IoHandler#sessionClosed(IoSession)} event.
     */
    void sessionClosed( NextFilter nextFilter, IoSession session ) throws Exception;

    /**
     * Filters {@link IoHandler#sessionIdle(IoSession,IdleStatus)}
     * event.
     */
    void sessionIdle( NextFilter nextFilter, IoSession session,
                      IdleStatus status ) throws Exception;

    /**
     * Filters {@link IoHandler#exceptionCaught(IoSession,Throwable)}
     * event.
     */
    void exceptionCaught( NextFilter nextFilter,
                          IoSession session, Throwable cause ) throws Exception;

    /**
     * Filters {@link IoHandler#messageReceived(IoSession,Object)}
     * event.
     */
    void messageReceived( NextFilter nextFilter,
                          IoSession session, Object message ) throws Exception;

    /**
     * Filters {@link IoHandler#messageSent(IoSession,Object)}
     * event.
     */
    void messageSent( NextFilter nextFilter, IoSession session,
                      Object message ) throws Exception;

    /**
     * Filters {@link IoSession#close()} method invocation.
     */
    void filterClose( NextFilter nextFilter, IoSession session, CloseFuture closeFuture ) throws Exception;
    
    /**
     * Filters {@link IoSession#write(Object)} method invocation.
     */
    void filterWrite( NextFilter nextFilter, IoSession session, WriteRequest writeRequest ) throws Exception;
    
    /**
     * Represents the next {@link IoFilter} in {@link IoFilterChain}.
     */
    public interface NextFilter
    {
        /**
         * Forwards <tt>sessionCreated</tt> event to next filter.
         */
        void sessionCreated( IoSession session );
        
        /**
         * Forwards <tt>sessionOpened</tt> event to next filter.
         */
        void sessionOpened( IoSession session );

        /**
         * Forwards <tt>sessionClosed</tt> event to next filter.
         */
        void sessionClosed( IoSession session );

        /**
         * Forwards <tt>sessionIdle</tt> event to next filter.
         */
        void sessionIdle( IoSession session, IdleStatus status );

        /**
         * Forwards <tt>exceptionCaught</tt> event to next filter.
         */
        void exceptionCaught( IoSession session, Throwable cause );

        /**
         * Forwards <tt>messageReceived</tt> event to next filter.
         */
        void messageReceived( IoSession session, Object message );

        /**
         * Forwards <tt>messageSent</tt> event to next filter.
         */
        void messageSent( IoSession session, Object message );

        /**
         * Forwards <tt>filterWrite</tt> event to next filter.
         */
        void filterWrite( IoSession session, WriteRequest writeRequest );
        
        /**
         * Forwards <tt>filterClose</tt> event to next filter.
         */
        void filterClose( IoSession session, CloseFuture closeFuture );
    }
    
    /**
     * Represents write request fired by {@link IoSession#write(Object)}.
     */
    public static class WriteRequest
    {
        private static final WriteFuture UNUSED_FUTURE = new WriteFuture();
        
        private final Object message;
        private final WriteFuture future;
        
        /**
         * Creates a new instance without {@link WriteFuture}.  You'll get
         * an instance of {@link WriteFuture} even if you called this constructor
         * because {@link #getFuture()} will return a bogus future.
         */
        public WriteRequest( Object message )
        {
            this( message, null );
        }

        /**
         * Creates a new instance with {@link WriteFuture}.
         */
        public WriteRequest( Object message, WriteFuture future )
        {
            if( message == null )
            {
                throw new NullPointerException( "message" );
            }
            
            if( future == null )
            {
                future = UNUSED_FUTURE;
            }
            
            this.message = message;
            this.future = future;
        }

        /**
         * Returns {@link WriteFuture} that is associated with this write request.
         */
        public WriteFuture getFuture()
        {
            return future;
        }

        /**
         * Returns a message object to be written.
         */
        public Object getMessage()
        {
            return message;
        }
        
        public String toString()
        {
            return message.toString();
        }
    }
}
1	/*
2	* @(#) $Id$
3	*
4	* Copyright 2004 The Apache Software Foundation
5	*
6	* Licensed under the Apache License, Version 2.0 (the "License");
7	* you may not use this file except in compliance with the License.
8	* 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, software
13	* distributed under the License is distributed on an "AS IS" BASIS,
14	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15	* See the License for the specific language governing permissions and
16	* limitations under the License.
17	*
18	*/
19	package org.apache.mina.common;
20
21
22
23	/**
24	* A filter which intercepts {@link IoHandler} events like Servlet
25	* filters. Filters can be used for these purposes:
26	* <ul>
27	* <li>Event logging,</li>
28	* <li>Performance measurement,</li>
29	* <li>Authorization,</li>
30	* <li>Overload control,</li>
31	* <li>Message transformation (e.g. encryption and decryption, ...),</li>
32	* <li>and many more.</li>
33	* </ul>
34	* <p>
35	* <strong>Please NEVER implement your filters to wrap
36	* {@link IoSession}s.</strong> Users can cache the reference to the
37	* session, which might malfunction if any filters are added or removed later.
38	*
39	* <h3>The Life Cycle</h3>
40	* {@link IoFilter}s are activated only when they are inside {@link IoFilterChain}.
41	* <p>
42	* When you add an {@link IoFilter} to an {@link IoFilterChain}:
43	* <ol>
44	* <li>{@link #init()} is invoked by {@link IoFilterChain} if the filter is
45	* added at the first time.</li>
46	* <li>{@link #onPreAdd(IoFilterChain, String, NextFilter)} is invoked to notify
47	* that the filter will be added to the chain.</li>
48	* <li>The filter is added to the chain, and all events and I/O requests
49	* pass through the filter from now.</li>
50	* <li>{@link #onPostAdd(IoFilterChain, String, NextFilter)} is invoked to notify
51	* that the filter is added to the chain.</li>
52	* <li>The filter is removed from the chain if {@link #onPostAdd(IoFilterChain, String, org.apache.mina.common.IoFilter.NextFilter)}
53	* threw an exception. {@link #destroy()} is also invoked if the filter
54	* is the last filter which was added to {@link IoFilterChain}s.</li>
55	* </ol>
56	* <p>
57	* When you remove an {@link IoFilter} from an {@link IoFilterChain}:
58	* <ol>
59	* <li>{@link #onPreRemove(IoFilterChain, String, NextFilter)} is invoked to
60	* notify that the filter will be removed from the chain.</li>
61	* <li>The filter is removed from the chain, and any events and I/O requests
62	* don't pass through the filter from now.</li>
63	* <li>{@link #onPostRemove(IoFilterChain, String, NextFilter)} is invoked to
64	* notify that the filter is removed from the chain.</li>
65	* <li>{@link #destroy()} is invoked if the removed filter was the last one.</li>
66	* </ol>
67	*
68	* @author The Apache Directory Project (dev@directory.apache.org)
69	* @version $Rev$, $Date$
70	*
71	* @see IoFilterAdapter
72	*/
73	public interface IoFilter
74	{
75	/**
76	* Invoked when this filter is added to a {@link IoFilterChain}
77	* at the first time, so you can initialize shared resources.
78	*/
79	void init() throws Exception;
80
81	/**
82	* Invoked when this filter is not used by any {@link IoFilterChain}
83	* anymore, so you can destroy shared resources.
84	*/
85	void destroy() throws Exception;
86
87	/**
88	* Invoked before this filter is added to the specified <tt>parent</tt>.
89	* Please note that this method can be invoked more than once if
90	* this filter is added to more than one parents. This method is not
91	* invoked before {@link #init()} is invoked.
92	*
93	* @param parent the parent who called this method
94	* @param name the name assigned to this filter
95	* @param nextFilter the {@link NextFilter} for this filter. You can reuse
96	* this object until this filter is removed from the chain.
97	*/
98	void onPreAdd( IoFilterChain parent, String name, NextFilter nextFilter ) throws Exception;
99
100	/**
101	* Invoked after this filter is added to the specified <tt>parent</tt>.
102	* Please note that this method can be invoked more than once if
103	* this filter is added to more than one parents. This method is not
104	* invoked before {@link #init()} is invoked.
105	*
106	* @param parent the parent who called this method
107	* @param name the name assigned to this filter
108	* @param nextFilter the {@link NextFilter} for this filter. You can reuse
109	* this object until this filter is removed from the chain.
110	*/
111	void onPostAdd( IoFilterChain parent, String name, NextFilter nextFilter ) throws Exception;
112
113	/**
114	* Invoked before this filter is removed from the specified <tt>parent</tt>.
115	* Please note that this method can be invoked more than once if
116	* this filter is removed from more than one parents.
117	* This method is always invoked before {@link #destroy()} is invoked.
118	*
119	* @param parent the parent who called this method
120	* @param name the name assigned to this filter
121	* @param nextFilter the {@link NextFilter} for this filter. You can reuse
122	* this object until this filter is removed from the chain.
123	*/
124	void onPreRemove( IoFilterChain parent, String name, NextFilter nextFilter ) throws Exception;
125
126	/**
127	* Invoked after 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 onPostRemove( IoFilterChain parent, String name, NextFilter nextFilter ) throws Exception;
138
139	/**
140	* Filters {@link IoHandler#sessionCreated(IoSession)} event.
141	*/
142	void sessionCreated( NextFilter nextFilter, IoSession session ) throws Exception;
143
144	/**
145	* Filters {@link IoHandler#sessionOpened(IoSession)} event.
146	*/
147	void sessionOpened( NextFilter nextFilter, IoSession session ) throws Exception;
148
149	/**
150	* Filters {@link IoHandler#sessionClosed(IoSession)} event.
151	*/
152	void sessionClosed( NextFilter nextFilter, IoSession session ) throws Exception;
153
154	/**
155	* Filters {@link IoHandler#sessionIdle(IoSession,IdleStatus)}
156	* event.
157	*/
158	void sessionIdle( NextFilter nextFilter, IoSession session,
159	IdleStatus status ) throws Exception;
160
161	/**
162	* Filters {@link IoHandler#exceptionCaught(IoSession,Throwable)}
163	* event.
164	*/
165	void exceptionCaught( NextFilter nextFilter,
166	IoSession session, Throwable cause ) throws Exception;
167
168	/**
169	* Filters {@link IoHandler#messageReceived(IoSession,Object)}
170	* event.
171	*/
172	void messageReceived( NextFilter nextFilter,
173	IoSession session, Object message ) throws Exception;
174
175	/**
176	* Filters {@link IoHandler#messageSent(IoSession,Object)}
177	* event.
178	*/
179	void messageSent( NextFilter nextFilter, IoSession session,
180	Object message ) throws Exception;
181
182	/**
183	* Filters {@link IoSession#close()} method invocation.
184	*/
185	void filterClose( NextFilter nextFilter, IoSession session, CloseFuture closeFuture ) throws Exception;
186
187	/**
188	* Filters {@link IoSession#write(Object)} method invocation.
189	*/
190	void filterWrite( NextFilter nextFilter, IoSession session, WriteRequest writeRequest ) throws Exception;
191
192	/**
193	* Represents the next {@link IoFilter} in {@link IoFilterChain}.
194	*/
195	public interface NextFilter
196	{
197	/**
198	* Forwards <tt>sessionCreated</tt> event to next filter.
199	*/
200	void sessionCreated( IoSession session );
201
202	/**
203	* Forwards <tt>sessionOpened</tt> event to next filter.
204	*/
205	void sessionOpened( IoSession session );
206
207	/**
208	* Forwards <tt>sessionClosed</tt> event to next filter.
209	*/
210	void sessionClosed( IoSession session );
211
212	/**
213	* Forwards <tt>sessionIdle</tt> event to next filter.
214	*/
215	void sessionIdle( IoSession session, IdleStatus status );
216
217	/**
218	* Forwards <tt>exceptionCaught</tt> event to next filter.
219	*/
220	void exceptionCaught( IoSession session, Throwable cause );
221
222	/**
223	* Forwards <tt>messageReceived</tt> event to next filter.
224	*/
225	void messageReceived( IoSession session, Object message );
226
227	/**
228	* Forwards <tt>messageSent</tt> event to next filter.
229	*/
230	void messageSent( IoSession session, Object message );
231
232	/**
233	* Forwards <tt>filterWrite</tt> event to next filter.
234	*/
235	void filterWrite( IoSession session, WriteRequest writeRequest );
236
237	/**
238	* Forwards <tt>filterClose</tt> event to next filter.
239	*/
240	void filterClose( IoSession session, CloseFuture closeFuture );
241	}
242
243	/**
244	* Represents write request fired by {@link IoSession#write(Object)}.
245	*/
246	public static class WriteRequest
247	{
248	private static final WriteFuture UNUSED_FUTURE = new WriteFuture();
249
250	private final Object message;
251	private final WriteFuture future;
252
253	/**
254	* Creates a new instance without {@link WriteFuture}. You'll get
255	* an instance of {@link WriteFuture} even if you called this constructor
256	* because {@link #getFuture()} will return a bogus future.
257	*/
258	public WriteRequest( Object message )
259	{
260	this( message, null );
261	}
262
263	/**
264	* Creates a new instance with {@link WriteFuture}.
265	*/
266	public WriteRequest( Object message, WriteFuture future )
267	{
268	if( message == null )
269	{
270	throw new NullPointerException( "message" );
271	}
272
273	if( future == null )
274	{
275	future = UNUSED_FUTURE;
276	}
277
278	this.message = message;
279	this.future = future;
280	}
281
282	/**
283	* Returns {@link WriteFuture} that is associated with this write request.
284	*/
285	public WriteFuture getFuture()
286	{
287	return future;
288	}
289
290	/**
291	* Returns a message object to be written.
292	*/
293	public Object getMessage()
294	{
295	return message;
296	}
297
298	public String toString()
299	{
300	return message.toString();
301	}
302	}
303	}