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