View Javadoc

1   /*
2    *  Licensed to the Apache Software Foundation (ASF) under one
3    *  or more contributor license agreements.  See the NOTICE file
4    *  distributed with this work for additional information
5    *  regarding copyright ownership.  The ASF licenses this file
6    *  to you under the Apache License, Version 2.0 (the
7    *  "License"); you may not use this file except in compliance
8    *  with the License.  You may obtain a copy of the License at
9    *  
10   *    http://www.apache.org/licenses/LICENSE-2.0
11   *  
12   *  Unless required by applicable law or agreed to in writing,
13   *  software distributed under the License is distributed on an
14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   *  KIND, either express or implied.  See the License for the
16   *  specific language governing permissions and limitations
17   *  under the License. 
18   *  
19   */
20  package org.apache.directory.server.core.interceptor;
21  
22  
23  import org.apache.directory.server.core.DirectoryService;
24  import org.apache.directory.server.core.entry.ClonedServerEntry;
25  import org.apache.directory.server.core.filtering.EntryFilteringCursor;
26  import org.apache.directory.server.core.interceptor.context.AddContextPartitionOperationContext;
27  import org.apache.directory.server.core.interceptor.context.AddOperationContext;
28  import org.apache.directory.server.core.interceptor.context.BindOperationContext;
29  import org.apache.directory.server.core.interceptor.context.CompareOperationContext;
30  import org.apache.directory.server.core.interceptor.context.DeleteOperationContext;
31  import org.apache.directory.server.core.interceptor.context.EntryOperationContext;
32  import org.apache.directory.server.core.interceptor.context.GetMatchedNameOperationContext;
33  import org.apache.directory.server.core.interceptor.context.GetRootDSEOperationContext;
34  import org.apache.directory.server.core.interceptor.context.GetSuffixOperationContext;
35  import org.apache.directory.server.core.interceptor.context.ListOperationContext;
36  import org.apache.directory.server.core.interceptor.context.ListSuffixOperationContext;
37  import org.apache.directory.server.core.interceptor.context.LookupOperationContext;
38  import org.apache.directory.server.core.interceptor.context.ModifyOperationContext;
39  import org.apache.directory.server.core.interceptor.context.MoveAndRenameOperationContext;
40  import org.apache.directory.server.core.interceptor.context.MoveOperationContext;
41  import org.apache.directory.server.core.interceptor.context.RemoveContextPartitionOperationContext;
42  import org.apache.directory.server.core.interceptor.context.RenameOperationContext;
43  import org.apache.directory.server.core.interceptor.context.SearchOperationContext;
44  import org.apache.directory.server.core.interceptor.context.UnbindOperationContext;
45  import org.apache.directory.server.core.partition.Partition;
46  import org.apache.directory.server.core.partition.PartitionNexus;
47  import org.apache.directory.shared.ldap.name.LdapDN;
48  
49  import java.util.Iterator;
50  
51  
52  /**
53   * Filters invocations on {@link PartitionNexus}.  {@link Interceptor}
54   * filters most method calls performed on {@link PartitionNexus} just
55   * like Servlet filters do.
56   * <p/>
57   * <h2>Interceptor Chaining</h2>
58   * 
59   * Interceptors should usually pass the control
60   * of current invocation to the next interceptor by calling an appropriate method
61   * on {@link NextInterceptor}.  The flow control is returned when the next 
62   * interceptor's filter method returns. You can therefore implement pre-, post-,
63   * around- invocation handler by how you place the statement.  Otherwise, you
64   * can transform the invocation into other(s).
65   * <p/>
66   * <h3>Pre-invocation Filtering</h3>
67   * <pre>
68   * public void delete( NextInterceptor nextInterceptor, Name name )
69   * {
70   *     System.out.println( "Starting invocation." );
71   *     nextInterceptor.delete( name );
72   * }
73   * </pre>
74   * <p/>
75   * <h3>Post-invocation Filtering</h3>
76   * <pre>
77   * public void delete( NextInterceptor nextInterceptor, Name name )
78   * {
79   *     nextInterceptor.delete( name );
80   *     System.out.println( "Invocation ended." );
81   * }
82   * </pre>
83   * <p/>
84   * <h3>Around-invocation Filtering</h3>
85   * <pre>
86   * public void delete( NextInterceptor nextInterceptor, Name name )
87   * {
88   *     long startTime = System.currentTimeMillis();
89   *     try
90   *     {
91   *         nextInterceptor.delete( name );
92   *     }
93   *     finally
94   *     {
95   *         long endTime = System.currentTimeMillis();
96   *         System.out.println( ( endTime - startTime ) + "ms elapsed." );
97   *     }
98   * }
99   * </pre>
100  * <p/>
101  * <h3>Transforming invocations</h3>
102  * <pre>
103  * public void delete( NextInterceptor nextInterceptor, Name name )
104  * {
105  *     // transform deletion into modification.
106  *     Attribute mark = new AttributeImpl( "entryDeleted", "true" );
107  *     nextInterceptor.modify( name, DirContext.REPLACE_ATTRIBUTE, mark );
108  * }
109  * </pre>
110  *
111  * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
112  * @version $Rev: 659905 $, $Date: 2008-05-25 05:37:28 +0200 (So, 25 Mai 2008) $
113  * @see NextInterceptor
114  */
115 public interface Interceptor
116 {
117     /**
118      * Name that must be unique in an interceptor chain
119      * @return name of this interceptor, must be unique in an interceptor chain.
120      */
121     String getName();
122 
123     /**
124      * Intializes this interceptor.  This is invoked by {@link InterceptorChain}
125      * when this intercepter is loaded into interceptor chain.
126      * @throws Exception 
127      */
128     void init( DirectoryService directoryService ) throws Exception;
129 
130 
131     /**
132      * Deinitializes this interceptor.  This is invoked by {@link InterceptorChain}
133      * when this intercepter is unloaded from interceptor chain.
134      */
135     void destroy();
136 
137 
138     /**
139      * Filters {@link PartitionNexus#getRootDSE( GetRootDSEOperationContext )} call.
140      */
141     ClonedServerEntry getRootDSE( NextInterceptor next, GetRootDSEOperationContext  opContext ) throws Exception;
142 
143 
144     /**
145      * Filters {@link PartitionNexus#getMatchedName( GetMatchedNameOperationContext )} call.
146      */
147     LdapDN getMatchedName( NextInterceptor next, GetMatchedNameOperationContext opContext ) throws Exception;
148 
149 
150     /**
151      * Filters {@link PartitionNexus#getSuffix( GetSuffixOperationContext )} call.
152      */
153     LdapDN getSuffix ( NextInterceptor next, GetSuffixOperationContext opContext ) throws Exception;
154 
155 
156     /**
157      * Filters {@link PartitionNexus#listSuffixes( ListSuffixOperationContext )} call.
158      */
159     Iterator<String> listSuffixes( NextInterceptor next, ListSuffixOperationContext opContext ) throws Exception;
160 
161 
162     /**
163      * Filters {@link PartitionNexus#addContextPartition( AddContextPartitionOperationContext )} call.
164      */
165     void addContextPartition( NextInterceptor next, AddContextPartitionOperationContext opContext ) throws Exception;
166 
167 
168     /**
169      * Filters {@link PartitionNexus#removeContextPartition( RemoveContextPartitionOperationContext )} call.
170      */
171     void removeContextPartition( NextInterceptor next, RemoveContextPartitionOperationContext opContext ) throws Exception;
172 
173 
174     /**
175      * Filters {@link PartitionNexus#compare( CompareOperationContext )} call.
176      */
177     boolean compare( NextInterceptor next, CompareOperationContext opContext) throws Exception;
178 
179 
180     /**
181      * Filters {@link Partition#delete( DeleteOperationContext )} call.
182      */
183     void delete( NextInterceptor next, DeleteOperationContext opContext ) throws Exception;
184 
185 
186     /**
187      * Filters {@link Partition#add( AddOperationContext )} call.
188      */
189     void add( NextInterceptor next, AddOperationContext opContext ) throws Exception;
190 
191 
192     /**
193      * Filters {@link Partition#modify( ModifyOperationContext )} call.
194      */
195     void modify( NextInterceptor next, ModifyOperationContext opContext ) throws Exception;
196 
197 
198     /**
199      * Filters {@link Partition#list( ListOperationContext )} call.
200      */
201     EntryFilteringCursor list( NextInterceptor next, ListOperationContext opContext ) throws Exception;
202 
203 
204     /**
205      * Filters {@link Partition#search( SearchOperationContext )} call.
206      */
207     EntryFilteringCursor search( NextInterceptor next, SearchOperationContext opContext ) throws Exception;
208 
209 
210     /**
211      * Filters {@link Partition#lookup( LookupOperationContext )} call.
212      */
213     ClonedServerEntry lookup( NextInterceptor next, LookupOperationContext opContext ) throws Exception;
214 
215 
216     /**
217      * Filters {@link Partition#hasEntry( EntryOperationContext )} call.
218      */
219     boolean hasEntry( NextInterceptor next, EntryOperationContext opContext ) throws Exception;
220 
221 
222     /**
223      * Filters {@link Partition#rename( RenameOperationContext )} call.
224      */
225     void rename( NextInterceptor next, RenameOperationContext opContext ) throws Exception;
226 
227 
228     /**
229      * Filters {@link Partition#move( MoveOperationContext )} call.
230      */
231     void move( NextInterceptor next, MoveOperationContext opContext ) throws Exception;
232 
233 
234     /**
235      * Filters {@link Partition#moveAndRename( MoveAndRenameOperationContext) } call.
236      */
237     void moveAndRename( NextInterceptor next, MoveAndRenameOperationContext opContext )
238         throws Exception;
239 
240     /**
241      * Filters {@link Partition#bind( BindOperationContext )} call.
242      */
243     void bind( NextInterceptor next, BindOperationContext opContext )
244         throws Exception;
245 
246     /**
247      * Filters {@link Partition#unbind( UnbindOperationContext )} call.
248      */
249     void unbind( NextInterceptor next, UnbindOperationContext opContext ) throws Exception;
250 }