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.ContextPartitionConfiguration;
32  import org.apache.ldap.server.configuration.InterceptorConfiguration;
33  import org.apache.ldap.server.jndi.ContextFactoryConfiguration;
34  import org.apache.ldap.server.partition.ContextPartition;
35  import org.apache.ldap.server.partition.ContextPartitionNexus;
36  
37  
38  /***
39   * Filters invocations on {@link ContextPartitionNexus}.  {@link Interceptor}
40   * filters most method calls performed on {@link ContextPartitionNexus} 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: 264732 $, $Date: 2005-08-30 04:04:51 -0400 (Tue, 30 Aug 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( ContextFactoryConfiguration factoryCfg, InterceptorConfiguration cfg ) throws NamingException;
108 
109 
110     /***
111      * Deinitializes this interceptor.  This is invoked by {@link InterceptorChain}
112      * when this intercepter is unloaded from interceptor chain.
113      */
114     void destroy();
115 
116     /***
117      * Filters {@link ContextPartitionNexus#getRootDSE()} call.
118      */
119     Attributes getRootDSE( NextInterceptor next ) throws NamingException; 
120     /***
121      * Filters {@link ContextPartitionNexus#getMatchedName(Name, boolean)} call.
122      */
123     Name getMatchedName( NextInterceptor next, Name name, boolean normalized ) throws NamingException;
124     /***
125      * Filters {@link ContextPartitionNexus#getSuffix(Name, boolean)} call.
126      */
127     Name getSuffix( NextInterceptor next, Name name, boolean normalized ) throws NamingException;
128     /***
129      * Filters {@link ContextPartitionNexus#listSuffixes(boolean)} call.
130      */
131     Iterator listSuffixes( NextInterceptor next, boolean normalized ) throws NamingException;
132     /***
133      * Filters {@link ContextPartitionNexus#addContextPartition(ContextPartitionConfiguration)} call.
134      */
135     void addContextPartition( NextInterceptor next, ContextPartitionConfiguration cfg ) throws NamingException;
136     /***
137      * Filters {@link ContextPartitionNexus#removeContextPartition(Name)} call.
138      */
139     void removeContextPartition( NextInterceptor next, Name suffix ) throws NamingException;
140     /***
141      * Filters {@link ContextPartition#delete(Name)} call.
142      */
143     void delete( NextInterceptor next, Name name ) throws NamingException;
144     /***
145      * Filters {@link ContextPartition#add(String, Name, Attributes)} call.
146      */
147     void add( NextInterceptor next, String userProvidedName, Name normalizedName, Attributes entry ) throws NamingException;
148     /***
149      * Filters {@link ContextPartition#modify(Name, int, Attributes)} call.
150      */
151     void modify( NextInterceptor next, Name name, int modOp, Attributes attributes ) throws NamingException;
152     /***
153      * Filters {@link ContextPartition#modify(Name, ModificationItem[])} call.
154      */
155     void modify( NextInterceptor next, Name name, ModificationItem [] items ) throws NamingException;
156     /***
157      * Filters {@link ContextPartition#list(Name)} call.
158      */
159     NamingEnumeration list( NextInterceptor next, Name baseName ) throws NamingException;
160     /***
161      * Filters {@link ContextPartition#search(Name, Map, ExprNode, SearchControls)} call.
162      */
163     NamingEnumeration search( NextInterceptor next, Name baseName, Map environment, ExprNode filter,
164                               SearchControls searchControls ) throws NamingException;
165     /***
166      * Filters {@link ContextPartition#lookup(Name)} call.
167      */
168     Attributes lookup( NextInterceptor next, Name name ) throws NamingException;
169     /***
170      * Filters {@link ContextPartition#lookup(Name, String[])} call.
171      */
172     Attributes lookup( NextInterceptor next, Name dn, String [] attrIds ) throws NamingException;
173     /***
174      * Filters {@link ContextPartition#lookup(Name, String[])} call.
175      */
176     boolean hasEntry( NextInterceptor next, Name name ) throws NamingException;
177     /***
178      * Filters {@link ContextPartition#isSuffix(Name)} call.
179      */
180     boolean isSuffix( NextInterceptor next, Name name ) throws NamingException;
181     /***
182      * Filters {@link ContextPartition#modifyRn(Name, String, boolean)} call.
183      */
184     void modifyRn( NextInterceptor next, Name name, String newRn, boolean deleteOldRn ) throws NamingException;
185     /***
186      * Filters {@link ContextPartition#move(Name, Name)} call.
187      */
188     void move( NextInterceptor next, Name oldName, Name newParentName ) throws NamingException;
189     /***
190      * Filters {@link ContextPartition#move(Name, Name, String, boolean)} call.
191      */
192     void move( NextInterceptor next, Name oldName, Name newParentName, String newRn,
193                boolean deleteOldRn ) throws NamingException;
194 }