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 }