Package org.forgerock.opendj.ldap.messages

Class Requests

java.lang.Object
org.forgerock.opendj.ldap.messages.Requests
public final class Requests extends Object
This class contains various methods for creating and manipulating requests.

All copy constructors of the form copyOfXXXRequest perform deep copies of their request parameter. More specifically, any controls, modifications, and attributes contained within the response will be duplicated.

  • Method Details

    • isPersistentSearch

      public static boolean isPersistentSearch(Request request)
      Returns whether the provided request is a persistent search request.
      Parameters:
      request - The request to test.
      Returns:
      true if the provided request is a persistent search request, false otherwise.

    • isCancel

      public static boolean isCancel(Request request)
      Checks whether the provided request is a Cancel extended request.
      Parameters:
      request - The request to check.
      Returns:
      true if the request is a Cancel request, false otherwise.

    • dnOfRequest

      public static Dn dnOfRequest(Request request)
      Returns the DN of the entry targeted by the provided request, or null if the target entry cannot be determined. This method will return null for most extended operations and SASL bind requests because the target DN cannot be recovered.
      Parameters:
      request - The request whose target entry DN is to be determined.
      Returns:
      The DN of the entry targeted by the provided request, or null if the target entry cannot be determined.

    • shallowCopyOfRequest

      public static <R extends Request> R shallowCopyOfRequest(R request)
      Creates a new request that is a shallow copy of the provided request, except for controls list which is a new list containing the original controls (and not the original list of controls).
      Type Parameters:
      R - The type of the request
      Parameters:
      request - the original request
      Returns:
      the new request

    • copyOfAbandonRequest

      public static AbandonRequest copyOfAbandonRequest(AbandonRequest request)
      Creates a new abandon request that is an exact copy of the provided request.
      Parameters:
      request - The abandon request to be copied.
      Returns:
      The new abandon request.
      Throws:
      NullPointerException - If request was null

    • copyOfAddRequest

      public static AddRequest copyOfAddRequest(AddRequest request)
      Creates a new add request that is an exact copy of the provided request.
      Parameters:
      request - The add request to be copied.
      Returns:
      The new add request.
      Throws:
      NullPointerException - If request was null .

    • copyOfCancelExtendedRequest

      public static CancelExtendedRequest copyOfCancelExtendedRequest(CancelExtendedRequest request)
      Creates a new cancel extended request that is an exact copy of the provided request.
      Parameters:
      request - The cancel extended request to be copied.
      Returns:
      The new cancel extended request.
      Throws:
      NullPointerException - If request was null .

    • copyOfCompareRequest

      public static CompareRequest copyOfCompareRequest(CompareRequest request)
      Creates a new compare request that is an exact copy of the provided request.
      Parameters:
      request - The compare request to be copied.
      Returns:
      The new compare request.
      Throws:
      NullPointerException - If request was null .

    • copyOfDeleteRequest

      public static DeleteRequest copyOfDeleteRequest(DeleteRequest request)
      Creates a new delete request that is an exact copy of the provided request.
      Parameters:
      request - The add request to be copied.
      Returns:
      The new delete request.
      Throws:
      NullPointerException - If request was null.

    • copyOfBindRequest

      public static BindRequest copyOfBindRequest(BindRequest request)
      Creates a new bind request that is an exact copy of the provided request.
      Parameters:
      request - The bind request to be copied.
      Returns:
      The new bind request.
      Throws:
      NullPointerException - If request was null .

    • copyOfGenericExtendedRequest

      public static GenericExtendedRequest copyOfGenericExtendedRequest(GenericExtendedRequest request)
      Creates a new generic extended request that is an exact copy of the provided request.
      Parameters:
      request - The generic extended request to be copied.
      Returns:
      The new generic extended request.
      Throws:
      NullPointerException - If request was null .

    • copyOfModifyDnRequest

      public static ModifyDnRequest copyOfModifyDnRequest(ModifyDnRequest request)
      Creates a new modify DN request that is an exact copy of the provided request.
      Parameters:
      request - The modify DN request to be copied.
      Returns:
      The new modify DN request.
      Throws:
      NullPointerException - If request was null .

    • copyOfModifyRequest

      public static ModifyRequest copyOfModifyRequest(ModifyRequest request)
      Creates a new modify request that is an exact copy of the provided request.
      Parameters:
      request - The modify request to be copied.
      Returns:
      The new modify request.
      Throws:
      NullPointerException - If request was null .

    • copyOfPasswordModifyExtendedRequest

      public static PasswordModifyExtendedRequest copyOfPasswordModifyExtendedRequest(PasswordModifyExtendedRequest request)
      Creates a new password modify extended request that is an exact copy of the provided request.
      Parameters:
      request - The password modify extended request to be copied.
      Returns:
      The new password modify extended request.
      Throws:
      NullPointerException - If request was null .

    • copyOfSearchRequest

      public static SearchRequest copyOfSearchRequest(SearchRequest request)
      Creates a new search request that is an exact copy of the provided request.
      Parameters:
      request - The search request to be copied.
      Returns:
      The new search request.
      Throws:
      NullPointerException - If request was null .

    • copyOfStartTlsExtendedRequest

      public static StartTlsExtendedRequest copyOfStartTlsExtendedRequest(StartTlsExtendedRequest request)
      Creates a new startTLS extended request that is an exact copy of the provided request.
      Parameters:
      request - The startTLS extended request to be copied.
      Returns:
      The new start TLS extended request.
      Throws:
      NullPointerException - If request was null .

    • copyOfUnbindRequest

      public static UnbindRequest copyOfUnbindRequest(UnbindRequest request)
      Creates a new unbind request that is an exact copy of the provided request.
      Parameters:
      request - The unbind request to be copied.
      Returns:
      The new unbind request.
      Throws:
      NullPointerException - If request was null .

    • copyOfWhoAmIExtendedRequest

      public static WhoAmIExtendedRequest copyOfWhoAmIExtendedRequest(WhoAmIExtendedRequest request)
      Creates a new Who Am I extended request that is an exact copy of the provided request.
      Parameters:
      request - The who Am I extended request to be copied.
      Returns:
      The new Who Am I extended request.
      Throws:
      NullPointerException - If request was null .

    • newAbandonRequest

      public static AbandonRequest newAbandonRequest(int requestID)
      Creates a new abandon request using the provided message ID.
      Parameters:
      requestID - The request ID of the request to be abandoned.
      Returns:
      The new abandon request.

    • newAddRequest

      public static AddRequest newAddRequest(Dn name)
      Creates a new add request using the provided distinguished name.
      Parameters:
      name - The distinguished name of the entry to be added.
      Returns:
      The new add request.
      Throws:
      NullPointerException - If name was null.

    • newAddRequest

      public static AddRequest newAddRequest(Entry entry)
      Creates a new add request backed by the provided entry. Modifications made to entry will be reflected in the returned add request. The returned add request supports updates to its list of controls, as well as updates to the name and attributes if the underlying entry allows.
      Parameters:
      entry - The entry to be added.
      Returns:
      The new add request.
      Throws:
      NullPointerException - If entry was null .

    • newAddRequest

      public static AddRequest newAddRequest(String name) throws LocalizedIllegalArgumentException
      Creates a new add request using the provided distinguished name decoded using the default schema.
      Parameters:
      name - The distinguished name of the entry to be added.
      Returns:
      The new add request.
      Throws:
      LocalizedIllegalArgumentException - If name could not be decoded using the default schema.
      NullPointerException - If name was null.

    • newAddRequest

      public static AddRequest newAddRequest(String... ldifLines) throws LocalizedIllegalArgumentException
      Creates a new add request using the provided lines of LDIF decoded using the default schema.
      Parameters:
      ldifLines - Lines of LDIF containing an LDIF add change record or an LDIF entry record.
      Returns:
      The new add request.
      Throws:
      LocalizedIllegalArgumentException - If ldifLines was empty, or contained invalid LDIF, or could not be decoded using the default schema.
      NullPointerException - If ldifLines was null .

    • newCancelExtendedRequest

      public static CancelExtendedRequest newCancelExtendedRequest(int requestID)
      Creates a new cancel extended request using the provided message ID.
      Parameters:
      requestID - The request ID of the request to be abandoned.
      Returns:
      The new cancel extended request.

    • newChangeRecord

      public static ChangeRecord newChangeRecord(String... ldifLines) throws LocalizedIllegalArgumentException
      Creates a new change record (an add, delete, modify, or modify DN request) using the provided lines of LDIF decoded using the default schema.
      Parameters:
      ldifLines - Lines of LDIF containing an LDIF change record or an LDIF entry record.
      Returns:
      The new change record.
      Throws:
      LocalizedIllegalArgumentException - If ldifLines was empty, or contained invalid LDIF, or could not be decoded using the default schema.
      NullPointerException - If ldifLines was null .

    • newCompareRequest

      public static CompareRequest newCompareRequest(Dn name, AttributeDescription attributeDescription, Object assertionValue)
      Creates a new compare request using the provided distinguished name, attribute name, and assertion value.

      If the assertion value is not an instance of ByteString then it will be converted using the ByteString.valueOfObject(Object) method.

      Parameters:
      name - The distinguished name of the entry to be compared.
      attributeDescription - The name of the attribute to be compared.
      assertionValue - The assertion value to be compared.
      Returns:
      The new compare request.
      Throws:
      NullPointerException - If name, attributeDescription, or assertionValue was null.

    • newCompareRequest

      public static CompareRequest newCompareRequest(String name, String attributeDescription, Object assertionValue) throws LocalizedIllegalArgumentException
      Creates a new compare request using the provided distinguished name, attribute name, and assertion value decoded using the default schema.

      If the assertion value is not an instance of ByteString then it will be converted using the ByteString.valueOfObject(Object) method.

      Parameters:
      name - The distinguished name of the entry to be compared.
      attributeDescription - The name of the attribute to be compared.
      assertionValue - The assertion value to be compared.
      Returns:
      The new compare request.
      Throws:
      LocalizedIllegalArgumentException - If name or attributeDescription could not be decoded using the default schema.
      NullPointerException - If name, attributeDescription, or assertionValue was null.

    • newDeleteRequest

      public static DeleteRequest newDeleteRequest(Dn name)
      Creates a new delete request using the provided distinguished name.
      Parameters:
      name - The distinguished name of the entry to be deleted.
      Returns:
      The new delete request.
      Throws:
      NullPointerException - If name was null.

    • newDeleteRequest

      public static DeleteRequest newDeleteRequest(String name) throws LocalizedIllegalArgumentException
      Creates a new delete request using the provided distinguished name decoded using the default schema.
      Parameters:
      name - The distinguished name of the entry to be deleted.
      Returns:
      The new delete request.
      Throws:
      LocalizedIllegalArgumentException - If name could not be decoded using the default schema.
      NullPointerException - If name was null.

    • newAnonymousBindRequest

      public static BindRequest newAnonymousBindRequest()
      Creates a new anonymous bind request initialized with an empty distinguished name, SIMPLE authentication type, and an empty password. The returned request is suitable for performing an anonymous bind, which may be useful in cases where an existing connections authorization state needs to be reset.

      This method is exactly equivalent to newBindRequest(), but its usage may result in more readable code in cases where the intent is to perform an anonymous bind request.

      Returns:
      The new anonymous bind request.

    • newBindRequest

      public static BindRequest newBindRequest()
      Creates a new bind request initialized with an empty distinguished name, SIMPLE authentication type, and an empty password. The returned request is suitable for performing an anonymous bind, which may be useful in cases where an existing connections authorization state needs to be reset. The request may be configured to perform a different type of bind by calling the request's various setter methods.
      Returns:
      The new bind request.

    • newSaslBindRequest

      public static BindRequest newSaslBindRequest(SaslClient saslClient)
      Creates a new SASL bind request configured to use the provided SaslClient. The returned bind request will have the same SASL mechanism as the provided SASL client and its SASL credentials will be populated with the SASL client's initial response if available.
      Parameters:
      saslClient - The SASL client which will drive the SASL authentication process.
      Returns:
      The new SASL bind request.
      Throws:
      IllegalArgumentException - If the provided SASL client has not been configured correctly.
      NullPointerException - If saslClient was null.

    • newAnonymousSaslBindRequest

      public static BindRequest newAnonymousSaslBindRequest(String traceString)
      Creates a new anonymous SASL bind request as defined in RFC 4505. This SASL mechanism allows a client to authenticate to the server without requiring the user to establish or otherwise disclose their identity to the server. That is, this mechanism provides an anonymous login method. This mechanism does not provide a security layer.

      Clients should provide trace information, which has no semantic value, and can be used by administrators in order to identify the user. It should take one of two forms: an Internet email address, or an opaque string that does not contain the '@' (U+0040) character and that can be interpreted by the system administrator of the client's domain. For privacy reasons, an Internet email address or other information identifying the user should only be used with permission from the user.

      Parameters:
      traceString - The optional trace information, which has no semantic value and can be used by administrators in order to identify the user, may be null.
      Returns:
      The new anonymous SASL bind request.
      See Also:

    • newPlainSaslBindRequest

      public static BindRequest newPlainSaslBindRequest(String authenticationId, char[] password, String authorizationId)
      Creates a new Plain SASL bind request as defined in RFC 4616. This SASL mechanism allows a client to authenticate to the server with an authentication ID and password. This mechanism does not provide a security layer.

      The authentication and optional authorization identities are specified using an authorization ID, or authzId, as defined in RFC 4513 section 5.2.1.8.

      Parameters:
      authenticationId - The authentication ID of the user. The authentication ID usually has the form "dn:" immediately followed by the distinguished name of the user, or "u:" followed by a user ID string, but other forms are permitted.
      password - The password of the user that the client wishes to bind as. The password will be converted to a UTF-8 octet string.
      authorizationId - The optional authorization ID of the user which represents an alternate authorization identity which should be used for subsequent operations performed on the connection. The authorization ID usually has the form "dn:" immediately followed by the distinguished name of the user, or "u:" followed by a user ID string, but other forms are permitted.
      Returns:
      The new Plain SASL bind request.
      Throws:
      NullPointerException - If authenticationId or password are null.
      See Also:

    • newExternalSaslBindRequest

      public static BindRequest newExternalSaslBindRequest(String authorizationId)
      Creates a new External SASL bind request as defined in RFC 4422. This SASL mechanism allows a client to request the server to use credentials established by means external to the mechanism to authenticate the client. The external means may be, for instance, SSL or TLS.

      A client may either request that its authorization identity be automatically derived from its authentication credentials exchanged at a lower security layer, or it may explicitly provide a desired authorization identity.

      The optional authorization identity is specified using an authorization ID, or authzId, as defined in RFC 4513 section 5.2.1.8.

      Parameters:
      authorizationId - The optional authorization ID of the user which represents an alternate authorization identity which should be used for subsequent operations performed on the connection. The authorization ID usually has the form "dn:" immediately followed by the distinguished name of the user, or "u:" followed by a user ID string, but other forms are permitted.
      Returns:
      The new External SASL bind request.
      See Also:

    • newCramMd5SaslBindRequest

      public static BindRequest newCramMd5SaslBindRequest(String authenticationId, char[] password)
      Creates a new CRAM-MD5 SASL bind request as defined in draft-ietf-sasl-crammd5. This SASL mechanism allows a client to perform a simple challenge-response authentication method, using a keyed MD5 digest. This mechanism does not provide a security layer.

      The CRAM-MD5 mechanism is intended to have limited use on the Internet. The mechanism offers inadequate protection against common attacks against application-level protocols and is prone to interoperability problems.

      The authentication and optional authorization identities are specified using an authorization ID, or authzId, as defined in RFC 4513 section 5.2.1.8.

      Parameters:
      authenticationId - The authentication ID of the user. The authentication ID usually has the form "dn:" immediately followed by the distinguished name of the user, or "u:" followed by a user ID string, but other forms are permitted.
      password - The password of the user that the client wishes to bind as. The password will be converted to a UTF-8 octet string.
      Returns:
      The new CRAM-MD5 SASL bind request.
      Throws:
      NullPointerException - If authenticationId or password are null.
      See Also:

    • newDigestMd5SaslBindRequest

      public static BindRequest newDigestMd5SaslBindRequest(String digestUri, String authenticationId, char[] password, String authorizationId, String realm, Map<String,?> properties)
      Creates a new DIGEST-MD5 SASL bind request as defined in RFC 2831. This SASL mechanism allows a client to perform a challenge-response authentication method, similar to HTTP Digest Access Authentication. This mechanism can be used to negotiate integrity and/or privacy protection for the underlying connection.

      Compared to CRAM-MD5, DIGEST-MD5 prevents chosen plain-text attacks, and permits the use of third party authentication servers, mutual authentication, and optimized re-authentication if a client has recently authenticated to a server.

      The authentication and optional authorization identities are specified using an authorization ID, or authzId, as defined in RFC 4513 section 5.2.1.8.

      Parameters:
      digestUri - The digest-uri which indicates the principal name of the service with which the client wishes to connect. Format is defined in RFC-2831. If the serv-type is not provided, ldap will be used as default.
      authenticationId - The authentication ID of the user. The authentication ID usually has the form "dn:" immediately followed by the distinguished name of the user, or "u:" followed by a user ID string, but other forms are permitted.
      password - The password of the user that the client wishes to bind as. The password will be converted to a UTF-8 octet string.
      authorizationId - The optional authorization ID of the user which represents an alternate authorization identity which should be used for subsequent operations performed on the connection. The authorization ID usually has the form "dn:" immediately followed by the distinguished name of the user, or "u:" followed by a user ID string, but other forms are permitted.
      realm - The optional name of the realm containing the user's account, which may be null.
      properties - The optional map containing additional SASL mechanism parameters, which may be null. See Sasl and the Java SASL reference guide for more information about the properties compatible with this SASL mechanism.
      Returns:
      The new Digest-MD5 SASL bind request.
      Throws:
      NullPointerException - If digestUri, authenticationId, or password are null.
      See Also:

    • newGssapiSaslBindRequest

      public static BindRequest newGssapiSaslBindRequest(String serverName, Subject subject, String authorizationId, Map<String,?> properties)
      Creates a new GSSAPI SASL bind request as defined in RFC 2831. This SASL mechanism allows a client to use the Generic Security Service Application Program Interface (GSS-API) Kerberos V5 to authenticate to the server. This mechanism can be used to negotiate integrity and/or privacy protection for the underlying connection.

      The optional authorization identity is specified using an authorization ID, or authzId, as defined in RFC 4513 section 5.2.1.8.

      Parameters:
      serverName - The fully-qualified host name of the server to authenticate to.
      subject - The Kerberos subject representing the user to be authenticated.
      authorizationId - The optional authorization ID of the user which represents an alternate authorization identity which should be used for subsequent operations performed on the connection. The authorization ID usually has the form "dn:" immediately followed by the distinguished name of the user, or "u:" followed by a user ID string, but other forms are permitted.
      properties - The optional map containing additional SASL mechanism parameters, which may be null. See Sasl and the Java SASL reference guide for more information about the properties compatible with this SASL mechanism.
      Returns:
      The new GSSAPI SASL bind request.
      Throws:
      NullPointerException - If serverName or subject are null.
      See Also:

    • newScramSaslBindRequest

      public static BindRequest newScramSaslBindRequest(ScramMechanism scramMechanism, String authenticationId, char[] password, String authorizationId)
      Creates a new SCRAM SASL bind request as defined in RFC 5802. This SASL mechanism allows a client to perform a challenge-response authentication method, similar to PBKDF2 except that credentials are not sent in the clear over the network and the PBKDF2 cost-based computation is offloaded to the client. The SCRAM SASL mechanism replaces DIGEST-MD5 and CRAM-MD5 and addresses many of the security concerns and interoperability issues identified in these legacy mechanisms.

      The authentication and optional authorization identities are specified using an authorization ID, or authzId, as defined in RFC 4513 section 5.2.1.8.

      Parameters:
      scramMechanism - The SCRAM mechanism to be used during authentication. Servers must store SCRAM credentials which are compatible with the SCRAM mechanism, otherwise authentication will fail.
      authenticationId - The authentication ID of the user. The authentication ID usually has the form "dn:" immediately followed by the distinguished name of the user, or "u:" followed by a user ID string, but other forms are permitted.
      password - The password of the user that the client wishes to bind as. The password will be converted to a UTF-8 octet string.
      authorizationId - The optional authorization ID of the user which represents an alternate authorization identity which should be used for subsequent operations performed on the connection. The authorization ID usually has the form "dn:" immediately followed by the distinguished name of the user, or "u:" followed by a user ID string, but other forms are permitted.
      Returns:
      The new SCRAM SASL bind request.
      Throws:
      NullPointerException - If scramMechanism, authenticationId, or password are null.
      See Also:

    • newGenericExtendedRequest

      public static GenericExtendedRequest newGenericExtendedRequest(String requestName)
      Creates a new generic extended request using the provided name and no value.
      Parameters:
      requestName - The dotted-decimal representation of the unique OID corresponding to this extended request.
      Returns:
      The new generic extended request.
      Throws:
      NullPointerException - If requestName was null.

    • newGenericExtendedRequest

      public static GenericExtendedRequest newGenericExtendedRequest(String requestName, Object requestValue)
      Creates a new generic extended request using the provided name and optional value.

      If the request value is not an instance of ByteString then it will be converted using the ByteString.valueOfObject(Object) method.

      Parameters:
      requestName - The dotted-decimal representation of the unique OID corresponding to this extended request.
      requestValue - The content of this generic extended request in a form defined by the extended operation, or null if there is no content.
      Returns:
      The new generic extended request.
      Throws:
      NullPointerException - If requestName was null.

    • newInvalidRequest

      public static InvalidRequest newInvalidRequest(Request.RequestType invalidRequestType, String invalidRawDn, LdapException reason)
      Creates a new invalid request using the provided reason.
      Parameters:
      invalidRequestType - The Ldap protocol-op type of the invalid request.
      invalidRawDn - The Dn which make this request invalid (might be null if the request is invalid because of another reason)
      reason - The reason why the request is invalid.
      Returns:
      The new invalid request.

    • newModifyDnRequest

      public static ModifyDnRequest newModifyDnRequest(Dn name, Rdn newRDN)
      Creates a new modify DN request using the provided distinguished name and new RDN. The new superior will be null, indicating that the renamed entry will remain under the same parent entry, and the old RDN attribute values will not be deleted.
      Parameters:
      name - The distinguished name of the entry to be renamed.
      newRDN - The new RDN of the entry.
      Returns:
      The new modify DN request.
      Throws:
      NullPointerException - If name or newRDN was null.

    • newModifyDnRequest

      public static ModifyDnRequest newModifyDnRequest(String name, String newRDN) throws LocalizedIllegalArgumentException
      Creates a new modify DN request using the provided distinguished name and new RDN decoded using the default schema. The new superior will be null, indicating that the renamed entry will remain under the same parent entry, and the old RDN attribute values will not be deleted.
      Parameters:
      name - The distinguished name of the entry to be renamed.
      newRDN - The new RDN of the entry.
      Returns:
      The new modify DN request.
      Throws:
      LocalizedIllegalArgumentException - If name or newRDN could not be decoded using the default schema.
      NullPointerException - If name or newRDN was null.

    • newModifyRequest

      public static ModifyRequest newModifyRequest(Dn name)
      Creates a new modify request using the provided distinguished name.
      Parameters:
      name - The distinguished name of the entry to be modified.
      Returns:
      The new modify request.
      Throws:
      NullPointerException - If name was null.

    • newModifyRequest

      public static ModifyRequest newModifyRequest(Entry fromEntry, Entry toEntry)
      Creates a new modify request containing a list of modifications which can be used to transform fromEntry into entry toEntry.

      The changes will be generated using a default set of options. More specifically, only user attributes will be compared, attributes will be compared using their matching rules, and all generated changes will be reversible: it will contain only modifications of type DELETE then ADD.

      Finally, the modify request will use the distinguished name taken from fromEntry. Moreover, this method will not check to see if both fromEntry and toEntry have the same distinguished name.

      This method is equivalent to: 

       ModifyRequest request = Entries.diffEntries(fromEntry, toEntry);
      Or: 
       ModifyRequest request = Entries.diffEntries(fromEntry, toEntry, Options.defaultOptions());
      Parameters:
      fromEntry - The source entry.
      toEntry - The destination entry.
      Returns:
      A modify request containing a list of modifications which can be used to transform fromEntry into entry toEntry. The returned request will always be non-null but may not contain any modifications.
      Throws:
      NullPointerException - If fromEntry or toEntry were null.
      See Also:

    • newModifyRequest

      public static ModifyRequest newModifyRequest(String name) throws LocalizedIllegalArgumentException
      Creates a new modify request using the provided distinguished name decoded using the default schema.
      Parameters:
      name - The distinguished name of the entry to be modified.
      Returns:
      The new modify request.
      Throws:
      LocalizedIllegalArgumentException - If name could not be decoded using the default schema.
      NullPointerException - If name was null.

    • newModifyRequest

      public static ModifyRequest newModifyRequest(String... ldifLines) throws LocalizedIllegalArgumentException
      Creates a new modify request using the provided lines of LDIF decoded using the default schema.
      Parameters:
      ldifLines - Lines of LDIF containing a single LDIF modify change record.
      Returns:
      The new modify request.
      Throws:
      LocalizedIllegalArgumentException - If ldifLines was empty, or contained invalid LDIF, or could not be decoded using the default schema.
      NullPointerException - If ldifLines was null .

    • newPasswordModifyExtendedRequest

      public static PasswordModifyExtendedRequest newPasswordModifyExtendedRequest()
      Creates a new password modify extended request, with no user identity, old password, or new password.
      Returns:
      The new password modify extended request.

    • newSearchRequest

      public static SearchRequest newSearchRequest(Dn name, SearchScope scope, Filter filter, String... attributeDescriptions)
      Creates a new search request using the provided distinguished name, scope, and filter.
      Parameters:
      name - The distinguished name of the base entry relative to which the search is to be performed.
      scope - The scope of the search.
      filter - The filter that defines the conditions that must be fulfilled in order for an entry to be returned.
      attributeDescriptions - The names of the attributes to be included with each entry.
      Returns:
      The new search request.
      Throws:
      NullPointerException - If the name, scope, or filter were null.

    • newSearchRequest

      public static SearchRequest newSearchRequest(String name, SearchScope scope, String filter, String... attributeDescriptions) throws LocalizedIllegalArgumentException
      Creates a new search request using the provided distinguished name, scope, and filter, decoded using the default schema.
      Parameters:
      name - The distinguished name of the base entry relative to which the search is to be performed.
      scope - The scope of the search.
      filter - The filter that defines the conditions that must be fulfilled in order for an entry to be returned.
      attributeDescriptions - The names of the attributes to be included with each entry.
      Returns:
      The new search request.
      Throws:
      LocalizedIllegalArgumentException - If name could not be decoded using the default schema, or if filter is not a valid LDAP string representation of a filter.
      NullPointerException - If the name, scope, or filter were null.

    • newSearchRequest

      public static SearchRequest newSearchRequest(Dn name, SearchScope scope)
      Creates a new search request using the provided distinguished name and scope.

      It will use the (objectclass=*) filter.

      Parameters:
      name - The distinguished name of the base entry relative to which the search is to be performed.
      scope - The scope of the search.
      Returns:
      The new search request.
      Throws:
      NullPointerException - If the name, scope were null.

    • newSearchRequest

      public static SearchRequest newSearchRequest(String name, SearchScope scope)
      Creates a new search request using the provided distinguished name and scope.

      It will use the (objectclass=*) filter.

      Parameters:
      name - The distinguished name of the base entry relative to which the search is to be performed.
      scope - The scope of the search.
      Returns:
      The new search request.
      Throws:
      NullPointerException - If the name, scope were null.

    • newSingleEntrySearchRequest

      public static SearchRequest newSingleEntrySearchRequest(Dn name, SearchScope scope, Filter filter, String... attributeDescriptions)
      Creates a new search request for a single entry, using the provided distinguished name, scope, and filter.
      Parameters:
      name - The distinguished name of the base entry relative to which the search is to be performed.
      scope - The scope of the search.
      filter - The filter that defines the conditions that must be fulfilled in order for an entry to be returned.
      attributeDescriptions - The names of the attributes to be included with each entry.
      Returns:
      The new search request.
      Throws:
      NullPointerException - If the name, scope, or filter were null.

    • newSingleEntrySearchRequest

      public static SearchRequest newSingleEntrySearchRequest(String name, SearchScope scope, String filter, String... attributeDescriptions) throws LocalizedIllegalArgumentException
      Creates a new search request for a single entry, using the provided distinguished name, scope, and filter, decoded using the default schema.
      Parameters:
      name - The distinguished name of the base entry relative to which the search is to be performed.
      scope - The scope of the search.
      filter - The filter that defines the conditions that must be fulfilled in order for an entry to be returned.
      attributeDescriptions - The names of the attributes to be included with each entry.
      Returns:
      The new search request.
      Throws:
      LocalizedIllegalArgumentException - If name could not be decoded using the default schema, or if filter is not a valid LDAP string representation of a filter.
      NullPointerException - If the name, scope, or filter were null.

    • newSimpleBindRequest

      public static BindRequest newSimpleBindRequest(String name, byte[] password) throws LocalizedIllegalArgumentException
      Creates a new simple bind request having the provided name and password suitable for name/password authentication. The name will be decoded using the default schema.

      The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

      Parameters:
      name - The name of the Directory object that the client wishes to bind as, which may be empty.
      password - The password of the Directory object that the client wishes to bind as, which may be empty indicating that an unauthenticated bind is to be performed.
      Returns:
      The new simple bind request.
      Throws:
      LocalizedIllegalArgumentException - If name could not be decoded using the default schema.
      NullPointerException - If name or password was null.

    • newSimpleBindRequest

      public static BindRequest newSimpleBindRequest(Dn name, byte[] password)
      Creates a new simple bind request having the provided name and password suitable for name/password authentication. The name will be decoded using the default schema.

      The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

      Parameters:
      name - The name of the Directory object that the client wishes to bind as, which may be empty.
      password - The password of the Directory object that the client wishes to bind as, which may be empty indicating that an unauthenticated bind is to be performed.
      Returns:
      The new simple bind request.
      Throws:
      NullPointerException - If name or password was null.

    • newSimpleBindRequest

      public static BindRequest newSimpleBindRequest(String name, char[] password)
      Creates a new simple bind request having the provided name and password suitable for name/password authentication. The name will be decoded using the default schema.

      The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

      Parameters:
      name - The name of the Directory object that the client wishes to bind as, which may be empty.
      password - The password of the Directory object that the client wishes to bind as, which may be empty indicating that an unauthenticated bind is to be performed. The password will be converted to a UTF-8 octet string.
      Returns:
      The new simple bind request.
      Throws:
      NullPointerException - If name or password was null.

    • newSimpleBindRequest

      public static BindRequest newSimpleBindRequest(String name, String password) throws LocalizedIllegalArgumentException
      Creates a new simple bind request having the provided name and password suitable for name/password authentication. The name will be decoded using the default schema.

      The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

      Parameters:
      name - The name of the Directory object that the client wishes to bind as, which may be empty.
      password - The password of the Directory object that the client wishes to bind as, which may be empty indicating that an unauthenticated bind is to be performed. The password will be converted to a UTF-8 octet string.
      Returns:
      The new simple bind request.
      Throws:
      LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.
      NullPointerException - If name or password was null.

    • newSimpleBindRequest

      public static BindRequest newSimpleBindRequest(Dn name, char[] password)
      Creates a new simple bind request having the provided name and password suitable for name/password authentication. The name will be decoded using the default schema.

      The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

      Parameters:
      name - The name of the Directory object that the client wishes to bind as, which may be empty.
      password - The password of the Directory object that the client wishes to bind as, which may be empty indicating that an unauthenticated bind is to be performed. The password will be converted to a UTF-8 octet string.
      Returns:
      The new simple bind request.
      Throws:
      NullPointerException - If name or password was null.

    • newSimpleBindRequest

      public static BindRequest newSimpleBindRequest(Dn name, String password)
      Creates a new simple bind request having the provided name and password suitable for name/password authentication. The name will be decoded using the default schema.

      The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

      Parameters:
      name - The name of the Directory object that the client wishes to bind as, which may be empty.
      password - The password of the Directory object that the client wishes to bind as, which may be empty indicating that an unauthenticated bind is to be performed. The password will be converted to a UTF-8 octet string.
      Returns:
      The new simple bind request.
      Throws:
      NullPointerException - If name or password was null.

    • newStartTlsExtendedRequest

      public static StartTlsExtendedRequest newStartTlsExtendedRequest(SslOptions sslOptions)
      Creates a new start TLS extended request which will use the provided SSL context.
      Parameters:
      sslOptions - The SslOptions that should be used when installing the TLS layer.
      Returns:
      The new start TLS extended request.
      Throws:
      NullPointerException - If sslContext was null.

    • newUnbindRequest

      public static UnbindRequest newUnbindRequest()
      Creates a new unbind request.
      Returns:
      The new unbind request.

    • newUnknownRequest

      public static UnknownRequest newUnknownRequest(byte protocolOpType, ByteString rawContent)
      Creates a new unknown request backed by the provided bytes. The returned request supports updates to its list of controls.
      Parameters:
      protocolOpType - The LDAP protocol-op type which was not recognized as a standard LDAP one.
      rawContent - Bytes of this unknown request.
      Returns:
      The new unknown request.
      Throws:
      NullPointerException - If rawContent was null .

    • newWhoAmIExtendedRequest

      public static WhoAmIExtendedRequest newWhoAmIExtendedRequest()
      Creates a new Who Am I extended request.
      Returns:
      The new Who Am I extended request.

    • getExtendedRequestOidForAlias

      public static String getExtendedRequestOidForAlias(String alias)
      Returns the extended request OID associated with the provided extended request "friendly name" alias or the provided alias if no OID has been found.
      Parameters:
      alias - Friendly name alias to resolve
      Returns:
      The extended request OID associated with the provided extended request "friendly name" alias or the provided alias if no OID has been found.

    • isExtendedRequestAlias

      public static boolean isExtendedRequestAlias(String alias)
      Returns true if the provided alias is a known user-friendly name of an extended request.
      Parameters:
      alias - Friendly name alias to resolve
      Returns:
      true if the provided alias is a known user-friendly name of an extended request.