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 java.util.Iterator;
21  import java.util.Map;
22  
23  import javax.naming.Name;
24  import javax.naming.NamingEnumeration;
25  import javax.naming.NamingException;
26  import javax.naming.directory.Attributes;
27  import javax.naming.directory.ModificationItem;
28  import javax.naming.directory.SearchControls;
29  
30  import org.apache.ldap.common.filter.ExprNode;
31  import org.apache.ldap.server.configuration.InterceptorConfiguration;
32  import org.apache.ldap.server.jndi.ContextFactoryConfiguration;
33  import org.apache.ldap.server.partition.ContextPartition;
34  import org.apache.ldap.server.partition.ContextPartitionNexus;
35  
36  
37  /***
38   * Filters invocations on {@link ContextPartitionNexus}.  {@link Interceptor}
39   * filters most method calls performed on {@link ContextPartitionNexus} just
40   * like Servlet filters do.
41   * <p/>
42   * <h2>Interceptor Chaining</h2>
43   * 
44   * Interceptors should usually pass the control
45   * of current invocation to the next interceptor by calling an appropriate method
46   * on {@link NextInterceptor}.  The flow control is returned when the next 
47   * interceptor's filter method returns. You can therefore implement pre-, post-,
48   * around- invocation handler by how you place the statement.  Otherwise, you
49   * can transform the invocation into other(s).
50   * <p/>
51   * <h3>Pre-invocation Filtering</h3>
52   * <pre>
53   * public void delete( NextInterceptor nextInterceptor, Name name )
54   * {
55   *     System.out.println( "Starting invocation." );
56   *     nextInterceptor.delete( name );
57   * }
58   * </pre>
59   * <p/>
60   * <h3>Post-invocation Filtering</h3>
61   * <pre>
62   * public void delete( NextInterceptor nextInterceptor, Name name )
63   * {
64   *     nextInterceptor.delete( name );
65   *     System.out.println( "Invocation ended." );
66   * }
67   * </pre>
68   * <p/>
69   * <h3>Around-invocation Filtering</h3>
70   * <pre>
71   * public void delete( NextInterceptor nextInterceptor, Name name )
72   * {
73   *     long startTime = System.currentTimeMillis();
74   *     try
75   *     {
76   *         nextInterceptor.delete( name );
77   *     }
78   *     finally
79   *     {
80   *         long endTime = System.currentTimeMillis();
81   *         System.out.println( ( endTime - startTime ) + "ms elapsed." );
82   *     }
83   * }
84   * </pre>
85   * <p/>
86   * <h3>Transforming invocations</h3>
87   * <pre>
88   * public void delete( NextInterceptor nextInterceptor, Name name )
89   * {
90   *     // transform deletion into modification.
91   *     Attribute mark = new BasicAttribute( "entryDeleted", "true" );
92   *     nextInterceptor.modify( name, DirContext.REPLACE_ATTRIBUTE, mark );
93   * }
94   * </pre>
95   *
96   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
97   * @version $Rev: 226451 $, $Date: 2005-07-29 20:54:58 -0400 (Fri, 29 Jul 2005) $
98   * @see NextInterceptor
99   */
100 public interface Interceptor
101 {
102     /***
103      * Intializes this interceptor.  This is invoked by {@link InterceptorChain}
104      * when this intercepter is loaded into interceptor chain.
105      */
106     void init( ContextFactoryConfiguration factoryCfg, InterceptorConfiguration cfg ) throws NamingException;
107 
108 
109     /***
110      * Deinitializes this interceptor.  This is invoked by {@link InterceptorChain}
111      * when this intercepter is unloaded from interceptor chain.
112      */
113     void destroy();
114 
115     /***
116      * Filters {@link ContextPartitionNexus#getRootDSE()} call.
117      */
118     Attributes getRootDSE( NextInterceptor next ) throws NamingException; 
119     /***
120      * Filters {@link ContextPartitionNexus#getMatchedName(Name, boolean)} call.
121      */
122     Name getMatchedName( NextInterceptor next, Name name, boolean normalized ) throws NamingException;
123     /***
124      * Filters {@link ContextPartitionNexus#getSuffix(Name, boolean)} call.
125      */
126     Name getSuffix( NextInterceptor next, Name name, boolean normalized ) throws NamingException;
127     /***
128      * Filters {@link ContextPartitionNexus#listSuffixes(boolean)} call.
129      */
130     Iterator listSuffixes( NextInterceptor next, boolean normalized ) throws NamingException;
131     /***
132      * Filters {@link ContextPartition#delete(Name)} call.
133      */
134     void delete( NextInterceptor next, Name name ) throws NamingException;
135     /***
136      * Filters {@link ContextPartition#add(String, Name, Attributes)} call.
137      */
138     void add( NextInterceptor next, String userProvidedName, Name normalizedName, Attributes entry ) throws NamingException;
139     /***
140      * Filters {@link ContextPartition#modify(Name, int, Attributes)} call.
141      */
142     void modify( NextInterceptor next, Name name, int modOp, Attributes attributes ) throws NamingException;
143     /***
144      * Filters {@link ContextPartition#modify(Name, ModificationItem[])} call.
145      */
146     void modify( NextInterceptor next, Name name, ModificationItem [] items ) throws NamingException;
147     /***
148      * Filters {@link ContextPartition#list(Name)} call.
149      */
150     NamingEnumeration list( NextInterceptor next, Name baseName ) throws NamingException;
151     /***
152      * Filters {@link ContextPartition#search(Name, Map, ExprNode, SearchControls)} call.
153      */
154     NamingEnumeration search( NextInterceptor next, Name baseName, Map environment, ExprNode filter,
155                               SearchControls searchControls ) throws NamingException;
156     /***
157      * Filters {@link ContextPartition#lookup(Name)} call.
158      */
159     Attributes lookup( NextInterceptor next, Name name ) throws NamingException;
160     /***
161      * Filters {@link ContextPartition#lookup(Name, String[])} call.
162      */
163     Attributes lookup( NextInterceptor next, Name dn, String [] attrIds ) throws NamingException;
164     /***
165      * Filters {@link ContextPartition#lookup(Name, String[])} call.
166      */
167     boolean hasEntry( NextInterceptor next, Name name ) throws NamingException;
168     /***
169      * Filters {@link ContextPartition#isSuffix(Name)} call.
170      */
171     boolean isSuffix( NextInterceptor next, Name name ) throws NamingException;
172     /***
173      * Filters {@link ContextPartition#modifyRn(Name, String, boolean)} call.
174      */
175     void modifyRn( NextInterceptor next, Name name, String newRn, boolean deleteOldRn ) throws NamingException;
176     /***
177      * Filters {@link ContextPartition#move(Name, Name)} call.
178      */
179     void move( NextInterceptor next, Name oldName, Name newParentName ) throws NamingException;
180     /***
181      * Filters {@link ContextPartition#move(Name, Name, String, boolean)} call.
182      */
183     void move( NextInterceptor next, Name oldName, Name newParentName, String newRn,
184                boolean deleteOldRn ) throws NamingException;
185 }