1
2
3
4
5
6
7
8
9
10
11
12
13
14
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;
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: 159316 $, $Date: 2005-03-28 17:20:10 -0500 (Mon, 28 Mar 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;
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;
122 }