Package com.unboundid.ldap.sdk

Class 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 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.
      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.
      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

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

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

      • getReferralConnector

        public final ReferralConnector getReferralConnector​(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.

      • setReferralConnector

        public final 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.
        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.

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