com.unboundid.ldap.sdk
Class LDAPRequest

java.lang.Object
  extended by com.unboundid.ldap.sdk.LDAPRequest
All Implemented Interfaces:
ReadOnlyLDAPRequest, java.io.Serializable
Direct Known Subclasses:
BindRequest, ExtendedRequest, UpdatableLDAPRequest

public abstract class LDAPRequest
extends java.lang.Object
implements ReadOnlyLDAPRequest

This class provides a framework that should be extended by all types of LDAP requests. It provides methods for interacting with the set of controls to include as part of the request and configuring a response timeout, which is the maximum length of time that the SDK should wait for a response to the request before returning an error back to the caller.

LDAPRequest objects are not immutable and should not be considered threadsafe. A single LDAPRequest object instance should not be used concurrently by multiple threads, but instead each thread wishing to process a request should have its own instance of that request. The duplicate() method may be used to create an exact copy of a request suitable for processing by a separate thread.

Note that even though this class is marked with the @Extensible annotation type, it should not be directly subclassed by third-party code. Only the ExtendedRequest and SASLBindRequest subclasses are actually intended to be extended by third-party code.

See Also:
Serialized Form

Constructor Summary
protected LDAPRequest(Control[] controls)
          Creates a new LDAP request with the provided set of controls.
 
Method Summary
 boolean followReferrals(LDAPConnection connection)
          Indicates whether to automatically follow any referrals encountered while processing this request.
 Control getControl(java.lang.String oid)
          Retrieves the control with the specified OID from this request.
 java.util.List<Control> getControlList()
          Retrieves a list containing the set of controls for this request.
 Control[] getControls()
          Retrieves the set of controls for this request.
 IntermediateResponseListener getIntermediateResponseListener()
          Retrieves the intermediate response listener for this request, if any.
abstract  int getLastMessageID()
          Retrieves the message ID for the last LDAP message sent using this request.
abstract  OperationType getOperationType()
          Retrieves the type of operation that is represented by this request.
 long getResponseTimeoutMillis(LDAPConnection connection)
          Retrieves the maximum length of time in milliseconds that processing on this operation should be allowed to block while waiting for a response from the server.
 boolean hasControl()
          Indicates whether this request contains at least one control.
 boolean hasControl(java.lang.String oid)
          Indicates whether this request contains at least one control with the specified OID.
protected abstract  LDAPResult process(LDAPConnection connection, int depth)
          Processes this operation using the provided connection and returns the result.
 void setFollowReferrals(java.lang.Boolean followReferrals)
          Specifies whether to automatically follow any referrals encountered while processing this request.
 void setIntermediateResponseListener(IntermediateResponseListener listener)
          Sets the intermediate response listener for this request.
 void setResponseTimeoutMillis(long responseTimeout)
          Specifies the maximum length of time in milliseconds that processing on this operation should be allowed to block while waiting for a response from the server.
 java.lang.String toString()
          Retrieves a string representation of this request.
abstract  void toString(java.lang.StringBuilder buffer)
          Appends a string representation of this request to the provided buffer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.unboundid.ldap.sdk.ReadOnlyLDAPRequest
duplicate, duplicate, toCode
 

Constructor Detail

LDAPRequest

protected LDAPRequest(Control[] controls)
Creates a new LDAP request with the provided set of controls.

Parameters:
controls - The set of controls to include in this LDAP request.
Method Detail

getControls

public final Control[] getControls()
Retrieves the set of controls for this request. The caller must not alter this set of controls.

Returns:
The set of controls for this request.

getControlList

public final java.util.List<Control> getControlList()
Retrieves a list containing the set of controls for this request.

Specified by:
getControlList in interface ReadOnlyLDAPRequest
Returns:
A list containing the set of controls for this request.

hasControl

public final boolean hasControl()
Indicates whether this request contains at least one control.

Specified by:
hasControl in interface ReadOnlyLDAPRequest
Returns:
true if this request contains at least one control, or false if not.

hasControl

public final boolean hasControl(java.lang.String oid)
Indicates whether this request contains at least one control with the specified OID.

