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;
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 }