View Javadoc

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;
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 }