001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 * 
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 * 
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 * 
019 */
020package org.apache.directory.server.core.api.interceptor.context;
021
022
023import java.util.List;
024
025import org.apache.directory.api.ldap.model.entry.Entry;
026import org.apache.directory.api.ldap.model.exception.LdapException;
027import org.apache.directory.api.ldap.model.message.Control;
028import org.apache.directory.api.ldap.model.name.Dn;
029import org.apache.directory.server.core.api.CoreSession;
030import org.apache.directory.server.core.api.LdapPrincipal;
031import org.apache.directory.server.core.api.entry.ClonedServerEntry;
032import org.apache.directory.server.core.api.partition.Partition;
033import org.apache.directory.server.core.api.partition.PartitionTxn;
034
035
036/**
037 * This interface represent the context passed as an argument to each interceptor.
038 * It will contain data used by all the operations.
039 *
040 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
041 */
042public interface OperationContext
043{
044    /**
045     * @return The number of the current interceptor in the list
046     */
047    int getCurrentInterceptor();
048
049
050    /**
051     * Sets the current interceptor number to a new value.
052     * 
053     * @param currentInterceptor The new current interceptor value
054     */
055    void setCurrentInterceptor( int currentInterceptor );
056
057
058    /**
059     * Gets the effective principal for this operation which may not be the
060     * same as the authenticated principal when the session for this context
061     * has an explicit authorization id, or this operation was applied with
062     * the proxy authorization control.
063     * 
064     * @see CoreSession#getAuthenticatedPrincipal()
065     * @see CoreSession#getEffectivePrincipal()
066     * @return the effective principal for this operation
067     */
068    LdapPrincipal getEffectivePrincipal();
069
070
071    /**
072     * @return The associated Dn
073     */
074    Dn getDn();
075
076
077    /**
078     * Set the context Dn
079     *
080     * @param dn The Dn to set
081     */
082    void setDn( Dn dn );
083
084
085    /**
086     * Gets the server entry associated with the target Dn of this
087     * OperationContext.  The entry associated with the Dn may be altered
088     * during the course of processing an LDAP operation through the
089     * InterceptorChain.  This place holder is put here to prevent the need
090     * for repetitive lookups of the target entry.  Furthermore the returned
091     * entry may be altered by any Interceptor in the chain and this is why a
092     * ClonedServerEntry is returned instead of a Entry.  A
093     * ClonedServerEntry has an immutable reference to the original state of
094     * the target entry.  The original state can be accessed via a call to
095     * {@link ClonedServerEntry#getOriginalEntry()}.  The return value may be
096     * null in which case any lookup performed to access it may set it to
097     * prevent the need for subsequent lookups.
098     * 
099     * 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}