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