Package 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 singleLDAPRequest
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. TheReadOnlyLDAPRequest.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 theExtendedRequest
andSASLBindRequest
subclasses are actually intended to be extended by third-party code.- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
LDAPRequest(Control[] controls)
Creates a new LDAP request with the provided set of controls.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method 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 interfaceReadOnlyLDAPRequest
- 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 interfaceReadOnlyLDAPRequest
- 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 interfaceReadOnlyLDAPRequest
- Returns:
true
if this request contains at least one control, orfalse
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 interfaceReadOnlyLDAPRequest
- Parameters:
oid
- The object identifier for which to make the determination. It must not benull
.- Returns:
true
if this request contains at least one control with the specified OID, orfalse
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 interfaceReadOnlyLDAPRequest
- Parameters:
oid
- The object identifier for which to retrieve the corresponding control. It must not benull
.- 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 interfaceReadOnlyLDAPRequest
- Parameters:
connection
- The connection to use in order to retrieve the default value, if appropriate. It may benull
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 interfaceReadOnlyLDAPRequest
- Parameters:
connection
- The connection whose connection options may be used in the course of making the determination. It must not benull
.- Returns:
true
if any referrals encountered during processing should be automatically followed, orfalse
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 benull
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 interfaceReadOnlyLDAPRequest
- Parameters:
connection
- The connection that may be used in the course of obtaining the appropriate referral connector. It must not benull
.- 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 benull
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 benull
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 interfaceReadOnlyLDAPRequest
- Overrides:
toString
in classjava.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 interfaceReadOnlyLDAPRequest
- Parameters:
buffer
- The buffer to which to append a string representation of this request.
-
-