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;
21
22
23 import java.net.SocketAddress;
24 import java.util.List;
25 import java.util.Set;
26
27 import javax.naming.ldap.Control;
28
29 import org.apache.directory.server.constants.ServerDNConstants;
30 import org.apache.directory.server.core.authn.LdapPrincipal;
31 import org.apache.directory.server.core.entry.ClonedServerEntry;
32 import org.apache.directory.server.core.entry.ServerEntry;
33 import org.apache.directory.server.core.filtering.EntryFilteringCursor;
34 import org.apache.directory.server.core.interceptor.context.OperationContext;
35 import org.apache.directory.shared.ldap.message.SearchRequest;
36 import org.apache.directory.shared.ldap.constants.AuthenticationLevel;
37 import org.apache.directory.shared.ldap.entry.Modification;
38 import org.apache.directory.shared.ldap.filter.ExprNode;
39 import org.apache.directory.shared.ldap.filter.SearchScope;
40 import org.apache.directory.shared.ldap.message.AddRequest;
41 import org.apache.directory.shared.ldap.message.AliasDerefMode;
42 import org.apache.directory.shared.ldap.message.CompareRequest;
43 import org.apache.directory.shared.ldap.message.DeleteRequest;
44 import org.apache.directory.shared.ldap.message.ModifyDnRequest;
45 import org.apache.directory.shared.ldap.message.ModifyRequest;
46 import org.apache.directory.shared.ldap.message.UnbindRequest;
47 import org.apache.directory.shared.ldap.name.LdapDN;
48 import org.apache.directory.shared.ldap.name.Rdn;
49 import org.apache.directory.shared.ldap.schema.AttributeTypeOptions;
50
51
52 /**
53 * An interface representing a session with the core DirectoryService. These
54 * sessions may either be real representing LDAP sessions associated with an
55 * actual LDAP network client, or may be virtual in which case there is no
56 * real LDAP client associated with the session. This interface is used by
57 * the DirectoryService core to track session specific parameters used to make
58 * various decisions during the course of operation handling.
59 *
60 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
61 * @version $Rev$, $Date$
62 */
63 public interface CoreSession
64 {
65 /**
66 * Gets the DirectoryService this session is bound to.
67 *
68 * @return the DirectoryService associated with this session
69 */
70 DirectoryService getDirectoryService();
71
72
73 /**
74 * Gets the LDAP principal used to authenticate. This is the identity
75 * used to establish this session on authentication.
76 *
77 * @return the LdapPrincipal used to authenticate.
78 */
79 LdapPrincipal getAuthenticatedPrincipal();
80
81
82 /**
83 * Gets the LDAP principal used for the effective identity associated with
84 * this session which may not be the same as the authenticated principal.
85 * This principal is often the same as the authenticated principal.
86 * Sometimes however, a user authenticating as one principal, may request
87 * to have all operations performed in the session as if they were another
88 * principal. The SASL mechanism allows setting an authorized principal
89 * which is in effect for the duration of the session. In this case all
90 * operations are performed as if they are being performed by this
91 * principal. This method will then return the authorized principal which
92 * will be different from the authenticated principal.
93 *
94 * Implementations of this interface may have a means to set the
95 * authorized principal which may or may not be the same as the
96 * authenticated principal. Implementations should default to return the
97 * authenticated principal when an authorized principal is not provided.
98 *
99 * @return the LdapPrincipal to use as the effective principal
100 */
101 LdapPrincipal getEffectivePrincipal();
102
103
104 /**
105 * Gets whether or not confidentiality is enabled for this session.
106 *
107 * @return true if confidentiality is enabled, false otherwise
108 */
109 boolean isConfidential();
110
111
112 /**
113 * Gets whether or not this user is anonymous.
114 *
115 * @return true if the identity is anonymous false otherwise
116 */
117 boolean isAnonymous();
118
119
120 /**
121 * Returns true if the effective principal associated with this session is
122 * the administrator.
123 *
124 * @see {@link ServerDNConstants#ADMIN_SYSTEM_DN}
125 * @return true if authorized as the administrator, false otherwise
126 */
127 boolean isAdministrator();
128
129
130 /**
131 * Returns true if the effective principal associated with this session is
132 * the administrator or is within the administrators group.
133 *
134 * @see {@link ServerDNConstants#ADMIN_SYSTEM_DN}
135 * @see {@link ServerDNConstants#ADMINISTRATORS_GROUP_DN}
136 * @return true if authorized as an administrator, false otherwise
137 */
138 boolean isAnAdministrator();
139
140
141 /**
142 * Gets the authentication level associated with this session.
143 *
144 * @return the authentication level associated with the session
145 */
146 AuthenticationLevel getAuthenticationLevel();
147
148
149 /**
150 * Gets the controls enabled for this session.
151 *
152 * @return the session controls as a Set
153 */
154 Set<Control> getControls();
155
156
157 /**
158 * Gets all outstanding operations currently being performed that have yet
159 * to be completed.
160 *
161 * @return the set of outstanding operations
162 */
163 Set<OperationContext> getOutstandingOperations();
164
165
166 /**
167 * Gets whether or not this session is virtual. Virtual sessions verses
168 * real sessions represent logical sessions established by non-LDAP
169 * services or embedding applications which do not expose the LDAP access.
170 *
171 * @return true if the session is virtual, false otherwise
172 */
173 boolean isVirtual();
174
175
176 /**
177 * Gets the socket address of the LDAP client or null if there is no LDAP
178 * client associated with the session. Some calls to the core can be made
179 * by embedding applications or by non-LDAP services using a programmatic
180 * (virtual) session. In these cases no client address is available.
181 *
182 * @return null if the session is virtual, non-null when the session is
183 * associated with a real LDAP client
184 */
185 SocketAddress getClientAddress();
186
187
188 /**
189 * Gets the socket address of the LDAP server or null if there is no LDAP
190 * service associated with the session. Some calls to the core can be
191 * made by embedding applications or by non-LDAP services using a
192 * programmatic (virtual) session. In these cases no service address is
193 * available.
194 *
195 * @return null if the session is virtual, non-null when the session is
196 * associated with a real LDAP service
197 */
198 SocketAddress getServiceAddress();
199
200
201 // -----------------------------------------------------------------------
202 // Operation Methods
203 // -----------------------------------------------------------------------
204
205
206 /**
207 * Adds an entry into the DirectoryService associated with this CoreSession.
208 *
209 * @param entry the entry to add
210 * @exception Exception on failures to add the entry
211 */
212 void add( ServerEntry entry ) throws Exception;
213
214
215 void add( AddRequest addRequest ) throws Exception;
216
217
218 /**
219 * Checks to see if an attribute in an entry contains a value.
220 *
221 * @param dn the distinguished name of the entry to check
222 * @param oid the OID of the attribute to check for the value
223 * @param value the value to check for
224 * @throws Exception if there are failures while comparing
225 */
226 void compare( LdapDN dn, String oid, Object value ) throws Exception;
227
228
229 boolean compare( CompareRequest compareRequest ) throws Exception;
230
231
232 /**
233 * Deletes an entry in the server.
234 *
235 * @param dn the distinguished name of the entry to delete
236 * @throws Exception if there are failures while deleting the entry
237 */
238 void delete( LdapDN dn ) throws Exception;
239
240
241 void delete( DeleteRequest deleteRequest ) throws Exception;
242
243 /**
244 * Checks to see if an entry exists.
245 */
246 boolean exists( LdapDN dn ) throws Exception;
247
248
249 /**
250 * Looks up an entry in the server returning all attributes: both user and
251 * operational attributes.
252 *
253 * @param dn the name of the entry to lookup
254 * @throws Exception if there are failures while looking up the entry
255 */
256 ClonedServerEntry lookup( LdapDN dn ) throws Exception;
257
258 ClonedServerEntry lookup( LdapDN dn, String[] atIds ) throws Exception;
259
260 ClonedServerEntry lookup( LdapDN dn, Control[] requestControls, ReferralHandlingMode refMode,
261 LdapDN authorized ) throws Exception;
262
263
264 /**
265 * Modifies an entry within the server by applying a list of modifications
266 * to the entry.
267 *
268 * @param dn the distinguished name of the entry to modify
269 * @param mods the list of modifications to apply
270 * @throws Exception if there are failures while modifying the entry
271 */
272 void modify( LdapDN dn, List<Modification> mods ) throws Exception;
273
274
275 void modify( ModifyRequest modifyRequest ) throws Exception;
276
277
278 /**
279 * Moves an entry or a branch of entries at a specified distinguished name
280 * to a position under a new parent.
281 *
282 * @param dn the distinguished name of the entry/branch to move
283 * @param newParent the new parent under which the entry/branch is moved
284 * @exception if there are failures while moving the entry/branch
285 */
286 void move( LdapDN dn, LdapDN newParent ) throws Exception;
287
288
289 void move( ModifyDnRequest modifyDnRequest ) throws Exception;
290
291
292 // void move( LdapDN dn, LdapDN newParent, Control[] requestControls, ReferralHandlingMode refMode,
293 // LdapDN authorized ) throws Exception;
294
295
296 /**
297 * Moves and renames (the relative distinguished name of) an entry (or a
298 * branch if the entry has children) at a specified distinguished name to
299 * a position under a new parent.
300 *
301 * @param dn the distinguished name of the entry/branch to move
302 * @param newParent the new parent under which the entry/branch is moved
303 * @param newRdn the new relative distinguished name of the entry at the
304 * root of the branch
305 * @exception if there are failures while moving and renaming the entry
306 * or branch
307 */
308 void moveAndRename( LdapDN dn, LdapDN newParent, Rdn newRdn, boolean deleteOldRdn ) throws Exception;
309
310
311 void moveAndRename( ModifyDnRequest modifyDnRequest ) throws Exception;
312
313
314 // void moveAndRename( LdapDN dn, LdapDN newParent, Rdn newRdn, boolean deleteOldRdn,
315 // Control[] requestControls, ReferralHandlingMode refMode, LdapDN authorized ) throws Exception;
316
317
318 /**
319 * Renames an entry by changing it's relative distinguished name. This
320 * has the side effect of changing the distinguished name of all entries
321 * directly or indirectly subordinate to the named entry if it has
322 * descendants.
323 *
324 * @param dn the distinguished name of the entry to rename
325 * @param newRdn the new relative distinguished name for the entry
326 * @param deleteOldRdn whether or not the old value for the relative
327 * distinguished name is to be deleted from the entry
328 * @throws Exception if there are failures while renaming the entry
329 */
330 void rename( LdapDN dn, Rdn newRdn, boolean deleteOldRdn ) throws Exception;
331
332
333 void rename( ModifyDnRequest modifyDnRequest ) throws Exception;
334
335
336 // void rename( LdapDN dn, Rdn newRdn, boolean deleteOldRdn,
337 // Control[] requestControls, ReferralHandlingMode refMode, LdapDN authorized ) throws Exception;
338
339
340 /**
341 * An optimized search operation using one level search scope which
342 * returns all the children of an entry specified by distinguished name.
343 * This is equivalent to a search operation with one level scope using
344 * the <code>(objectClass=*)</code> filter.
345 *
346 * @param dn the distinguished name of the entry to list the children of
347 * @param aliasDerefMode the alias dereferencing mode used
348 * @param returningAttributes the attributes to return
349 * @throws Exception if there are failures while listing children
350 */
351 EntryFilteringCursor list( LdapDN dn, AliasDerefMode aliasDerefMode,
352 Set<AttributeTypeOptions> returningAttributes ) throws Exception;
353
354
355 /**
356 * An optimized search operation using one level search scope which
357 * applies size and time limit constraints and returns all the children
358 * of an entry specified by distinguished name if thes limits are not
359 * violated. This is equivalent to a search operation with one level
360 * scope using the <code>(objectClass=*)</code> filter.
361 *
362 * @param dn the distinguished name of the entry to list the children of
363 * @param aliasDerefMode the alias dereferencing mode used
364 * @param returningAttributes the attributes to return
365 * @param sizeLimit the upper bound to the number of entries to return
366 * @param timeLimit the upper bound to the amount of time before
367 * terminating the search
368 * @throws Exception if there are failures while listing children
369 */
370 EntryFilteringCursor list( LdapDN dn, AliasDerefMode aliasDerefMode,
371 Set<AttributeTypeOptions> returningAttributes, int sizeLimit, int timeLimit ) throws Exception;
372
373
374 /**
375 * Searches the directory using a specified search scope and filter.
376 *
377 * @param dn the distinguished name of the entry to list the children of
378 * @param scope the search scope to apply
379 * @param aliasDerefMode the alias dereferencing mode used
380 * @param returningAttributes the attributes to return
381 * @throws Exception if there are failures while listing children
382 */
383 EntryFilteringCursor search( LdapDN dn, SearchScope scope, ExprNode filter, AliasDerefMode aliasDerefMode,
384 Set<AttributeTypeOptions> returningAttributes ) throws Exception;
385
386
387 /**
388 * Searches the directory using a specified search scope and filter.
389 *
390 * @param dn the distinguished name of the entry to list the children of
391 * @param aliasDerefMode the alias dereferencing mode used
392 * @param returningAttributes the attributes to return
393 * @param sizeLimit the upper bound to the number of entries to return
394 * @param timeLimit the upper bound to the amount of time before
395 * terminating the search
396 * @throws Exception if there are failures while listing children
397 */
398 EntryFilteringCursor search( LdapDN dn, SearchScope scope, ExprNode filter, AliasDerefMode aliasDerefMode,
399 Set<AttributeTypeOptions> returningAttributes, int sizeLimit, int timeLimit ) throws Exception;
400
401
402 EntryFilteringCursor search( SearchRequest searchRequest ) throws Exception;
403
404
405 void unbind() throws Exception;
406
407
408 void unbind( UnbindRequest unbindRequest ) throws Exception;
409 }