com.unboundid.ldap.sdk

Class LDAPRequest

java.lang.Object

com.unboundid.ldap.sdk.LDAPRequest

All Implemented Interfaces:

ReadOnlyLDAPRequest, java.io.Serializable

Direct Known Subclasses:

BindRequest, ExtendedRequest, UpdatableLDAPRequest

@Extensible
 @ThreadSafety(level=NOT_THREADSAFE)
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 ReadOnlyLDAPRequest.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

Constructors

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

Method Summary

Modifier and Type	Method and Description
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.
ReferralConnector	getReferralConnector(LDAPConnection connection) Retrieves the referral connector that should be used when establishing a connection for the purpose of automatically following a referral.
protected ReferralConnector	getReferralConnectorInternal() Retrieves the referral connector that has been set for this request.
protected int	getReferralDepth() Retrieves the current depth to use when following referrals.
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	setReferralConnector(ReferralConnector referralConnector) Sets the referral connector that should be used to establish connections for the purpose of following any referrals encountered when processing this request.
protected void	setReferralDepth(int referralDepth) Sets the current depth to use when following referrals.
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(@Nullable
                      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

@NotNull
public final Control[] getControls()

Retrieves the set of controls for this request. The caller must not alter this set of controls.

Specified by:

getControls in interface ReadOnlyLDAPRequest

Returns:

The set of controls for this request.

getControlList

@NotNull
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(@NotNull
                                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

@Nullable
public final Control getControl(@NotNull
                                          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(@Nullable
                                           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(@NotNull
                                     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(@Nullable
                                     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.

getReferralDepth

protected int getReferralDepth()

Retrieves the current depth to use when following referrals.

Returns:

The current depth to use when following referrals.

setReferralDepth

protected void setReferralDepth(int referralDepth)

Sets the current depth to use when following referrals.

Parameters:

referralDepth - The current depth to use when following referrals.

getReferralConnector

@NotNull
public final ReferralConnector getReferralConnector(@NotNull
                                                             LDAPConnection connection)

Retrieves the referral connector that should be used when establishing a connection for the purpose of automatically following a referral.

Specified by:

getReferralConnector in interface ReadOnlyLDAPRequest

Parameters:

connection - The connection that may be used in the course of obtaining the appropriate referral connector. It must not be null.

Returns:

The referral connector that should be used for the purpose of automatically following a referral. It will not be null.

getReferralConnectorInternal

@Nullable
protected final ReferralConnector getReferralConnectorInternal()

Retrieves the referral connector that has been set for this request.

Returns:

The referral connector that has been set for this request, or null if no referral connector has been set for this request and the connection's default referral connector will be used if necessary.

setReferralConnector

public final void setReferralConnector(@Nullable
                                       ReferralConnector referralConnector)

Sets the referral connector that should be used to establish connections for the purpose of following any referrals encountered when processing this request.

Parameters:

referralConnector - The referral connector that should be used to establish connections for the purpose of following any referral encountered when processing this request. It may be null to use the default referral handler for the connection on which the referral was received.

getIntermediateResponseListener

@Nullable
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(@Nullable
                                                  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
 @NotNull
protected abstract LDAPResult process(@NotNull
                                                                 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

@NotNull
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

@NotNull
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(@NotNull
                              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.