Specified by:
hasControl in interface ReadOnlyLDAPRequest
Parameters:
oid - The object identifier for which to make the determination. It must not be null.
Returns:
true if this request contains at least one control with the specified OID, or false if not.

getControl

public final Control getControl(java.lang.String oid)
Retrieves the control with the specified OID from this request. If this request has multiple controls with the specified OID, then the first will be returned.

Specified by:
getControl in interface ReadOnlyLDAPRequest
Parameters:
oid - The object identifier for which to retrieve the corresponding control. It must not be null.
Returns:
The first control found with the specified OID, or null if no control with that OID is included in this request.

getResponseTimeoutMillis

public final long getResponseTimeoutMillis(LDAPConnection connection)
Retrieves the maximum length of time in milliseconds that processing on this operation should be allowed to block while waiting for a response from the server.

Specified by:
getResponseTimeoutMillis in interface ReadOnlyLDAPRequest
Parameters:
connection - The connection to use in order to retrieve the default value, if appropriate. It may be null to retrieve the request-specific timeout (which may be negative if no response-specific timeout has been set).
Returns:
The maximum length of time in milliseconds that processing on this operation should be allowed to block while waiting for a response from the server, or zero if no timeout should be enforced.

setResponseTimeoutMillis

public final void setResponseTimeoutMillis(long responseTimeout)
Specifies the maximum length of time in milliseconds that processing on this operation should be allowed to block while waiting for a response from the server. A value of zero indicates that no timeout should be enforced. A value that is less than zero indicates that the default response timeout for the underlying connection should be used.

Parameters:
responseTimeout - The maximum length of time in milliseconds that processing on this operation should be allowed to block while waiting for a response from the server.

followReferrals

public final boolean followReferrals(LDAPConnection connection)
Indicates whether to automatically follow any referrals encountered while processing this request. If a value has been set for this request, then it will be returned. Otherwise, the default from the connection options for the provided connection will be used.

Specified by:
followReferrals in interface ReadOnlyLDAPRequest
Parameters:
connection - The connection whose connection options may be used in the course of making the determination. It must not be null.
Returns:
true if any referrals encountered during processing should be automatically followed, or false if not.

setFollowReferrals

public final void setFollowReferrals(java.lang.Boolean followReferrals)
Specifies whether to automatically follow any referrals encountered while processing this request. This may be used to override the default behavior defined in the connection options for the connection used to process the request.

Parameters:
followReferrals - Indicates whether to automatically follow any referrals encountered while processing this request. It may be null to indicate that the determination should be based on the connection options for the connection used to process the request.

getIntermediateResponseListener

public final IntermediateResponseListener getIntermediateResponseListener()
Retrieves the intermediate response listener for this request, if any.

Returns:
The intermediate response listener for this request, or null if there is none.

setIntermediateResponseListener

public final void setIntermediateResponseListener(IntermediateResponseListener listener)
Sets the intermediate response listener for this request.

Parameters:
listener - The intermediate response listener for this request. It may be null to clear any existing listener.

process

@InternalUseOnly
protected abstract LDAPResult process(LDAPConnection connection,
                                                      int depth)
                               throws LDAPException
Processes this operation using the provided connection and returns the result.

Parameters:
connection - The connection to use to process the request.
depth - The current referral depth for this request. It should always be one for the initial request, and should only be incremented when following referrals.
Returns:
The result of processing this operation.
Throws:
LDAPException - If a problem occurs while processing the request.

getLastMessageID

public abstract int getLastMessageID()
Retrieves the message ID for the last LDAP message sent using this request.

Returns:
The message ID for the last LDAP message sent using this request, or -1 if it no LDAP messages have yet been sent using this request.

getOperationType

public abstract OperationType getOperationType()
Retrieves the type of operation that is represented by this request.

Returns:
The type of operation that is represented by this request.

toString

public java.lang.String toString()
Retrieves a string representation of this request.

Specified by:
toString in interface ReadOnlyLDAPRequest
Overrides:
toString in class java.lang.Object
Returns:
A string representation of this request.

toString

public abstract void toString(java.lang.StringBuilder buffer)
Appends a string representation of this request to the provided buffer.

Specified by:
toString in interface ReadOnlyLDAPRequest
Parameters:
buffer - The buffer to which to append a string representation of this request.