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.context;
21  
22  
23  import java.util.Collection;
24  import java.util.List;
25  
26  import javax.naming.ldap.Control;
27  
28  import org.apache.directory.server.core.CoreSession;
29  import org.apache.directory.server.core.authn.LdapPrincipal;
30  import org.apache.directory.server.core.entry.ClonedServerEntry;
31  import org.apache.directory.server.core.entry.ServerEntry;
32  import org.apache.directory.server.core.interceptor.Interceptor;
33  import org.apache.directory.shared.ldap.entry.Modification;
34  import org.apache.directory.shared.ldap.name.LdapDN;
35  
36  
37  /**
38   * This interface represent the context passed as an argument to each interceptor.
39   * It will contain data used by all the operations.
40   *
41   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
42   * @version $Rev$, $Date$
43   */
44  public interface OperationContext
45  {
46      /**
47       * Checks to see if this operation is the first operation in a chain of 
48       * operations performed on the DirectoryService.  The first operation in  
49       * a sequence of operations, is not a byproduct of another operation 
50       * unlike operations following in the sequence.  The other operations 
51       * following the first, occur as a side effect to complete this first 
52       * operation.
53       * 
54       * @return true if the operation is the first, false otherwise
55       */
56      boolean isFirstOperation();
57      
58      
59      /**
60       * Gets the first, direct operation issued against the DirectoryService.
61       *
62       * @return the first, direct operation issued 
63       */
64      OperationContext getFirstOperation();
65      
66      
67      /**
68       * Gets the previous, operation issued on the DirectoryService.
69       *
70       * @return the previous, operation issued
71       */
72      OperationContext getPreviousOperation();
73      
74      
75      /**
76       * Gets the next, indirect operation issued on the DirectoryService.
77       *
78       * @return the next, indirect operation issued 
79       */
80      OperationContext getNextOperation();
81      
82      
83      /**
84       * Gets the last, operation issued on the DirectoryService.
85       *
86       * @return the last, operation issued
87       */
88      OperationContext getLastOperation();
89  
90  
91      /**
92       * Gets the effective principal for this operation which may not be the 
93       * same as the authenticated principal when the session for this context
94       * has an explicit authorization id, or this operation was applied with 
95       * the proxy authorization control.
96       * 
97       * @see CoreSession#getAuthenticatedPrincipal()
98       * @see CoreSession#getEffectivePrincipal()
99       * @return the effective principal for this operation
100      */
101     LdapPrincipal getEffectivePrincipal();
102 
103 
104     /**
105      * @return The associated DN
106      */
107     LdapDN getDn();
108     
109     
110     /**
111      * Set the context DN
112      *
113      * @param dn The DN to set
114      */
115     void setDn( LdapDN dn );
116 
117     
118     /**
119      * Gets the server entry associated with the target DN of this 
120      * OperationContext.  The entry associated with the DN may be altered 
121      * during the course of processing an LDAP operation through the 
122      * InterceptorChain.  This place holder is put here to prevent the need
123      * for repetitive lookups of the target entry.  Furthermore the returned
124      * entry may be altered by any Interceptor in the chain and this is why a
125      * ClonedServerEntry is returned instead of a ServerEntry.  A 
126      * ClonedServerEntry has an immutable reference to the original state of
127      * the target entry.  The original state can be accessed via a call to
128      * {@link ClonedServerEntry#getOriginalEntry()}.  The return value may be 
129      * null in which case any lookup performed to access it may set it to 
130      * prevent the need for subsequent lookups.
131      * 
132      * Also note that during the course of handling some operations such as 
133      * those that rename, move or rename and move the entry, may alter the DN 
134      * of this entry.  Interceptor implementors should not presume the DN or 
135      * the values contained in this entry are currently what is present in the 
136      * DIT.  The original entry contained in the ClonedServerEntry shoudl be 
137      * used as the definitive source of information about the state of the 
138      * entry in the DIT before returning from the Partition subsystem.
139      * 
140      * @return target entry associated with the DN of this OperationContext
141      */
142     ClonedServerEntry getEntry();
143     
144     
145     /**
146      * Sets the server entry associated with the target DN of this 
147      * OperationContext.
148      *
149      * @param entry the entry whose DN is associated with this OperationContext.
150      */
151     void setEntry( ClonedServerEntry entry );
152     
153     
154     /**
155      * Adds a response control to this operation.
156      *
157      * @param responseControl the response control to add to this operation
158      */
159     void addResponseControl( Control responseControl );
160     
161     
162     /** 
163      * Checks to see if a response control is present on this operation.
164      *
165      * @param numericOid the numeric OID of the control also known as it's type OID
166      * @return true if the control is associated with this operation, false otherwise
167      */
168     boolean hasResponseControl( String numericOid );
169     
170     
171     /**
172      * Gets a response control if present for this request.
173      * 
174      * @param numericOid the numeric OID of the control also known as it's type OID
175      * @return the control if present
176      */
177     Control getResponseControl( String numericOid );
178     
179     
180     /**
181      * Gets all the response controls producted during this operation.
182      *
183      * @return an array over all the response controls 
184      */
185     Control[] getResponseControls();
186     
187     
188     /**
189      * Checks if any response controls have been generated for this operation.
190      *
191      * @return true if any response controls have been generated, false otherwise
192      */
193     boolean hasResponseControls();
194     
195     
196     /**
197      * Checks the number of response controls have been generated for this operation.
198      *
199      * @return the number of response controls that have been generated
200      */
201     int getResponseControlCount();
202     
203     
204     /**
205      * Adds a request control to this operation.
206      *
207      * @param requestControl the request control to add to this operation
208      */
209     void addRequestControl( Control requestControl );
210     
211     
212     /** 
213      * Checks to see if a request control is present on this request.
214      *
215      * @param numericOid the numeric OID of the control also known as it's type OID
216      * @return true if the control is associated with this operation, false otherwise
217      */
218     boolean hasRequestControl( String numericOid );
219     
220     
221     /**
222      * Checks if any request controls exists for this operation.
223      *
224      * @return true if any request controls exist, false otherwise
225      */
226     boolean hasRequestControls();
227     
228     
229     /**
230      * Gets a request control if present for this request.
231      * 
232      * @param numericOid the numeric OID of the control also known as it's type OID
233      * @return the control if present
234      */
235     Control getRequestControl( String numericOid );
236 
237 
238     /**
239      * Adds many request controls to this operation.
240      *
241      * @param requestControls the request controls to add to this operation
242      */
243     void addRequestControls( Control[] requestControls );
244     
245     
246     /**
247      * @return the operation's name
248      */
249     String getName();
250     
251     
252     /**
253      * Checks to see if an Interceptor is bypassed for this operation.
254      *
255      * @param interceptorName the interceptorName of the Interceptor to check for bypass
256      * @return true if the Interceptor should be bypassed, false otherwise
257      */
258     boolean isBypassed( String interceptorName );
259 
260 
261     /**
262      * Checks to see if any Interceptors are bypassed by this Invocation.
263      *
264      * @return true if at least one bypass exists
265      */
266     boolean hasBypass();
267     
268     
269     /**
270      * Gets the set of bypassed Interceptors.
271      *
272      * @return the set of bypassed Interceptors
273      */
274     Collection<String> getByPassed();
275     
276     
277     /**
278      * Sets the set of bypassed Interceptors.
279      * 
280      * @param byPassed the set of bypassed Interceptors
281      */
282     void setByPassed( Collection<String> byPassed );
283     
284     
285     /**
286      * Gets the session associated with this operation.
287      *
288      * @return the session associated with this operation
289      */
290     CoreSession getSession();
291     
292     
293     // -----------------------------------------------------------------------
294     // Utility Factory Methods to Create New OperationContexts
295     // -----------------------------------------------------------------------
296     
297     
298     LookupOperationContext newLookupContext( LdapDN dn );
299 
300     
301     ClonedServerEntry lookup( LdapDN dn, Collection<String> byPass ) throws Exception;
302     
303     
304     ClonedServerEntry lookup( LookupOperationContext lookupContext ) throws Exception;
305     
306     
307     void modify( LdapDN dn, List<Modification> mods, Collection<String> byPass ) throws Exception;
308     
309     
310     void add( ServerEntry entry, Collection<String> byPass ) throws Exception;
311     
312     
313     void delete( LdapDN dn, Collection<String> byPass ) throws Exception;
314 
315 
316     /**
317      * Checks to see if an entry exists.
318      *
319      * @param dn the distinguished name of the entry to check
320      * @param byPass collection of {@link Interceptor}'s to bypass for this check
321      * @return true if the entry exists, false if it does not
322      * @throws Exception on failure to perform this operation
323      */
324     boolean hasEntry( LdapDN dn, Collection<String> byPass ) throws Exception;
325     
326     
327 //    AddOperationContext newAddContext( ServerEntry entry );
328     
329     
330 //    void add( AddOperationContext addContext ) throws Exception;
331 }