/*
    *   Licensed to the Apache Software Foundation (ASF) under one
    *   or more contributor license agreements.  See the NOTICE file
    *   distributed with this work for additional information
    *   regarding copyright ownership.  The ASF licenses this file
    *   to you under the Apache License, Version 2.0 (the
    *   "License"); you may not use this file except in compliance
    *   with the License.  You may obtain a copy of the License at
    *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   *   Unless required by applicable law or agreed to in writing,
   *   software distributed under the License is distributed on an
   *   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   *   KIND, either express or implied.  See the License for the
   *   specific language governing permissions and limitations
   *   under the License.
   *
   */
  package org.apache.directory.server.core.api;
  
  
  import java.io.IOException;
  import java.net.SocketAddress;
  import java.util.List;
  import java.util.Set;
  
  import org.apache.directory.api.ldap.model.constants.AuthenticationLevel;
  import org.apache.directory.api.ldap.model.cursor.Cursor;
  import org.apache.directory.api.ldap.model.entry.Entry;
  import org.apache.directory.api.ldap.model.entry.Modification;
  import org.apache.directory.api.ldap.model.exception.LdapException;
  import org.apache.directory.api.ldap.model.filter.ExprNode;
  import org.apache.directory.api.ldap.model.message.AddRequest;
  import org.apache.directory.api.ldap.model.message.AliasDerefMode;
  import org.apache.directory.api.ldap.model.message.CompareRequest;
  import org.apache.directory.api.ldap.model.message.Control;
  import org.apache.directory.api.ldap.model.message.DeleteRequest;
  import org.apache.directory.api.ldap.model.message.ModifyDnRequest;
  import org.apache.directory.api.ldap.model.message.ModifyRequest;
  import org.apache.directory.api.ldap.model.message.SearchRequest;
  import org.apache.directory.api.ldap.model.message.SearchScope;
  import org.apache.directory.api.ldap.model.message.UnbindRequest;
  import org.apache.directory.api.ldap.model.name.Dn;
  import org.apache.directory.api.ldap.model.name.Rdn;
  import org.apache.directory.server.constants.ServerDNConstants;
  import org.apache.directory.server.core.api.changelog.LogChange;
  import org.apache.directory.server.core.api.interceptor.context.OperationContext;
  import org.apache.directory.server.core.api.partition.Partition;
  import org.apache.directory.server.core.api.partition.PartitionTxn;
  
  
  /**
   * An interface representing a session with the core DirectoryService. These 
   * sessions may either be real representing LDAP sessions associated with an 
   * actual LDAP network client, or may be virtual in which case there is no 
   * real LDAP client associated with the session.  This interface is used by 
   * the DirectoryService core to track session specific parameters used to make 
   * various decisions during the course of operation handling.
   * 
   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
   */
  public interface CoreSession
  {
      /**
       * Gets the DirectoryService this session is bound to.
       *
       * @return the DirectoryService associated with this session
       */
      DirectoryService getDirectoryService();
  
  
      /**
       * Gets the anonymous LDAP principal used to authenticate.
       *
       * @return the LdapPrincipal used to authenticate.
       */
      LdapPrincipal getAnonymousPrincipal();
  
  
      /**
       * Gets the LDAP principal used to authenticate.  This is the identity 
       * used to establish this session on authentication.
       *
       * @return the LdapPrincipal used to authenticate.
       */
      LdapPrincipal getAuthenticatedPrincipal();
  
  
      /**
       * Gets the LDAP principal used for the effective identity associated with
       * this session which may not be the same as the authenticated principal.  
       * This principal is often the same as the authenticated principal.  
       * Sometimes however, a user authenticating as one principal, may request 
       * to have all operations performed in the session as if they were another 
       * principal.  The SASL mechanism allows setting an authorized principal 
       * which is in effect for the duration of the session.  In this case all 
       * operations are performed as if they are being performed by this 
       * principal.  This method will then return the authorized principal which
      * will be different from the authenticated principal.
      * 
      * Implementations of this interface may have a means to set the 
      * authorized principal which may or may not be the same as the 
      * authenticated principal.  Implementations should default to return the 
      * authenticated principal when an authorized principal is not provided.
      *
      * @return the LdapPrincipal to use as the effective principal
      */
     LdapPrincipal getEffectivePrincipal();
 
 
     /**
      * Gets whether or not confidentiality is enabled for this session.
      * 
      * @return true if confidentiality is enabled, false otherwise
      */
     boolean isConfidential();
 
 
     /**
      * Gets whether or not this user is anonymous.
      *
      * @return true if the identity is anonymous false otherwise
      */
     boolean isAnonymous();
 
 
     /**
      * Returns true if the effective principal associated with this session is 
      * the administrator.
      * 
      * @see ServerDNConstants#ADMIN_SYSTEM_DN
      * @return true if authorized as the administrator, false otherwise
      */
     boolean isAdministrator();
 
 
     /**
      * Returns true if the effective principal associated with this session is 
      * the administrator or is within the administrators group.
      *
      * @see ServerDNConstants#ADMIN_SYSTEM_DN
      * @see ServerDNConstants#ADMINISTRATORS_GROUP_DN
      * @return true if authorized as an administrator, false otherwise
      */
     boolean isAnAdministrator();
 
 
     /**
      * Gets the authentication level associated with this session.
      * 
      * @return the authentication level associated with the session
      */
     AuthenticationLevel getAuthenticationLevel();
 
 
     /**
      * Gets the controls enabled for this session.
      * 
      * @return the session controls as a Set
      */
     Set<Control> getControls();
 
 
     /**
      * Gets all outstanding operations currently being performed that have yet 
      * to be completed.
      * 
      * @return the set of outstanding operations
      */
     Set<OperationContext> getOutstandingOperations();
 
 
     /**
      * Gets whether or not this session is virtual.  Virtual sessions verses 
      * real sessions represent logical sessions established by non-LDAP 
      * services or embedding applications which do not expose the LDAP access.
      *
      * @return true if the session is virtual, false otherwise
      */
     boolean isVirtual();
 
 
     /**
      * Gets the socket address of the LDAP client or null if there is no LDAP
      * client associated with the session.  Some calls to the core can be made
      * by embedding applications or by non-LDAP services using a programmatic
      * (virtual) session.  In these cases no client address is available.
      * 
      * @return null if the session is virtual, non-null when the session is 
      * associated with a real LDAP client
      */
     SocketAddress getClientAddress();
 
 
     /**
      * Gets the socket address of the LDAP server or null if there is no LDAP
      * service associated with the session.  Some calls to the core can be 
      * made by embedding applications or by non-LDAP services using a 
      * programmatic (virtual) session.  In these cases no service address is 
      * available.
      * 
      * @return null if the session is virtual, non-null when the session is 
      * associated with a real LDAP service
      */
     SocketAddress getServiceAddress();
 
 
     // -----------------------------------------------------------------------
     // Operation Methods
     // -----------------------------------------------------------------------
     /**
      * Adds an entry into the DirectoryService associated with this CoreSession.
      * 
      * @param entry the entry to add
      * @exception LdapException on failures to add the entry
      */
     void add( Entry entry ) throws LdapException;
 
 
     /**
      * Adds an entry into the DirectoryService associated with this CoreSession.
      * 
      * @param entry the entry to add
      * @param log a flag set if the added entry should be stored in the changeLog
      * @exception LdapException on failures to add the entry
      */
     void add( Entry entry, LogChange log ) throws LdapException;
 
 
     /**
      * Adds an entry into the DirectoryService associated with this CoreSession.
      * The flag is used to tell the server to ignore the referrals and manipulate
      * them as if they were normal entries.
      * 
      * @param entry the entry to add
      * @param ignoreReferral a flag to tell the server to ignore referrals
      * @exception LdapException on failures to add the entry
      */
     void add( Entry entry, boolean ignoreReferral ) throws LdapException;
 
 
     /**
      * Adds an entry into the DirectoryService associated with this CoreSession.
      * The flag is used to tell the server to ignore the referrals and manipulate
      * them as if they were normal entries.
      * 
      * @param entry the entry to add
      * @param ignoreReferral a flag to tell the server to ignore referrals
      * @param log a flag set if the added entry should be stored in the changeLog
      * @exception LdapException on failures to add the entry
      */
     void add( Entry entry, boolean ignoreReferral, LogChange log ) throws LdapException;
 
 
     /**
      * Adds an entry into the DirectoryService associated with this CoreSession.
      * The entry is built using the received AddRequest.
      * 
      * @param addRequest the request to execute
      * @exception LdapException on failures to add the entry
      */
     void add( AddRequest addRequest ) throws LdapException;
 
 
     /**
      * Adds an entry into the DirectoryService associated with this CoreSession.
      * The entry is built using the received AddRequest.
      * 
      * @param addRequest the request to execute
      * @param log a flag set if the added entry should be stored in the changeLog
      * @exception LdapException on failures to add the entry
      */
     void add( AddRequest addRequest, LogChange log ) throws LdapException;
 
 
     /**
      * Checks to see if an attribute in an entry contains a value.
      *
      * @param dn the distinguished name of the entry to check
      * @param oid the OID of the attribute to check for the value
      * @param value the value to check for
      * @return <tt>true</tt> if the value exists in the entry
      * @throws LdapException if there are failures while comparing
      */
     boolean compare( Dn dn, String oid, Object value ) throws LdapException;
 
 
     /**
      * Checks to see if an attribute in an entry contains a value.
      * The flag is used to tell the server to ignore the referrals and manipulate
      * them as if they were normal entries.
      *
      * @param dn the distinguished name of the entry to check
      * @param oid the OID of the attribute to check for the value
      * @param value the value to check for
      * @param ignoreReferral a flag to tell the server to ignore referrals
      * @return <tt>true</tt> if the value exists in the entry
      * @throws LdapException if there are failures while comparing
      */
     boolean compare( Dn dn, String oid, Object value, boolean ignoreReferral ) throws LdapException;
 
 
     /**
      * Checks to see if an attribute in an entry contains a value.
      *
      * @param compareRequest the received request
      * @return <tt>true</tt> if the value exists in the entry
      * @throws LdapException if there are failures while comparing
      */
     boolean compare( CompareRequest compareRequest ) throws LdapException;
 
 
     /**
      * Deletes an entry in the server.
      *
      * @param dn the distinguished name of the entry to delete
      * @throws LdapException if there are failures while deleting the entry
      */
     void delete( Dn dn ) throws LdapException;
 
 
     /**
      * Deletes an entry in the server.
      *
      * @param dn the distinguished name of the entry to delete
      * @param log a flag set if the added entry should be stored in the changeLog
      * @throws LdapException if there are failures while deleting the entry
      */
     void delete( Dn dn, LogChange log ) throws LdapException;
 
 
     /**
      * Deletes an entry in the server.
      *
      * @param deleteRequest the delete request containing all the informations 
      * necessary to delete the entry
      * @throws LdapException if there are failures while deleting the entry
      */
     void delete( DeleteRequest deleteRequest ) throws LdapException;
 
 
     /**
      * Deletes an entry in the server. The operation can be logged if requested
      *
      * @param deleteRequest the delete request containing all the informations 
      * necessary to delete the entry
      * @param log Tells if we should log the deletion in the ChangeLog interceptor
      * @throws LdapException if there are failures while deleting the entry
      */
     void delete( DeleteRequest deleteRequest, LogChange log ) throws LdapException;
 
 
     /**
      * Deletes an entry in the server.
      * The flag is used to tell the server to ignore the referrals and manipulate
      * them as if they were normal entries.
      *
      * @param dn the distinguished name of the entry to delete
      * @param ignoreReferral a flag to tell the server to ignore referrals
      * @throws LdapException if there are failures while deleting the entry
      */
     void delete( Dn dn, boolean ignoreReferral ) throws LdapException;
 
 
     /**
      * Deletes an entry in the server.
      * The flag is used to tell the server to ignore the referrals and manipulate
      * them as if they were normal entries.
      *
      * @param dn the distinguished name of the entry to delete
      * @param ignoreReferral a flag to tell the server to ignore referrals
      * @param log a flag set if the added entry should be stored in the changeLog
      * @throws LdapException if there are failures while deleting the entry
      */
     void delete( Dn dn, boolean ignoreReferral, LogChange log ) throws LdapException;
 
 
     /**
      * Checks to see if an entry exists.
      * 
      * @param dn The Dn for the entry  to find
      * @return <tt>true</tt> if the entry exists
      * @throws LdapException If we weren't able to fetch the entry
      */
     boolean exists( String dn ) throws LdapException;
 
 
     /**
      * Checks to see if an entry exists.
      *  
      * @param dn The Dn for the entry  to find
      * @return <tt>true</tt> if the entry exists
      * @throws LdapException If we weren't able to fetch the entry
      */
     boolean exists( Dn dn ) throws LdapException;
 
 
     /**
      * Looks up an entry in the server returning all attributes: both user and
      * operational attributes.
      *
      * @param dn the name of the entry to lookup
      * @param atIds The list of attributes to return
      * @return The found Entry
      * @throws LdapException if there are failures while looking up the entry
      */
     Entry lookup( Dn dn, String... atIds ) throws LdapException;
 
 
     /**
      * Looks up an entry in the server returning all attributes: both user and
      * operational attributes.
      *
      * @param dn the name of the entry to lookup
      * @param controls the Controls to use 
      * @param atIds The list of attributes to return
      * @return The found Entry
      * @throws LdapException if there are failures while looking up the entry
      */
     Entry lookup( Dn dn, Control[] controls, String... atIds ) throws LdapException;
 
 
     /**
      * Modifies an entry within the server by applying a list of modifications 
      * to the entry.
      *
      * @param dn the distinguished name of the entry to modify
      * @param mods the list of modifications to apply
      * @throws LdapException if there are failures while modifying the entry
      */
     void modify( Dn dn, List<Modification> mods ) throws LdapException;
 
 
     /**
      * Modifies an entry within the server by applying a list of modifications 
      * to the entry.
      *
      * @param dn the distinguished name of the entry to modify
      * @param mods the list of modifications to apply
      * @throws LdapException if there are failures while modifying the entry
      */
     void modify( Dn dn, Modification... mods ) throws LdapException;
 
 
     /**
      * Modifies an entry within the server by applying a list of modifications 
      * to the entry.
      *
      * @param dn the distinguished name of the entry to modify
      * @param mods the list of modifications to apply
      * @param log a flag set if the added entry should be stored in the changeLog
      * @throws LdapException if there are failures while modifying the entry
      */
     void modify( Dn dn, List<Modification> mods, LogChange log ) throws LdapException;
 
 
     /**
      * Modifies an entry within the server by applying a list of modifications 
      * to the entry.
      * The flag is used to tell the server to ignore the referrals and manipulate
      * them as if they were normal entries.
      *
      * @param dn the distinguished name of the entry to modify
      * @param ignoreReferral a flag to tell the server to ignore referrals
      * @param mods the list of modifications to apply
      * @throws LdapException if there are failures while modifying the entry
      */
     void modify( Dn dn, List<Modification> mods, boolean ignoreReferral ) throws LdapException;
 
 
     /**
      * Modifies an entry within the server by applying a list of modifications 
      * to the entry.
      * The flag is used to tell the server to ignore the referrals and manipulate
      * them as if they were normal entries.
      *
      * @param dn the distinguished name of the entry to modify
      * @param ignoreReferral a flag to tell the server to ignore referrals
      * @param mods the list of modifications to apply
      * @param log a flag set if the added entry should be stored in the changeLog
      * @throws LdapException if there are failures while modifying the entry
      */
     void modify( Dn dn, List<Modification> mods, boolean ignoreReferral, LogChange log ) throws LdapException;
 
 
     void modify( ModifyRequest modifyRequest ) throws LdapException;
 
 
     void modify( ModifyRequest modifyRequest, LogChange log ) throws LdapException;
 
 
     /**
      * Moves an entry or a branch of entries at a specified distinguished name
      * to a position under a new parent.
      * 
      * @param dn the distinguished name of the entry/branch to move
      * @param newParent the new parent under which the entry/branch is moved
      * @exception LdapException if there are failures while moving the entry/branch
      */
     void move( Dn dn, Dn newParent ) throws LdapException;
 
 
     /**
      * Moves an entry or a branch of entries at a specified distinguished name
      * to a position under a new parent.
      * 
      * @param dn the distinguished name of the entry/branch to move
      * @param newParent the new parent under which the entry/branch is moved
      * @param log a flag set if the added entry should be stored in the changeLog
      * @exception LdapException if there are failures while moving the entry/branch
      */
     void move( Dn dn, Dn newParent, LogChange log ) throws LdapException;
 
 
     /**
      * Moves an entry or a branch of entries at a specified distinguished name
      * to a position under a new parent.
      * 
      * @param dn the distinguished name of the entry/branch to move
      * @param newParent the new parent under which the entry/branch is moved
      * @param ignoreReferral a flag to tell the server to ignore referrals
      * @exception LdapException if there are failures while moving the entry/branch
      */
     void move( Dn dn, Dn newParent, boolean ignoreReferral ) throws Exception;
 
 
     /**
      * Moves an entry or a branch of entries at a specified distinguished name
      * to a position under a new parent.
      * 
      * @param dn the distinguished name of the entry/branch to move
      * @param newParent the new parent under which the entry/branch is moved
      * @param ignoreReferral a flag to tell the server to ignore referrals
      * @param log a flag set if the added entry should be stored in the changeLog
      * @exception LdapException if there are failures while moving the entry/branch
      */
     void move( Dn dn, Dn newParent, boolean ignoreReferral, LogChange log ) throws LdapException;
 
 
     /**
      * Move an entry by changing its superior.
      *
      * @param modifyDnRequest The ModifyDN request
      * @throws LdapException if there are failures while moving the entry/branch
      */
     void move( ModifyDnRequest modifyDnRequest ) throws LdapException;
 
 
     /**
      * Move an entry by changing its superior.
      *
      * @param modifyDnRequest The ModifyDN request
      * @param log a flag set if the added entry should be stored in the changeLog
      * @throws LdapException if there are failures while moving the entry/branch
      */
     void move( ModifyDnRequest modifyDnRequest, LogChange log ) throws LdapException;
 
 
     /**
      * Moves and renames (the relative distinguished name of) an entry (or a 
      * branch if the entry has children) at a specified distinguished name to 
      * a position under a new parent.
      * 
      * @param dn the distinguished name of the entry/branch to move
      * @param newParent the new parent under which the entry/branch is moved
      * @param newRdn the new relative distinguished name of the entry at the 
      * root of the branch
      * @param deleteOldRdn If the old Rdn must be deleted
      * @exception LdapException if there are failures while moving and renaming the entry
      * or branch
      */
     void moveAndRename( Dn dn, Dn newParent, Rdn newRdn, boolean deleteOldRdn ) throws LdapException;
 
 
     /**
      * Moves and renames (the relative distinguished name of) an entry (or a 
      * branch if the entry has children) at a specified distinguished name to 
      * a position under a new parent.
      * 
      * @param dn the distinguished name of the entry/branch to move
      * @param newParent the new parent under which the entry/branch is moved
      * @param newRdn the new relative distinguished name of the entry at the 
      * root of the branch
      * @param deleteOldRdn If the old Rdn must be deleted
      * @param log a flag set if the added entry should be stored in the changeLog
      * @exception LdapException if there are failures while moving and renaming the entry
      * or branch
      */
     void moveAndRename( Dn dn, Dn newParent, Rdn newRdn, boolean deleteOldRdn, LogChange log ) throws LdapException;
 
 
     /**
      * Moves and renames (the relative distinguished name of) an entry (or a 
      * branch if the entry has children) at a specified distinguished name to 
      * a position under a new parent.
      * 
      * @param dn the distinguished name of the entry/branch to move
      * @param newParent the new parent under which the entry/branch is moved
      * @param newRdn the new relative distinguished name of the entry at the 
      * root of the branch
      * @param deleteOldRdn If the old Rdn must be deleted
      * @param ignoreReferral  a flag to tell the server to ignore referrals
      * @exception LdapException if there are failures while moving and renaming the entry
      * or branch
      */
     void moveAndRename( Dn dn, Dn newParent, Rdn newRdn, boolean deleteOldRdn, boolean ignoreReferral )
         throws LdapException;
 
 
     /**
      * Moves and renames (the relative distinguished name of) an entry (or a 
      * branch if the entry has children) at a specified distinguished name to 
      * a position under a new parent.
      * 
      * @param dn the distinguished name of the entry/branch to move
      * @param newParent the new parent under which the entry/branch is moved
      * @param newRdn the new relative distinguished name of the entry at the 
      * root of the branch
      * @param deleteOldRdn If the old Rdn must be deleted
      * @param ignoreReferral  a flag to tell the server to ignore referrals
      * @param log a flag set if the added entry should be stored in the changeLog
      * @exception LdapException if there are failures while moving and renaming the entry
      * or branch
      */
     void moveAndRename( Dn dn, Dn newParent, Rdn newRdn, boolean deleteOldRdn, boolean ignoreReferral, LogChange log )
         throws LdapException;
 
 
     /**
      * Move and rename an entry. We change the Rdn and the superior.
      *
      * @param modifyDnRequest The move and rename request
      * @throws LdapException if there are failures while moving and renaming the entry
      * or branch
      */
     void moveAndRename( ModifyDnRequest modifyDnRequest ) throws LdapException;
 
 
     /**
      * Move and rename an entry. We change the Rdn and the superior.
      *
      * @param modifyDnRequest The move and rename request
      * @param log a flag set if the added entry should be stored in the changeLog
      * @throws LdapException if there are failures while moving and renaming the entry
      * or branch
      */
     void moveAndRename( ModifyDnRequest modifyDnRequest, LogChange log ) throws LdapException;
 
 
     /**
      * Renames an entry by changing it's relative distinguished name.  This 
      * has the side effect of changing the distinguished name of all entries
      * directly or indirectly subordinate to the named entry if it has 
      * descendants.
      *
      * @param dn the distinguished name of the entry to rename
      * @param newRdn the new relative distinguished name for the entry
      * @param deleteOldRdn whether or not the old value for the relative 
      * distinguished name is to be deleted from the entry
      * @throws LdapException if there are failures while renaming the entry
      */
     void rename( Dn dn, Rdn newRdn, boolean deleteOldRdn ) throws LdapException;
 
 
     /**
      * Renames an entry by changing it's relative distinguished name.  This 
      * has the side effect of changing the distinguished name of all entries
      * directly or indirectly subordinate to the named entry if it has 
      * descendants.
      *
      * @param dn the distinguished name of the entry to rename
      * @param newRdn the new relative distinguished name for the entry
      * @param deleteOldRdn whether or not the old value for the relative 
      * distinguished name is to be deleted from the entry
      * @param log a flag set if the added entry should be stored in the changeLog
      * @throws LdapException if there are failures while renaming the entry
      */
     void rename( Dn dn, Rdn newRdn, boolean deleteOldRdn, LogChange log ) throws LdapException;
 
 
     /**
      * Renames an entry by changing it's relative distinguished name.  This 
      * has the side effect of changing the distinguished name of all entries
      * directly or indirectly subordinate to the named entry if it has 
      * descendants.
      *
      * @param dn the distinguished name of the entry to rename
      * @param newRdn the new relative distinguished name for the entry
      * @param deleteOldRdn whether or not the old value for the relative 
      * distinguished name is to be deleted from the entry
      * @param ignoreReferral a flag to tell the server to ignore referrals
      * @throws LdapException if there are failures while renaming the entry
      */
     void rename( Dn dn, Rdn newRdn, boolean deleteOldRdn, boolean ignoreReferral ) throws LdapException;
 
 
     /**
      * Renames an entry by changing it's relative distinguished name.  This 
      * has the side effect of changing the distinguished name of all entries
      * directly or indirectly subordinate to the named entry if it has 
      * descendants.
      *
      * @param dn the distinguished name of the entry to rename
      * @param newRdn the new relative distinguished name for the entry
      * @param deleteOldRdn whether or not the old value for the relative 
      * distinguished name is to be deleted from the entry
      * @param ignoreReferral a flag to tell the server to ignore referrals
      * @param log a flag set if the added entry should be stored in the changeLog
      * @throws LdapException if there are failures while renaming the entry
      */
     void rename( Dn dn, Rdn newRdn, boolean deleteOldRdn, boolean ignoreReferral, LogChange log ) throws LdapException;
 
 
     /**
      * Rename an entry applying the ModifyDN request 
      *
      * @param modifyDnRequest The requested modification
      * @throws LdapException if there are failures while renaming the entry
      */
     void rename( ModifyDnRequest modifyDnRequest ) throws LdapException;
 
 
     /**
      * Rename an entry applying the ModifyDN request 
      *
      * @param modifyDnRequest The requested modification
      * @param log a flag set if the added entry should be stored in the changeLog
      * @throws LdapException if there are failures while renaming the entry
      */
     void rename( ModifyDnRequest modifyDnRequest, LogChange log ) throws LdapException;
 
 
     /**
      * An optimized search operation using one level search scope which 
      * returns all the children of an entry specified by distinguished name.
      * This is equivalent to a search operation with one level scope using
      * the <code>(objectClass=*)</code> filter.
      *
      * @param dn the distinguished name of the entry to list the children of
      * @param aliasDerefMode the alias dereferencing mode used
      * @param returningAttributes the attributes to return
      * @return A cursor to brows the search results
      * @throws LdapException if there are failures while listing children
      */
     Cursor<Entry> list( Dn dn, AliasDerefMode aliasDerefMode,
         String... returningAttributes ) throws LdapException;
 
 
     /**
      * Searches the directory using a specified filter. The scope is defaulting
      * to 'base'. The alias dereferencing default to 'always'. the returned attributes 
      * defaults to 'all the user attributes)
      *
      * @param dn the distinguished name of the entry to list the children of
      * @param filter the search filter
      * @return A cursor to brows the search results
      * @throws LdapException if there are failures while listing children
      */
     Cursor<Entry> search( Dn dn, String filter ) throws LdapException;
 
 
     /**
      * Searches the directory using a specified filter. The scope is defaulting
      * to 'base'. The alias dereferencing default to 'always'. the returned attributes 
      * defaults to 'all the user attributes)
      *
      * @param dn the distinguished name of the entry to list the children of
      * @param filter the search filter
      * @param ignoreReferrals a flag to tell the server to ignore referrals
      * @return A cursor to brows the search results
      * @throws LdapException if there are failures while listing children
      */
     Cursor<Entry> search( Dn dn, String filter, boolean ignoreReferrals ) throws LdapException;
 
 
     /**
      * Searches the directory using a specified search scope and filter.
      *
      * @param dn the distinguished name of the entry to list the children of
      * @param scope the search scope to apply
      * @param filter the search filter
      * @param aliasDerefMode the alias dereferencing mode used
      * @param returningAttributes the attributes to return
      * @return A cursor to brows the search results
      * @throws LdapException if there are failures while listing children
      */
     Cursor<Entry> search( Dn dn, SearchScope scope, ExprNode filter, AliasDerefMode aliasDerefMode,
         String... returningAttributes ) throws LdapException;
 
 
     Cursor<Entry> search( SearchRequest searchRequest ) throws LdapException;
 
 
     /**
      * Unbind from the current LdapSession.
      * 
      * @throws LdapException If the operation failed
      */
     void unbind() throws LdapException;
 
 
     /**
      * Unbind from the current LdapSession.
      * 
      * @param unbindRequest The Unbind requst, potentially containing some controls
      * @throws LdapException If the operation failed
      */
     void unbind( UnbindRequest unbindRequest ) throws LdapException;
     
     
     /**
      * @return true if the password must be changed
      */
     boolean isPwdMustChange();
 
     
     /**
      * Sets if the passwords must be changed. If set to true then this session is
      * only allowed to perform modify password, bind, unbind, abandon and StartTLS
      * extended operation only as specified in section #8.1.2.2 of the password policy
      * <a href="http://tools.ietf.org/id/draft-behera-ldap-password-policy-10.txt">spec</a> 
      * 
      * @param pwdMustChange If the password must change or not
      */
     void setPwdMustChange( boolean pwdMustChange );
     
     
     /**
      * @return <tt>true</tt> if a session transaction has been started
      */
     boolean hasSessionTransaction();
     
     
     /**
      * Set the flag indicating we have received the startTransaction extended operation
      * 
      * @return The transaction ID
      */
     long beginSessionTransaction();
     
     
     /**
      * Set the flag indicating we have received the sendTransaction extended operation
      * 
      * @param commit If we have to commit or rollback the transaction
      * @throws IOException If one of the transaction cannot be closed
      */
     void endSessionTransaction( boolean commit ) throws IOException;
     
     
     /**
      * Retrieve a transaction associated with a partition, if we have one.
      * 
      * @return The found transaction, or null if no transaction  has been started
      * @param partition The Partition 
      */
     PartitionTxn getTransaction( Partition partition );
     
     
     /**
      * Add a transaction associated with a partition if it's not already stored in teh 
      * transaction map.
      * 
      * @param partition The Partition which will be associated with the transaction
      * @param transaction The transaction to set
      */
     void addTransaction( Partition partition, PartitionTxn transaction );
 }