Package com.isode.dsapi

Class DirectorySession.PendingOperation

  • Enclosing class:
    DirectorySession
    public static class DirectorySession.PendingOperation
extends java.lang.Object
    A PendingOperation object keeps track of an asynchronous directory operation.

    A successful attempt to initiate an asynchronous directory operation will return a PendingOperation object. Callers may subsequently use poll() to check whether the operation has been completed, or cancel() to cancel it.

    See Also:
    DirectorySession.readAsync(DN, Selection, CommonArgs)

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void cancel()
      Cancel an outstanding asynchronous operation.
      DirectorySession getDirectorySession()
      Return the DirectorySession for which this PendingObject was created.
      DN getDN()
      Return the DN (if any) associated with this operation.
      java.lang.String getOperation()
      Return the operation name that is associated with this operation.
      int getOpID()
      Return the operation ID associated with this operation.
      Indication poll()
      Check for completion of an asynchronous operation.
      java.lang.String toString()
      Return a user friendly String representation of this object.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • PendingOperation

        protected PendingOperation​(DirectorySession ds,
                           int opID,
                           DN dn,
                           java.lang.String operation)
        Construct a new PendingOperation object. This method is used by routines in the DirectorySession class.
        Parameters:
        ds - the DirectorySession associated with this PendingObject
        opID - the operation ID, as returned from the JNI layer
        dn - the DN of the entry relating to this operation (or null if none is applicable)
        operation - a String containing the name of the operation (for UI purposes).

      • PendingOperation

        protected PendingOperation​(DirectorySession ds,
                           DN dn,
                           java.lang.String operation,
                           IndicationException dsapiException)
        Construct a new PendingOperation object. This method is used by routines in the DirectorySession class.

        This constructor is used when an attempt to initiate an asynchronous operation is bound to fail with some kind of IndicationException, but that exception should not be reported unless and until the caller polls to see the result of the operation.

        Parameters:
        ds - the DirectorySession associated with this PendingObject.
        dn - the DN of the entry relating to this operation (or null if none is applicable)
        operation - a String containing the name of the operation (for UI purposes).
        dsapiException - a IndicationException which is to be reported when the caller polls this PendingOperation.
        Since:
        14.6

      • PendingOperation

        protected PendingOperation​(DirectorySession ds,
                           int opID,
                           java.lang.String operation)
        Construct a new PendingOperation object. This method is used by routines in the DirectorySession class.
        Parameters:
        ds - the DirectorySession associated with this PendingObject
        opID - the operation ID, as returned from the JNI layer
        operation - a String containing the name of the operation (for UI purposes)

    • Method Detail

      • toString

        public java.lang.String toString()
        Return a user friendly String representation of this object.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String representation of the object

      • getOpID

        public int getOpID()
        Return the operation ID associated with this operation.
        Returns:
        the operation ID, as used by the native DSAPI layer

      • getDN

        public DN getDN()
        Return the DN (if any) associated with this operation.
        Returns:
        the DN associated with this operation, or null if no DN is associated with it

      • getOperation

        public java.lang.String getOperation()
        Return the operation name that is associated with this operation.
        Returns:
        the description (e.g. "asynchronous read") of this operation

      • getDirectorySession

        public DirectorySession getDirectorySession()
        Return the DirectorySession for which this PendingObject was created.
        Returns:
        a DirectorySession

      • poll

        public Indication poll()
                throws NativeLibraryException,
                       java.lang.NullPointerException,
                       NoSuchOperationException,
                       java.lang.IllegalArgumentException,
                       DirectoryOperationFailedException,
                       NoSuchEntryException,
                       IndicationException
        Check for completion of an asynchronous operation. For an operation which has not yet completed, null will be returned. For an operation which has completed, an Indication will be returned. Once an Indication has been returned, further calls to this method using the same PendingOperation object will result in a NoSuchOperationException being thrown.
        Returns:
        either an Indication containing the result of the completed operation, or null if the operation has not yet completed.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library
        NoSuchOperationException - if this operation is no longer in progress. This could be because a previous call to poll() has already returned an Indication, or because cancel() was called
        DirectoryOperationFailedException - if the operation was sent to the directory, and the directory returned an "operation failed" status with no extra indication or information
        NoSuchEntryException - if the operation failed with an error indicating that the relevant DN was not found
        IndicationException - if the underlying layer returned an Indication that represents a failure status from the DSA
        java.lang.NullPointerException
        java.lang.IllegalArgumentException

      • cancel

        public void cancel()
        Cancel an outstanding asynchronous operation. This is a way to indicate that the results of the operation are no longer of interest. Calling this method does not guarantee that the directory operation will be aborted.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library