Package com.isode.dsapi

Class DirectorySession.PendingOperation

java.lang.Object
com.isode.dsapi.DirectorySession.PendingOperation
Enclosing class:
DirectorySession
public static class DirectorySession.PendingOperation extends 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:

  • Constructor Details

    • PendingOperation

      protected PendingOperation(DirectorySession ds, int opID, DN dn, 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, 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, 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 Details

    • toString

      public String toString()
      Return a user friendly String representation of this object.
      Overrides:
      toString in class 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 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, NullPointerException, NoSuchOperationException, 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
      NullPointerException
      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