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 */
020 package org.apache.directory.server.core.interceptor.context;
021
022
023 import java.util.Collection;
024 import java.util.List;
025
026 import org.apache.directory.server.core.CoreSession;
027 import org.apache.directory.server.core.LdapPrincipal;
028 import org.apache.directory.server.core.entry.ClonedServerEntry;
029 import org.apache.directory.server.core.interceptor.Interceptor;
030 import org.apache.directory.shared.ldap.entry.Modification;
031 import org.apache.directory.shared.ldap.entry.ServerEntry;
032 import org.apache.directory.shared.ldap.message.control.Control;
033 import org.apache.directory.shared.ldap.name.DN;
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 * @version $Rev$, $Date$
042 */
043 public interface OperationContext
044 {
045 /**
046 * Checks to see if this operation is the first operation in a chain of
047 * operations performed on the DirectoryService. The first operation in
048 * a sequence of operations, is not a byproduct of another operation
049 * unlike operations following in the sequence. The other operations
050 * following the first, occur as a side effect to complete this first
051 * operation.
052 *
053 * @return true if the operation is the first, false otherwise
054 */
055 boolean isFirstOperation();
056
057
058 /**
059 * Gets the first, direct operation issued against the DirectoryService.
060 *
061 * @return the first, direct operation issued
062 */
063 OperationContext getFirstOperation();
064
065
066 /**
067 * Gets the previous, operation issued on the DirectoryService.
068 *
069 * @return the previous, operation issued
070 */
071 OperationContext getPreviousOperation();
072
073
074 /**
075 * Gets the next, indirect operation issued on the DirectoryService.
076 *
077 * @return the next, indirect operation issued
078 */
079 OperationContext getNextOperation();
080
081
082 /**
083 * Gets the last, operation issued on the DirectoryService.
084 *
085 * @return the last, operation issued
086 */
087 OperationContext getLastOperation();
088
089
090 /**
091 * Gets the effective principal for this operation which may not be the
092 * same as the authenticated principal when the session for this context
093 * has an explicit authorization id, or this operation was applied with
094 * the proxy authorization control.
095 *
096 * @see CoreSession#getAuthenticatedPrincipal()
097 * @see CoreSession#getEffectivePrincipal()
098 * @return the effective principal for this operation
099 */
100 LdapPrincipal getEffectivePrincipal();
101
102
103 /**
104 * @return The associated DN
105 */
106 DN getDn();
107
108
109 /**
110 * Set the context DN
111 *
112 * @param dn The DN to set
113 */
114 void setDn( DN dn );
115
116
117 /**
118 * Gets the server entry associated with the target DN of this
119 * OperationContext. The entry associated with the DN may be altered
120 * during the course of processing an LDAP operation through the
121 * InterceptorChain. This place holder is put here to prevent the need
122 * for repetitive lookups of the target entry. Furthermore the returned
123 * entry may be altered by any Interceptor in the chain and this is why a
124 * ClonedServerEntry is returned instead of a ServerEntry. A
125 * ClonedServerEntry has an immutable reference to the original state of
126 * the target entry. The original state can be accessed via a call to
127 * {@link ClonedServerEntry#getOriginalEntry()}. The return value may be
128 * null in which case any lookup performed to access it may set it to
129 * prevent the need for subsequent lookups.
130 *
131 * Also note that during the course of handling some operations such as
132 * those that rename, move or rename and move the entry, may alter the DN
133 * of this entry. Interceptor implementors should not presume the DN or
134 * the values contained in this entry are currently what is present in the
135 * DIT. The original entry contained in the ClonedServerEntry shoudl be
136 * used as the definitive source of information about the state of the
137 * entry in the DIT before returning from the Partition subsystem.
138 *
139 * @return target entry associated with the DN of this OperationContext
140 */
141 ClonedServerEntry getEntry();
142
143
144 /**
145 * Sets the server entry associated with the target DN of this
146 * OperationContext.
147 *
148 * @param entry the entry whose DN is associated with this OperationContext.
149 */
150 void setEntry( ClonedServerEntry entry );
151
152
153 /**
154 * Adds a response control to this operation.
155 *
156 * @param responseControl the response control to add to this operation
157 */
158 void addResponseControl( Control responseControl );
159
160
161 /**
162 * Checks to see if a response control is present on this operation.
163 *
164 * @param numericOid the numeric OID of the control also known as it's type OID
165 * @return true if the control is associated with this operation, false otherwise
166 */
167 boolean hasResponseControl( String numericOid );
168
169
170 /**
171 * Gets a response control if present for this request.
172 *
173 * @param numericOid the numeric OID of the control also known as it's type OID
174 * @return the control if present
175 */
176 Control getResponseControl( String numericOid );
177
178
179 /**
180 * Gets all the response controls producted during this operation.
181 *
182 * @return an array over all the response controls
183 */
184 Control[] getResponseControls();
185
186
187 /**
188 * Checks if any response controls have been generated for this operation.
189 *
190 * @return true if any response controls have been generated, false otherwise
191 */
192 boolean hasResponseControls();
193
194
195 /**
196 * Checks the number of response controls have been generated for this operation.
197 *
198 * @return the number of response controls that have been generated
199 */
200 int getResponseControlCount();
201
202
203 /**
204 * Adds a request control to this operation.
205 *
206 * @param requestControl the request control to add to this operation
207 */
208 void addRequestControl( Control requestControl );
209
210
211 /**
212 * Checks to see if a request control is present on this request.
213 *
214 * @param numericOid the numeric OID of the control also known as it's type OID
215 * @return true if the control is associated with this operation, false otherwise
216 */
217 boolean hasRequestControl( String numericOid );
218
219
220 /**
221 * Checks if any request controls exists for this operation.
222 *
223 * @return true if any request controls exist, false otherwise
224 */
225 boolean hasRequestControls();
226
227
228 /**
229 * Gets a request control if present for this request.
230 *
231 * @param numericOid the numeric OID of the control also known as it's type OID
232 * @return the control if present
233 */
234 Control getRequestControl( String numericOid );
235
236
237 /**
238 * Adds many request controls to this operation.
239 *
240 * @param requestControls the request controls to add to this operation
241 */
242 void addRequestControls( Control[] requestControls );
243
244
245 /**
246 * @return the operation's name
247 */
248 String getName();
249
250
251 /**
252 * Checks to see if an Interceptor is bypassed for this operation.
253 *
254 * @param interceptorName the interceptorName of the Interceptor to check for bypass
255 * @return true if the Interceptor should be bypassed, false otherwise
256 */
257 boolean isBypassed( String interceptorName );
258
259
260 /**
261 * Checks to see if any Interceptors are bypassed by this Invocation.
262 *
263 * @return true if at least one bypass exists
264 */
265 boolean hasBypass();
266
267
268 /**
269 * Gets the set of bypassed Interceptors.
270 *
271 * @return the set of bypassed Interceptors
272 */
273 Collection<String> getByPassed();
274
275
276 /**
277 * Sets the set of bypassed Interceptors.
278 *
279 * @param byPassed the set of bypassed Interceptors
280 */
281 void setByPassed( Collection<String> byPassed );
282
283
284 /**
285 * Gets the session associated with this operation.
286 *
287 * @return the session associated with this operation
288 */
289 CoreSession getSession();
290
291
292 // -----------------------------------------------------------------------
293 // Utility Factory Methods to Create New OperationContexts
294 // -----------------------------------------------------------------------
295
296
297 LookupOperationContext newLookupContext( DN dn );
298
299
300 ClonedServerEntry lookup( DN dn, Collection<String> byPass ) throws Exception;
301
302
303 ClonedServerEntry lookup( LookupOperationContext lookupContext ) throws Exception;
304
305
306 void modify( DN dn, List<Modification> mods, Collection<String> byPass ) throws Exception;
307
308
309 void add( ServerEntry entry, Collection<String> byPass ) throws Exception;
310
311
312 void delete( DN dn, Collection<String> byPass ) throws Exception;
313
314
315 /**
316 * Checks to see if an entry exists.
317 *
318 * @param dn the distinguished name of the entry to check
319 * @param byPass collection of {@link Interceptor}'s to bypass for this check
320 * @return true if the entry exists, false if it does not
321 * @throws Exception on failure to perform this operation
322 */
323 boolean hasEntry( DN dn, Collection<String> byPass ) throws Exception;
324
325
326 /**
327 * Set the throwReferral flag to true
328 */
329 void throwReferral();
330
331
332 /**
333 * @return <code>true</code> if the referrals are thrown
334 */
335 boolean isReferralThrown();
336
337
338 /**
339 * Set the throwReferral flag to false
340 */
341 void ignoreReferral();
342
343
344 /**
345 * @return <code>true</code> if the referrals are ignored
346 */
347 boolean isReferralIgnored();
348 }