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.

  • Field Details

    • DN_PREFIX

      public static final ByteString DN_PREFIX
      The distinguished name prefix.

  • 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 addRequest)
      Creates a new add request that is an exact copy of the provided request.
      Parameters:
      addRequest - The add request to be copied.
      Returns:
      The new add request.
      Throws:
      NullPointerException - If request was null .

    • copyOfCancelExtendedRequest

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

    • copyOfCompareRequest

      public static CompareRequest copyOfCompareRequest(CompareRequest compareRequest)
      Creates a new compare request that is an exact copy of the provided request.
      Parameters:
      compareRequest - 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 bindRequest)
      Creates a new bind request that is an exact copy of the provided request.
      Parameters:
      bindRequest - The bind request to be copied.
      Returns:
      The new bind request.
      Throws:
      NullPointerException - If request was null .

    • copyOfGenericExtendedRequest

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

    • copyOfModifyDnRequest

      public static ModifyDnRequest copyOfModifyDnRequest(ModifyDnRequest modifyDnRequest)
      Creates a new modify DN request that is an exact copy of the provided request.
      Parameters:
      modifyDnRequest - 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 modifyRequest)
      Creates a new modify request that is an exact copy of the provided request.
      Parameters:
      modifyRequest - The modify request to be copied.
      Returns:
      The new modify request.

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

    • copyOfSearchRequest

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

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

    • copyOfUnbindRequest

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

    • copyOfWhoAmIExtendedRequest

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

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

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

    • 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.
      Returns:
      The new bind request.

    • newBindRequest

      public static BindRequest newBindRequest(int version, Dn name, byte authenticationType, ByteString authenticationValue) throws IOException
      Creates a new bind request initialized with the distinguished name, the authentication type and the authentication value.
      Parameters:
      version - the version of the protocol to be used at the LDAP message layer.
      name - the name of the Directory object that the client wishes to bind as. May be empty, but cannot be null.
      authenticationType - the authentication mechanism identifier.
      authenticationValue - the encoded authentication value for this bind request as defined by the LDAP protocol.
      Returns:
      The new bind request.
      Throws:
      IOException

    • newSaslBindRequest

      public static BindRequest newSaslBindRequest(String saslMechanism, ByteString saslCredentials)
      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:
      saslMechanism - The SASL mechanism name, such as BindRequest.SASL_MECHANISM_NAME_PLAIN.
      saslCredentials - The optional SASL credentials which will be defensively copied if provided.
      Returns:
      The new SASL bind request.
      Throws:
      UnsupportedOperationException - If this bind request does not permit the authentication type or value to be set.
      NullPointerException - If saslMechanism was null.

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

    • newGenericExtendedRequest

      public static GenericExtendedRequest newGenericExtendedRequest(String requestName, ByteString 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.

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

    • newModifyDnRequest

      public static ModifyDnRequest newModifyDnRequest(Dn name, Rdn newRDN, Dn newSuperior, boolean deleteOldRdn)
      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.
      newSuperior - the distinguished name of the new superior entry, or null if the entry is to remain under the same parent entry.
      deleteOldRdn - true if the old RDN attribute values are to be deleted from the entry, or false if they are to be retained.
      Returns:
      The new modify DN request.
      Throws:
      NullPointerException - If name or newRDN was null.

    • newModifyDnRequest

      public static ModifyDnRequest newModifyDnRequest(String name, String newRDN, String newSuperior, boolean deleteOldRdn)
      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.
      newSuperior - the distinguished name of the new superior entry, or null if the entry is to remain under the same parent entry.
      deleteOldRdn - true if the old RDN attribute values are to be deleted from the entry, or false if they are to be retained.
      Returns:
      The new modify DN request.
      Throws:
      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.

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

    • 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(Object userIdentity, ByteString oldPassword, ByteString newPassword)
      Creates a new password modify extended request, with specified user identity, old password and new password.
      Parameters:
      userIdentity - the identity of the user whose password is to be modified, or null if the request should be applied to the user currently associated with the session.
      oldPassword - the current password for the user, or null if the password is not known.
      newPassword - the desired password for the user, or null if a new password should be generated.
      Returns:
      The new password modify extended request.

    • newPasswordModifyExtendedRequest

      public static PasswordModifyExtendedRequest newPasswordModifyExtendedRequest(Object userIdentity)
      Creates a new password modify extended request, with specified user identity.
      Parameters:
      userIdentity - the identity of the user whose password is to be modified, or null if the request should be applied to the user currently associated with the session.
      Returns:
      The new password modify extended request.

    • newSearchRequest

      public static SearchRequest newSearchRequest(Dn name, SearchScope scope, DereferenceAliasesPolicy dereferenceAliasesPolicy, int sizeLimit, int timeLimit, boolean typesOnly, Filter filter, String... attributeDescriptions)
      Creates a new search request with all parameters.
      Parameters:
      name - the distinguished name of the base entry relative to which the search is to be performed.
      scope - the scope of the search.
      dereferenceAliasesPolicy - the alias dereferencing policy to be used during the search.
      sizeLimit - the maximum number of entries that will be returned by the search. 0 means an unlimited number of entries will be returned.
      timeLimit - the time limit that should be used in order to restrict the maximum time (in seconds) allowed for the search.
      typesOnly - true if only attribute descriptions (and not values) are to be returned, or false (the default) if both attribute descriptions and values are to be returned.
      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.

    • newSearchRequest

      public static SearchRequest newSearchRequest(Dn name, SearchScope scope, DereferenceAliasesPolicy dereferenceAliasesPolicy, int sizeLimit, int timeLimit, boolean typesOnly, Filter filter, List<String> attributeDescriptions, List<Control> controls)
      Creates a new search request with all parameters.
      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.
      dereferenceAliasesPolicy - the alias dereferencing policy to be used during the search.
      sizeLimit - the maximum number of entries that will be returned by the search. 0 means an unlimited number of entries will be returned.
      timeLimit - the time limit that should be used in order to restrict the maximum time (in seconds) allowed for the search.
      typesOnly - true if only attribute descriptions (and not values) are to be returned, or false (the default) if both attribute descriptions and values are to be returned.
      attributeDescriptions - the names of the attributes to be included with each entry.
      controls - the List containing the controls.
      Returns:
      The new search request.

    • newSearchRequest

      public static SearchRequest newSearchRequest(String name, SearchScope scope, DereferenceAliasesPolicy dereferenceAliasesPolicy, int sizeLimit, int timeLimit, boolean typesOnly, String filter, String... attributeDescriptions)
      Creates a new search request with all parameters.
      Parameters:
      name - the distinguished name of the base entry relative to which the search is to be performed.
      scope - the scope of the search.
      dereferenceAliasesPolicy - the alias dereferencing policy to be used during the search.
      sizeLimit - the maximum number of entries that will be returned by the search. 0 means an unlimited number of entries will be returned.
      timeLimit - the time limit that should be used in order to restrict the maximum time (in seconds) allowed for the search.
      typesOnly - true if only attribute descriptions (and not values) are to be returned, or false (the default) if both attribute descriptions and values are to be returned.
      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.

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

    • 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

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

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

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

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

    • newSimpleBindRequest

      public static BindRequest newSimpleBindRequest(String name, ByteString 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, ByteString 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.

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