Package com.unboundid.ldap.sdk

Class LDAPRequest

java.lang.Object
com.unboundid.ldap.sdk.LDAPRequest
All Implemented Interfaces:
ReadOnlyLDAPRequest, Serializable
Direct Known Subclasses:
BindRequest, ExtendedRequest, UpdatableLDAPRequest
@Extensible @ThreadSafety(level=NOT_THREADSAFE) public abstract class LDAPRequest extends 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:

  • Constructor Details

    • 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 Details

    • 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 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 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 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 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 String toString()
      Retrieves a string representation of this request.
      Specified by:
      toString in interface ReadOnlyLDAPRequest
      Overrides:
      toString in class Object
      Returns:
      A string representation of this request.

    • toString

      public abstract void toString(@NotNull 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.