com.unboundid.ldap.sdk

Class AsyncRequestID

java.lang.Object

com.unboundid.ldap.sdk.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

Modifier and Type	Method and 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.