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;
021    
022    
023    import java.net.SocketAddress;
024    import java.util.List;
025    import java.util.Set;
026    
027    import org.apache.directory.server.constants.ServerDNConstants;
028    import org.apache.directory.server.core.changelog.LogChange;
029    import org.apache.directory.server.core.entry.ClonedServerEntry;
030    import org.apache.directory.server.core.filtering.EntryFilteringCursor;
031    import org.apache.directory.server.core.interceptor.context.OperationContext;
032    import org.apache.directory.shared.ldap.constants.AuthenticationLevel;
033    import org.apache.directory.shared.ldap.entry.Modification;
034    import org.apache.directory.shared.ldap.entry.ServerEntry;
035    import org.apache.directory.shared.ldap.filter.ExprNode;
036    import org.apache.directory.shared.ldap.filter.SearchScope;
037    import org.apache.directory.shared.ldap.message.AliasDerefMode;
038    import org.apache.directory.shared.ldap.message.control.Control;
039    import org.apache.directory.shared.ldap.message.internal.InternalAddRequest;
040    import org.apache.directory.shared.ldap.message.internal.InternalCompareRequest;
041    import org.apache.directory.shared.ldap.message.internal.InternalDeleteRequest;
042    import org.apache.directory.shared.ldap.message.internal.InternalModifyDnRequest;
043    import org.apache.directory.shared.ldap.message.internal.InternalModifyRequest;
044    import org.apache.directory.shared.ldap.message.internal.InternalSearchRequest;
045    import org.apache.directory.shared.ldap.message.internal.InternalUnbindRequest;
046    import org.apache.directory.shared.ldap.name.DN;
047    import org.apache.directory.shared.ldap.name.RDN;
048    import org.apache.directory.shared.ldap.schema.AttributeTypeOptions;
049    
050    
051    /**
052     * An interface representing a session with the core DirectoryService. These 
053     * sessions may either be real representing LDAP sessions associated with an 
054     * actual LDAP network client, or may be virtual in which case there is no 
055     * real LDAP client associated with the session.  This interface is used by 
056     * the DirectoryService core to track session specific parameters used to make 
057     * various decisions during the course of operation handling.
058     * 
059     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
060     * @version $Rev$, $Date$
061     */
062    public interface CoreSession
063    {
064        /**
065         * Gets the DirectoryService this session is bound to.
066         *
067         * @return the DirectoryService associated with this session
068         */
069        DirectoryService getDirectoryService();
070    
071        
072        /**
073         * Gets the LDAP principal used to authenticate.  This is the identity 
074         * used to establish this session on authentication.
075         *
076         * @return the LdapPrincipal used to authenticate.
077         */
078        LdapPrincipal getAuthenticatedPrincipal();
079        
080        
081        /**
082         * Gets the LDAP principal used for the effective identity associated with
083         * this session which may not be the same as the authenticated principal.  
084         * This principal is often the same as the authenticated principal.  
085         * Sometimes however, a user authenticating as one principal, may request 
086         * to have all operations performed in the session as if they were another 
087         * principal.  The SASL mechanism allows setting an authorized principal 
088         * which is in effect for the duration of the session.  In this case all 
089         * operations are performed as if they are being performed by this 
090         * principal.  This method will then return the authorized principal which
091         * will be different from the authenticated principal.
092         * 
093         * Implementations of this interface may have a means to set the 
094         * authorized principal which may or may not be the same as the 
095         * authenticated principal.  Implementations should default to return the 
096         * authenticated principal when an authorized principal is not provided.
097         *
098         * @return the LdapPrincipal to use as the effective principal
099         */
100        LdapPrincipal getEffectivePrincipal();
101    
102        
103        /**
104         * Gets whether or not confidentiality is enabled for this session.
105         * 
106         * @return true if confidentiality is enabled, false otherwise
107         */
108        boolean isConfidential();
109        
110        
111        /**
112         * Gets whether or not this user is anonymous.
113         *
114         * @return true if the identity is anonymous false otherwise
115         */
116        boolean isAnonymous();
117        
118        
119        /**
120         * Returns true if the effective principal associated with this session is 
121         * the administrator.
122         * 
123         * @see {@link ServerDNConstants#ADMIN_SYSTEM_DN}
124         * @return true if authorized as the administrator, false otherwise
125         */
126        boolean isAdministrator();
127        
128        
129        /**
130         * Returns true if the effective principal associated with this session is 
131         * the administrator or is within the administrators group.
132         *
133         * @see {@link ServerDNConstants#ADMIN_SYSTEM_DN}
134         * @see {@link ServerDNConstants#ADMINISTRATORS_GROUP_DN}
135         * @return true if authorized as an administrator, false otherwise
136         */
137        boolean isAnAdministrator();
138        
139        
140        /**
141         * Gets the authentication level associated with this session.
142         * 
143         * @return the authentication level associated with the session
144         */
145        AuthenticationLevel getAuthenticationLevel();
146        
147        
148        /**
149         * Gets the controls enabled for this session.
150         * 
151         * @return the session controls as a Set
152         */
153        Set<Control> getControls();
154        
155        
156        /**
157         * Gets all outstanding operations currently being performed that have yet 
158         * to be completed.
159         * 
160         * @return the set of outstanding operations
161         */
162        Set<OperationContext> getOutstandingOperations();
163    
164        
165        /**
166         * Gets whether or not this session is virtual.  Virtual sessions verses 
167         * real sessions represent logical sessions established by non-LDAP 
168         * services or embedding applications which do not expose the LDAP access.
169         *
170         * @return true if the session is virtual, false otherwise
171         */
172        boolean isVirtual();
173        
174        
175        /**
176         * Gets the socket address of the LDAP client or null if there is no LDAP
177         * client associated with the session.  Some calls to the core can be made
178         * by embedding applications or by non-LDAP services using a programmatic
179         * (virtual) session.  In these cases no client address is available.
180         * 
181         * @return null if the session is virtual, non-null when the session is 
182         * associated with a real LDAP client
183         */
184        SocketAddress getClientAddress();
185    
186    
187        /**
188         * Gets the socket address of the LDAP server or null if there is no LDAP
189         * service associated with the session.  Some calls to the core can be 
190         * made by embedding applications or by non-LDAP services using a 
191         * programmatic (virtual) session.  In these cases no service address is 
192         * available.
193         * 
194         * @return null if the session is virtual, non-null when the session is 
195         * associated with a real LDAP service
196         */
197        SocketAddress getServiceAddress();
198        
199        
200        // -----------------------------------------------------------------------
201        // Operation Methods
202        // -----------------------------------------------------------------------
203        /**
204         * Adds an entry into the DirectoryService associated with this CoreSession.
205         * 
206         * @param entry the entry to add
207         * @exception Exception on failures to add the entry
208         */
209        void add( ServerEntry entry ) throws Exception;
210        
211        
212        /**
213         * Adds an entry into the DirectoryService associated with this CoreSession.
214         * 
215         * @param entry the entry to add
216         * @param log a flag set if the added entry should be stored in the changeLog
217         * @exception Exception on failures to add the entry
218         */
219        void add( ServerEntry entry, LogChange log ) throws Exception;
220        
221        
222        /**
223         * Adds an entry into the DirectoryService associated with this CoreSession.
224         * The flag is used to tell the server to ignore the referrals and manipulate
225         * them as if they were normal entries.
226         * 
227         * @param entry the entry to add
228         * @param ignoreReferral a flag to tell the server to ignore referrals
229         * @exception Exception on failures to add the entry
230         */
231        void add( ServerEntry entry, boolean ignoreReferral ) throws Exception;
232        
233        
234        /**
235         * Adds an entry into the DirectoryService associated with this CoreSession.
236         * The flag is used to tell the server to ignore the referrals and manipulate
237         * them as if they were normal entries.
238         * 
239         * @param entry the entry to add
240         * @param ignoreReferral a flag to tell the server to ignore referrals
241         * @param log a flag set if the added entry should be stored in the changeLog
242         * @exception Exception on failures to add the entry
243         */
244        void add( ServerEntry entry, boolean ignoreReferral, LogChange log ) throws Exception;
245        
246        
247        /**
248         * Adds an entry into the DirectoryService associated with this CoreSession.
249         * The entry is built using the received AddRequest.
250         * 
251         * @param InternalAddRequest the request to execute
252         * @exception Exception on failures to add the entry
253         */
254        void add( InternalAddRequest addRequest ) throws Exception;
255        
256        
257        /**
258         * Adds an entry into the DirectoryService associated with this CoreSession.
259         * The entry is built using the received AddRequest.
260         * 
261         * @param InternalAddRequest the request to execute
262         * @param log a flag set if the added entry should be stored in the changeLog
263         * @exception Exception on failures to add the entry
264         */
265        void add( InternalAddRequest addRequest, LogChange log ) throws Exception;
266        
267        
268        /**
269         * Checks to see if an attribute in an entry contains a value.
270         *
271         * @param dn the distinguished name of the entry to check
272         * @param oid the OID of the attribute to check for the value
273         * @param value the value to check for
274         * @throws Exception if there are failures while comparing
275         */
276        boolean compare( DN dn, String oid, Object value ) throws Exception;
277        
278        
279        /**
280         * Checks to see if an attribute in an entry contains a value.
281         * The flag is used to tell the server to ignore the referrals and manipulate
282         * them as if they were normal entries.
283         *
284         * @param dn the distinguished name of the entry to check
285         * @param oid the OID of the attribute to check for the value
286         * @param value the value to check for
287         * @param ignoreReferral a flag to tell the server to ignore referrals
288         * @throws Exception if there are failures while comparing
289         */
290        boolean compare( DN dn, String oid, Object value, boolean ignoreReferral ) throws Exception;
291        
292        
293        /**
294         * Checks to see if an attribute in an entry contains a value.
295         *
296         * @param compareRequest the received request
297         * @throws Exception if there are failures while comparing
298         */
299        boolean compare( InternalCompareRequest compareRequest ) throws Exception;
300    
301        
302        /**
303         * Deletes an entry in the server.
304         *
305         * @param dn the distinguished name of the entry to delete
306         * @throws Exception if there are failures while deleting the entry
307         */
308        void delete( DN dn ) throws Exception;
309    
310        
311        /**
312         * Deletes an entry in the server.
313         *
314         * @param dn the distinguished name of the entry to delete
315         * @param log a flag set if the added entry should be stored in the changeLog
316         * @throws Exception if there are failures while deleting the entry
317         */
318        void delete( DN dn, LogChange log ) throws Exception;
319        
320        
321        void delete( InternalDeleteRequest deleteRequest ) throws Exception;
322        
323        
324        void delete( InternalDeleteRequest deleteRequest, LogChange log ) throws Exception;
325    
326        
327        /**
328         * Deletes an entry in the server.
329         * The flag is used to tell the server to ignore the referrals and manipulate
330         * them as if they were normal entries.
331         *
332         * @param dn the distinguished name of the entry to delete
333         * @param ignoreReferral a flag to tell the server to ignore referrals
334         * @throws Exception if there are failures while deleting the entry
335         */
336        void delete( DN dn, boolean ignoreReferral ) throws Exception;
337        
338        
339        /**
340         * Deletes an entry in the server.
341         * The flag is used to tell the server to ignore the referrals and manipulate
342         * them as if they were normal entries.
343         *
344         * @param dn the distinguished name of the entry to delete
345         * @param ignoreReferral a flag to tell the server to ignore referrals
346         * @param log a flag set if the added entry should be stored in the changeLog
347         * @throws Exception if there are failures while deleting the entry
348         */
349        void delete( DN dn, boolean ignoreReferral, LogChange log ) throws Exception;
350        
351        
352        /**
353         * Checks to see if an entry exists. 
354         */
355        boolean exists( DN dn ) throws Exception;
356        
357        
358        /**
359         * Looks up an entry in the server returning all attributes: both user and
360         * operational attributes.
361         *
362         * @param dn the name of the entry to lookup
363         * @throws Exception if there are failures while looking up the entry
364         */
365        ClonedServerEntry lookup( DN dn ) throws Exception;
366    
367        /**
368         * Looks up an entry in the server returning all attributes: both user and
369         * operational attributes.
370         *
371         * @param dn the name of the entry to lookup
372         * @param atIds The list of attributes to return
373         * @throws Exception if there are failures while looking up the entry
374         */
375        ClonedServerEntry lookup( DN dn, String[] atIds ) throws Exception;
376    
377        
378        /**
379         * Modifies an entry within the server by applying a list of modifications 
380         * to the entry.
381         *
382         * @param dn the distinguished name of the entry to modify
383         * @param mods the list of modifications to apply
384         * @throws Exception if there are failures while modifying the entry
385         */
386        void modify( DN dn, List<Modification> mods ) throws Exception;
387        
388        
389        /**
390         * Modifies an entry within the server by applying a list of modifications 
391         * to the entry.
392         *
393         * @param dn the distinguished name of the entry to modify
394         * @param mods the list of modifications to apply
395         * @param log a flag set if the added entry should be stored in the changeLog
396         * @throws Exception if there are failures while modifying the entry
397         */
398        void modify( DN dn, List<Modification> mods, LogChange log ) throws Exception;
399        
400        
401        /**
402         * Modifies an entry within the server by applying a list of modifications 
403         * to the entry.
404         * The flag is used to tell the server to ignore the referrals and manipulate
405         * them as if they were normal entries.
406         *
407         * @param dn the distinguished name of the entry to modify
408         * @param ignoreReferral a flag to tell the server to ignore referrals
409         * @param mods the list of modifications to apply
410         * @throws Exception if there are failures while modifying the entry
411         */
412        void modify( DN dn, List<Modification> mods, boolean ignoreReferral ) throws Exception;
413        
414        
415        /**
416         * Modifies an entry within the server by applying a list of modifications 
417         * to the entry.
418         * The flag is used to tell the server to ignore the referrals and manipulate
419         * them as if they were normal entries.
420         *
421         * @param dn the distinguished name of the entry to modify
422         * @param ignoreReferral a flag to tell the server to ignore referrals
423         * @param mods the list of modifications to apply
424         * @param log a flag set if the added entry should be stored in the changeLog
425         * @throws Exception if there are failures while modifying the entry
426         */
427        void modify( DN dn, List<Modification> mods, boolean ignoreReferral, LogChange log ) throws Exception;
428        
429        
430        void modify( InternalModifyRequest modifyRequest ) throws Exception;
431        
432        
433        void modify( InternalModifyRequest modifyRequest, LogChange log ) throws Exception;
434    
435        
436        /**
437         * Moves an entry or a branch of entries at a specified distinguished name
438         * to a position under a new parent.
439         * 
440         * @param dn the distinguished name of the entry/branch to move
441         * @param newParent the new parent under which the entry/branch is moved
442         * @exception if there are failures while moving the entry/branch
443         */
444        void move( DN dn, DN newParent ) throws Exception;
445        
446        
447        /**
448         * Moves an entry or a branch of entries at a specified distinguished name
449         * to a position under a new parent.
450         * 
451         * @param dn the distinguished name of the entry/branch to move
452         * @param newParent the new parent under which the entry/branch is moved
453         * @param log a flag set if the added entry should be stored in the changeLog
454         * @exception if there are failures while moving the entry/branch
455         */
456        void move( DN dn, DN newParent, LogChange log ) throws Exception;
457        
458        
459        /**
460         * Moves an entry or a branch of entries at a specified distinguished name
461         * to a position under a new parent.
462         * 
463         * @param dn the distinguished name of the entry/branch to move
464         * @param newParent the new parent under which the entry/branch is moved
465         * @param ignoreReferral a flag to tell the server to ignore referrals
466         * @exception if there are failures while moving the entry/branch
467         */
468        void move( DN dn, DN newParent, boolean ignoreReferral ) throws Exception;
469        
470        
471        /**
472         * Moves an entry or a branch of entries at a specified distinguished name
473         * to a position under a new parent.
474         * 
475         * @param dn the distinguished name of the entry/branch to move
476         * @param newParent the new parent under which the entry/branch is moved
477         * @param ignoreReferral a flag to tell the server to ignore referrals
478         * @param log a flag set if the added entry should be stored in the changeLog
479         * @exception if there are failures while moving the entry/branch
480         */
481        void move( DN dn, DN newParent, boolean ignoreReferral, LogChange log ) throws Exception;
482        
483        
484        /**
485         * Move an entry by changing its superior.
486         *
487         * @param modifyDnRequest The ModifyDN request
488         * @throws Exception if there are failures while moving the entry/branch
489         */
490        void move( InternalModifyDnRequest modifyDnRequest ) throws Exception;
491        
492        
493        /**
494         * Move an entry by changing its superior.
495         *
496         * @param modifyDnRequest The ModifyDN request
497         * @param log a flag set if the added entry should be stored in the changeLog
498         * @throws Exception if there are failures while moving the entry/branch
499         */
500        void move( InternalModifyDnRequest modifyDnRequest, LogChange log ) throws Exception;
501        
502        
503        /**
504         * Moves and renames (the relative distinguished name of) an entry (or a 
505         * branch if the entry has children) at a specified distinguished name to 
506         * a position under a new parent.
507         * 
508         * @param dn the distinguished name of the entry/branch to move
509         * @param newParent the new parent under which the entry/branch is moved
510         * @param newRdn the new relative distinguished name of the entry at the 
511         * root of the branch
512         * @exception if there are failures while moving and renaming the entry
513         * or branch
514         */
515        void moveAndRename( DN dn, DN newParent, RDN newRdn, boolean deleteOldRdn ) throws Exception;
516        
517        
518        /**
519         * Moves and renames (the relative distinguished name of) an entry (or a 
520         * branch if the entry has children) at a specified distinguished name to 
521         * a position under a new parent.
522         * 
523         * @param dn the distinguished name of the entry/branch to move
524         * @param newParent the new parent under which the entry/branch is moved
525         * @param newRdn the new relative distinguished name of the entry at the 
526         * root of the branch
527         * @param log a flag set if the added entry should be stored in the changeLog
528         * @exception if there are failures while moving and renaming the entry
529         * or branch
530         */
531        void moveAndRename( DN dn, DN newParent, RDN newRdn, boolean deleteOldRdn, LogChange log ) throws Exception;
532        
533        
534        /**
535         * Moves and renames (the relative distinguished name of) an entry (or a 
536         * branch if the entry has children) at a specified distinguished name to 
537         * a position under a new parent.
538         * 
539         * @param dn the distinguished name of the entry/branch to move
540         * @param newParent the new parent under which the entry/branch is moved
541         * @param newRdn the new relative distinguished name of the entry at the 
542         * root of the branch
543         * @param ignoreReferral  a flag to tell the server to ignore referrals
544         * @exception if there are failures while moving and renaming the entry
545         * or branch
546         */
547        void moveAndRename( DN dn, DN newParent, RDN newRdn, boolean deleteOldRdn, boolean ignoreReferral ) throws Exception;
548        
549        
550        /**
551         * Moves and renames (the relative distinguished name of) an entry (or a 
552         * branch if the entry has children) at a specified distinguished name to 
553         * a position under a new parent.
554         * 
555         * @param dn the distinguished name of the entry/branch to move
556         * @param newParent the new parent under which the entry/branch is moved
557         * @param newRdn the new relative distinguished name of the entry at the 
558         * root of the branch
559         * @param ignoreReferral  a flag to tell the server to ignore referrals
560         * @param log a flag set if the added entry should be stored in the changeLog
561         * @exception if there are failures while moving and renaming the entry
562         * or branch
563         */
564        void moveAndRename( DN dn, DN newParent, RDN newRdn, boolean deleteOldRdn, boolean ignoreReferral, LogChange log ) throws Exception;
565        
566        
567        /**
568         * Move and rename an entry. We change the RDN and the superior.
569         *
570         * @param modifyDnRequest The move and rename request
571         * @throws Exception if there are failures while moving and renaming the entry
572         * or branch
573         */
574        void moveAndRename( InternalModifyDnRequest modifyDnRequest ) throws Exception;
575        
576        
577        /**
578         * Move and rename an entry. We change the RDN and the superior.
579         *
580         * @param modifyDnRequest The move and rename request
581         * @param log a flag set if the added entry should be stored in the changeLog
582         * @throws Exception if there are failures while moving and renaming the entry
583         * or branch
584         */
585        void moveAndRename( InternalModifyDnRequest modifyDnRequest, LogChange log ) throws Exception;
586        
587        
588        /**
589         * Renames an entry by changing it's relative distinguished name.  This 
590         * has the side effect of changing the distinguished name of all entries
591         * directly or indirectly subordinate to the named entry if it has 
592         * descendants.
593         *
594         * @param dn the distinguished name of the entry to rename
595         * @param newRdn the new relative distinguished name for the entry
596         * @param deleteOldRdn whether or not the old value for the relative 
597         * distinguished name is to be deleted from the entry
598         * @throws Exception if there are failures while renaming the entry
599         */
600        void rename( DN dn, RDN newRdn, boolean deleteOldRdn ) throws Exception;
601        
602        
603        /**
604         * Renames an entry by changing it's relative distinguished name.  This 
605         * has the side effect of changing the distinguished name of all entries
606         * directly or indirectly subordinate to the named entry if it has 
607         * descendants.
608         *
609         * @param dn the distinguished name of the entry to rename
610         * @param newRdn the new relative distinguished name for the entry
611         * @param deleteOldRdn whether or not the old value for the relative 
612         * distinguished name is to be deleted from the entry
613         * @param log a flag set if the added entry should be stored in the changeLog
614         * @throws Exception if there are failures while renaming the entry
615         */
616        void rename( DN dn, RDN newRdn, boolean deleteOldRdn, LogChange log ) throws Exception;
617        
618        
619        /**
620         * Renames an entry by changing it's relative distinguished name.  This 
621         * has the side effect of changing the distinguished name of all entries
622         * directly or indirectly subordinate to the named entry if it has 
623         * descendants.
624         *
625         * @param dn the distinguished name of the entry to rename
626         * @param newRdn the new relative distinguished name for the entry
627         * @param deleteOldRdn whether or not the old value for the relative 
628         * distinguished name is to be deleted from the entry
629         * @param ignoreReferral a flag to tell the server to ignore referrals
630         * @throws Exception if there are failures while renaming the entry
631         */
632        void rename( DN dn, RDN newRdn, boolean deleteOldRdn, boolean ignoreReferral ) throws Exception;
633        
634        
635        /**
636         * Renames an entry by changing it's relative distinguished name.  This 
637         * has the side effect of changing the distinguished name of all entries
638         * directly or indirectly subordinate to the named entry if it has 
639         * descendants.
640         *
641         * @param dn the distinguished name of the entry to rename
642         * @param newRdn the new relative distinguished name for the entry
643         * @param deleteOldRdn whether or not the old value for the relative 
644         * distinguished name is to be deleted from the entry
645         * @param ignoreReferral a flag to tell the server to ignore referrals
646         * @param log a flag set if the added entry should be stored in the changeLog
647         * @throws Exception if there are failures while renaming the entry
648         */
649        void rename( DN dn, RDN newRdn, boolean deleteOldRdn, boolean ignoreReferral, LogChange log ) throws Exception;
650        
651        
652        /**
653         * Rename an entry applying the ModifyDN request 
654         *
655         * @param modifyDnRequest The requested modification
656         * @throws Exception if there are failures while renaming the entry
657         */
658        void rename( InternalModifyDnRequest modifyDnRequest ) throws Exception;
659        
660        
661        /**
662         * Rename an entry applying the ModifyDN request 
663         *
664         * @param modifyDnRequest The requested modification
665         * @param log a flag set if the added entry should be stored in the changeLog
666         * @throws Exception if there are failures while renaming the entry
667         */
668        void rename( InternalModifyDnRequest modifyDnRequest, LogChange log ) throws Exception;
669        
670        
671        /**
672         * An optimized search operation using one level search scope which 
673         * returns all the children of an entry specified by distinguished name.
674         * This is equivalent to a search operation with one level scope using
675         * the <code>(objectClass=*)</code> filter.
676         *
677         * @param dn the distinguished name of the entry to list the children of
678         * @param aliasDerefMode the alias dereferencing mode used
679         * @param returningAttributes the attributes to return
680         * @throws Exception if there are failures while listing children
681         */
682        EntryFilteringCursor list( DN dn, AliasDerefMode aliasDerefMode, 
683            Set<AttributeTypeOptions> returningAttributes ) throws Exception;
684        
685        
686        /**
687         * An optimized search operation using one level search scope which 
688         * applies size and time limit constraints and returns all the children 
689         * of an entry specified by distinguished name if thes limits are not
690         * violated.  This is equivalent to a search operation with one level 
691         * scope using the <code>(objectClass=*)</code> filter.
692         *
693         * @param dn the distinguished name of the entry to list the children of
694         * @param aliasDerefMode the alias dereferencing mode used
695         * @param returningAttributes the attributes to return
696         * @param sizeLimit the upper bound to the number of entries to return
697         * @param timeLimit the upper bound to the amount of time before 
698         * terminating the search
699         * @throws Exception if there are failures while listing children
700         */
701        EntryFilteringCursor list( DN dn, AliasDerefMode aliasDerefMode, 
702            Set<AttributeTypeOptions> returningAttributes, long sizeLimit, int timeLimit ) throws Exception;
703        
704        
705        /**
706         * Searches the directory using a specified filter. The scope is defaulting
707         * to 'base'. The alias dereferencing default to 'always'. the returned attributes 
708         * defaults to 'all the user attributes)
709         *
710         * @param dn the distinguished name of the entry to list the children of
711         * @param filter the search filter
712         * @throws Exception if there are failures while listing children
713         */
714        EntryFilteringCursor search( DN dn, String filter ) throws Exception;
715        
716        
717        /**
718         * Searches the directory using a specified filter. The scope is defaulting
719         * to 'base'. The alias dereferencing default to 'always'. the returned attributes 
720         * defaults to 'all the user attributes)
721         *
722         * @param dn the distinguished name of the entry to list the children of
723         * @param filter the search filter
724         * @param ignoreReferrals a flag to tell the server to ignore referrals
725         * @throws Exception if there are failures while listing children
726         */
727        EntryFilteringCursor search( DN dn, String filter, boolean ignoreReferrals ) throws Exception;
728        
729        
730        /**
731         * Searches the directory using a specified search scope and filter.
732         *
733         * @param dn the distinguished name of the entry to list the children of
734         * @param scope the search scope to apply
735         * @param filter the search filter
736         * @param aliasDerefMode the alias dereferencing mode used
737         * @param returningAttributes the attributes to return
738         * @throws Exception if there are failures while listing children
739         */
740        EntryFilteringCursor search( DN dn, SearchScope scope, ExprNode filter, AliasDerefMode aliasDerefMode, 
741            Set<AttributeTypeOptions> returningAttributes ) throws Exception;
742        
743        
744        /**
745         * Searches the directory using a specified search scope and filter.
746         *
747         * @param dn the distinguished name of the entry to list the children of
748         * @param scope the search scope to apply
749         * @param filter the search filter
750         * @param aliasDerefMode the alias dereferencing mode used
751         * @param returningAttributes the attributes to return
752         * @throws Exception if there are failures while listing children
753         */
754        
755        
756        /**
757         * Searches the directory using a specified search scope and filter.
758         *
759         * @param dn the distinguished name of the entry to list the children of
760         * @param aliasDerefMode the alias dereferencing mode used
761         * @param returningAttributes the attributes to return
762         * @param sizeLimit the upper bound to the number of entries to return
763         * @param timeLimit the upper bound to the amount of time before 
764         * terminating the search
765         * @throws Exception if there are failures while listing children
766         */
767        EntryFilteringCursor search( DN dn, SearchScope scope, ExprNode filter, AliasDerefMode aliasDerefMode, 
768            Set<AttributeTypeOptions> returningAttributes, long sizeLimit, int timeLimit ) throws Exception;
769    
770    
771        EntryFilteringCursor search( InternalSearchRequest searchRequest ) throws Exception;
772    
773    
774        void unbind() throws Exception;
775        
776        
777        void unbind( InternalUnbindRequest unbindRequest ) throws Exception;
778    }