KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > ldap > server > interceptor > Interceptor


1 /*
2  * Copyright 2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  *
16  */
17 package org.apache.ldap.server.interceptor;
18
19
20 import org.apache.ldap.server.BackingStore;
21 import org.apache.ldap.server.invocation.Invocation;
22
23 import javax.naming.NamingException JavaDoc;
24
25
26 /**
27  * Filters any directory operations. You can filter any {@link Invocation}
28  * performed on {@link BackingStore}s just like Servlet filters do.
29  * <p/>
30  * <h2>Interceptor Chaining</h2> Interceptors should usually pass the control
31  * of current invocation to the next interceptor by calling
32  * {@link NextInterceptor#process(Invocation)}. The flow control is returned
33  * when the next interceptor's {@link Interceptor#process(NextInterceptor, Invocation)}
34  * returns. You can therefore implement pre-, post-, around- invocation handler
35  * by how you place the statement.
36  * <p/>
37  * <h3>Pre-invocation Filtering</h3>
38  * <pre>
39  * public void process( NextInterceptor nextInterceptor, Invocation invocation )
40  * {
41  * System.out.println( "Starting invocation." );
42  * nextInterceptor.process( invocation );
43  * }
44  * </pre>
45  * <p/>
46  * <h3>Post-invocation Filtering</h3>
47  * <pre>
48  * public void process( NextInterceptor nextInterceptor, Invocation invocation )
49  * {
50  * nextInterceptor.process( invocation );
51  * System.out.println( "Invocation ended." );
52  * }
53  * </pre>
54  * <p/>
55  * <h3>Around-invocation Filtering</h3>
56  * <pre>
57  * public void process( NextInterceptor nextInterceptor, Invocation invocation )
58  * {
59  * long startTime = System.currentTimeMillis();
60  * try
61  * {
62  * nextInterceptor.process( invocation );
63  * }
64  * finally
65  * {
66  * long endTime = System.currentTimeMillis();
67  * System.out.println( ( endTime - startTime ) + "ms elapsed." );
68  * }
69  * }
70  * </pre>
71  * <p/>
72  * <h2>Interceptor Naming Convention</h2>
73  * <p/>
74  * When you create an implementation of Interceptor, you have to follow the
75  * basic class naming convention to avoid others' confusion:
76  * <ul>
77  * <li>Class name must be an agent noun or end with <code>Interceptor</code> or
78  * <code>Service</code>.</li>
79  * </ul>
80  * Plus, placing your interceptor implementations into relavent packages like
81  * <code>interceptor</code> or ones that reflect its purpose would be a good
82  * practice.
83  * <p/>
84  * <h2>Overriding Default Interceptor Settings</h2>
85  * <p/>
86  * See {@link org.apache.ldap.server.jndi.EnvKeys#INTERCEPTORS} and
87  * {@link InterceptorChain#newDefaultChain()}.
88  *
89  * @author <a HREF="mailto:dev@directory.apache.org">Apache Directory Project</a>
90  * @version $Rev: 169198 $, $Date: 2005-05-08 20:05:59 -0400 (Sun, 08 May 2005) $
91  * @see NextInterceptor
92  */
93 public interface Interceptor
94 {
95     /**
96      * Intializes this interceptor. This is invoked by directory
97      * service provider when this intercepter is loaded into interceptor chain.
98      *
99      * @param context the configuration properties for this interceptor
100      * @throws NamingException if failed to initialize this interceptor
101      */
102     void init( InterceptorContext context ) throws NamingException JavaDoc;
103
104
105     /**
106      * Deinitializes this interceptor. This is invoked by directory
107      * service provider when this intercepter is unloaded from interceptor chain.
108      */
109     void destroy();
110
111
112     /**
113      * Filters a particular invocation. You can pass control to
114      * <code>nextInterceptor</code> by calling {@link NextInterceptor#process(
115      * org.apache.ldap.server.invocation.Invocation)}
116      *
117      * @param nextInterceptor the next interceptor in the interceptor chain
118      * @param invocation the invocation to process
119      * @throws NamingException on failures while handling the invocation
120      */
121     void process( NextInterceptor nextInterceptor, Invocation invocation ) throws NamingException JavaDoc;
122 }
123
Popular Tags