Package com.isode.dsapi

Class DirectorySession

  • All Implemented Interfaces:
    SWIG_DSAPIConstants
    public class DirectorySession
extends java.lang.Object
implements SWIG_DSAPIConstants
    Each DirectorySession object represents a connection to a particular directory.

    To use a DirectorySession object, callers typically use code of the form: 

        DirectorySession sess = new DirectorySession(presaddr);
    .
    .
    sess.bind(bindDN, password, null); // simple bind; no common args
    that is, specify an address when constructing the object (which will validate the address format), and then attempt to bind as a separate operation.

    Note that re-binding is not currently supported; that is, once a successful bind operation has been performed, a subsequent attempt to perform another bind on the same session will result in a NotImplementedException being thrown. This restriction also applies to sessions which have been bound and then unbound.

    With some exceptions that are noted in the documentation, DirectorySession objects may be safely shared between multiple threads. So, for example, several separate threads may use the same DirectorySession to perform reads and writes to a given directory. Note that there is no explicit guarantee, in the case of multiple outstanding operations, as to the ordering of operations.

    In the case that an application wishes to execute a series of discrete directory operations in a single transaction, without risking another thread performing operations that might invalidate the transaction, callers should synchronize on the DirectorySession object. For example: 

       synchronize(session) {
          session.delete(oldDN, null);
          session.rename(newDN, oldDN, null);
   }

    Obviously, such synchronization cannot protect against problems caused by other directory clients which may be accessing the directory.

    Note this class can only be used after a successful call has been made to DSapi.initialize().

    See Also:
    DSapi.initialize()

    • Field Detail

      • SCOPE_BASE

        public static final int SCOPE_BASE
        Used to request a search of just the base object.
        See Also:
        Constant Field Values

      • SCOPE_ONELEVEL

        public static final int SCOPE_ONELEVEL
        Used to request a search of entries immediately beneath the base object.
        See Also:
        Constant Field Values

      • SCOPE_SUBTREE

        public static final int SCOPE_SUBTREE
        Used to request a search of entries in the entire tree below the base object.
        See Also:
        Constant Field Values

      • MATCHALL

        public static final java.lang.String MATCHALL
        Filter string which matches all entries: "(objectclass=*)".
        See Also:
        Constant Field Values

      • BIND_ANONYMOUS

        public static final int BIND_ANONYMOUS
        Bind type: anonymous bind.
        See Also:
        Constant Field Values

      • BIND_SIMPLE

        public static final int BIND_SIMPLE
        Bind type: simple bind
        See Also:
        Constant Field Values

      • BIND_STRONG

        public static final int BIND_STRONG
        Bind type: strong bind.
        See Also:
        Constant Field Values

      • defaultCommonArgs

        public CommonArgs defaultCommonArgs
        Default common arguments for directory operations. In all cases where a CommonArgs is required, this object contains a set of default common arguments which are used in the absence of any user specified argument. For example: 
           DirectorySession ds = new DirectorySession(presAddr);
   .
   .
   // This search will have a size limit of 20, and will be a signed
   // operation. Other common arguments will be as defined in
   // the CommonArgs.setDefaults() method.
   ds.defaultCommonArgs.setSizeLimit(20);
   ds.defaultCommonArgs.setSigned(true);

   Indication ind = ds.search(baseDN,filter,scope,sel, null);

   // This search will have a size limit of 30, with all other arguments
   // default according to CommonArgs.setDefault(). The size limit and
   // signed option previously changed in the session defaultCommonArgs
   // are *not* used because the caller has specified their own set of
   // common arguments.
   CommonArgs myca = new CommonArgs();
   myca.setSizeLimit(30);

   Indication ind = ds.search(baseDN,filter,scope,sel,myca);
        Note that changing this variable changes the default CommonArgs for all users of this DirectorySession. If you wish to make a temporary change to this variable for a series of operations, you can make sure that it does not affect other users of the DirectorySession by surrounding the code with a synchronized block, e.g. 
          synchronized(session) {
     CommonArgs oldCA = session.defaultCommonArgs;
     session.defaultCommonArgs = ...;
     // do directory operations
     session.defaultCommonArgs = oldCA;
  }
        While one thread is executing in such a synchronized block, any other threads which wish to perform operations on the same DirectorySession will be blocked.

      • baseDN

        protected DN baseDN
        Base DN. For use by Isode software only.