Class AsyncRequestID

  • All Implemented Interfaces:
    java.io.Serializable, java.util.concurrent.Future<LDAPResult>

    @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class AsyncRequestID
    extends java.lang.Object
    implements java.io.Serializable, java.util.concurrent.Future<LDAPResult>
    This class defines an object that provides information about a request that was initiated asynchronously. It may be used to abandon or cancel the associated request. This class also implements the java.util.concurrent.Future interface, so it may be used in that manner.

    Example

    The following example initiates an asynchronous modify operation and then attempts to abandon it:
     Modification mod = new Modification(ModificationType.REPLACE,
          "description", "This is the new description.");
     ModifyRequest modifyRequest =
          new ModifyRequest("dc=example,dc=com", mod);
    
     AsyncRequestID asyncRequestID =
          connection.asyncModify(modifyRequest, myAsyncResultListener);
    
     // Assume that we've waited a reasonable amount of time but the modify
     // hasn't completed yet so we'll try to abandon it.
    
     connection.abandon(asyncRequestID);
     
    See Also:
    Serialized Form
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean cancel​(boolean mayInterruptIfRunning)
      Attempts to cancel the associated asynchronous operation operation.
      boolean equals​(java.lang.Object o)
      Indicates whether the provided object is equal to this async request ID.
      LDAPResult get()
      Attempts to get the result for the associated operation, waiting if necessary for it to complete.
      LDAPResult get​(long timeout, java.util.concurrent.TimeUnit timeUnit)
      Attempts to get the result for the associated operation, waiting if necessary for up to the specified length of time for the operation to complete.
      int getMessageID()
      Retrieves the message ID for the associated request.
      int hashCode()
      Retrieves a hash code for this async request ID.
      boolean isCancelled()
      Indicates whether an attempt has been made to cancel the associated operation before it completed.
      boolean isDone()
      Indicates whether the associated operation has completed, regardless of whether it completed normally, completed with an error, or was canceled before starting.
      java.lang.String toString()
      Retrieves a string representation of this async request ID.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Method Detail

      • getMessageID

        public int getMessageID()
        Retrieves the message ID for the associated request.
        Returns:
        The message ID for the associated request.
      • cancel

        public boolean cancel​(boolean mayInterruptIfRunning)
        Attempts to cancel the associated asynchronous operation operation. This will cause an abandon request to be sent to the server for the associated request, but because there is no response to an abandon operation then there is no way that we can determine whether the operation was actually abandoned.
        Specified by:
        cancel in interface java.util.concurrent.Future<LDAPResult>
        Parameters:
        mayInterruptIfRunning - Indicates whether to interrupt the thread running the associated task. This will be ignored.
        Returns:
        true if an abandon request was sent to cancel the associated operation, or false if it was not possible to send an abandon request because the operation has already completed, because an abandon request has already been sent, or because an error occurred while trying to send the cancel request.
      • isCancelled

        public boolean isCancelled()
        Indicates whether an attempt has been made to cancel the associated operation before it completed.
        Specified by:
        isCancelled in interface java.util.concurrent.Future<LDAPResult>
        Returns:
        true if an attempt was made to cancel the operation, or false if no cancel attempt was made, or if the operation completed before it could be canceled.
      • isDone

        public boolean isDone()
        Indicates whether the associated operation has completed, regardless of whether it completed normally, completed with an error, or was canceled before starting.
        Specified by:
        isDone in interface java.util.concurrent.Future<LDAPResult>
        Returns:
        true if the associated operation has completed, or if an attempt has been made to cancel it, or false if the operation has not yet completed and no cancel attempt has been made.
      • get

        @NotNull
        public LDAPResult get()
                       throws java.lang.InterruptedException
        Attempts to get the result for the associated operation, waiting if necessary for it to complete. Note that this method will differ from the behavior defined in the java.util.concurrent.Future API in that it will not wait forever. Rather, it will wait for no more than the length of time specified as the maximum response time defined in the connection options for the connection used to send the asynchronous request. This is necessary because the operation may have been abandoned or otherwise interrupted, or the associated connection may have become invalidated, in a way that the LDAP SDK cannot detect.
        Specified by:
        get in interface java.util.concurrent.Future<LDAPResult>
        Returns:
        The result for the associated operation. If the operation has been canceled, or if no result has been received within the response timeout period, then a generated response will be returned.
        Throws:
        java.lang.InterruptedException - If the thread calling this method was interrupted before a result was received.
      • get

        @NotNull
        public LDAPResult get​(long timeout,
                              @NotNull
                              java.util.concurrent.TimeUnit timeUnit)
                       throws java.lang.InterruptedException,
                              java.util.concurrent.TimeoutException
        Attempts to get the result for the associated operation, waiting if necessary for up to the specified length of time for the operation to complete.
        Specified by:
        get in interface java.util.concurrent.Future<LDAPResult>
        Parameters:
        timeout - The maximum length of time to wait for the response.
        timeUnit - The time unit for the provided timeout value.
        Returns:
        The result for the associated operation. If the operation has been canceled, then a generated response will be returned.
        Throws:
        java.lang.InterruptedException - If the thread calling this method was interrupted before a result was received.
        java.util.concurrent.TimeoutException - If a timeout was encountered before the result could be obtained.
      • hashCode

        public int hashCode()
        Retrieves a hash code for this async request ID.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        A hash code for this async request ID.
      • equals

        public boolean equals​(@Nullable
                              java.lang.Object o)
        Indicates whether the provided object is equal to this async request ID.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - The object for which to make the determination.
        Returns:
        true if the provided object is equal to this async request ID, or false if not.
      • toString

        @NotNull
        public java.lang.String toString()
        Retrieves a string representation of this async request ID.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representation of this async request ID.