Class PasswordModifyExtendedRequest

  • All Implemented Interfaces:
    ProtocolOp, ReadOnlyLDAPRequest, java.io.Serializable

    @NotMutable
    @ThreadSafety(level=NOT_THREADSAFE)
    public final class PasswordModifyExtendedRequest
    extends ExtendedRequest
    This class provides an implementation of the LDAP password modify extended request as defined in RFC 3062. It may be used to change the password for a user in the directory, and provides the ability to specify the current password for verification. It also offers the ability to request that the server generate a new password for the user.

    The elements of a password modify extended request include:
    • userIdentity -- This specifies the user for which to change the password. It should generally be the DN for the target user (although the specification does indicate that some servers may accept other values). If no value is provided, then the server will attempt to change the password for the currently-authenticated user.
    • oldPassword -- This specifies the current password for the user. Some servers may require that the old password be provided when a user is changing his or her own password as an extra level of verification, but it is generally not necessary when an administrator is resetting the password for another user.
    • newPassword -- This specifies the new password to use for the user. If it is not provided, then the server may attempt to generate a new password for the user, and in that case it will be included in the generatedPassword field of the corresponding PasswordModifyExtendedResult. Note that some servers may not support generating a new password, in which case the client will always be required to provide it.

    Example

    The following example demonstrates the use of the password modify extended operation to change the password for user "uid=test.user,ou=People,dc=example,dc=com". Neither the current password nor a new password will be provided, so the server will generate a new password for the user.
     PasswordModifyExtendedRequest passwordModifyRequest =
          new PasswordModifyExtendedRequest(
               "uid=test.user,ou=People,dc=example,dc=com", // The user to update
               (String) null, // The current password for the user.
               (String) null); // The new password.  null = server will generate
    
     PasswordModifyExtendedResult passwordModifyResult;
     try
     {
       passwordModifyResult = (PasswordModifyExtendedResult)
            connection.processExtendedOperation(passwordModifyRequest);
       // This doesn't necessarily mean that the operation was successful, since
       // some kinds of extended operations return non-success results under
       // normal conditions.
     }
     catch (LDAPException le)
     {
       // For an extended operation, this generally means that a problem was
       // encountered while trying to send the request or read the result.
       passwordModifyResult = new PasswordModifyExtendedResult(
            new ExtendedResult(le));
     }
    
     LDAPTestUtils.assertResultCodeEquals(passwordModifyResult,
          ResultCode.SUCCESS);
     String serverGeneratedNewPassword =
          passwordModifyResult.getGeneratedPassword();
     
    See Also:
    Serialized Form
    • Constructor Detail

      • PasswordModifyExtendedRequest

        public PasswordModifyExtendedRequest​(@Nullable
                                             java.lang.String newPassword)
        Creates a new password modify extended request that will attempt to change the password of the currently-authenticated user.
        Parameters:
        newPassword - The new password for the user. It may be null if the new password should be generated by the directory server.
      • PasswordModifyExtendedRequest

        public PasswordModifyExtendedRequest​(@Nullable
                                             byte[] newPassword)
        Creates a new password modify extended request that will attempt to change the password of the currently-authenticated user.
        Parameters:
        newPassword - The new password for the user. It may be null if the new password should be generated by the directory server.
      • PasswordModifyExtendedRequest

        public PasswordModifyExtendedRequest​(@Nullable
                                             java.lang.String oldPassword,
                                             @Nullable
                                             java.lang.String newPassword)
        Creates a new password modify extended request that will attempt to change the password of the currently-authenticated user.
        Parameters:
        oldPassword - The current password for the user. It may be null if the directory server does not require the user's current password for self changes.
        newPassword - The new password for the user. It may be null if the new password should be generated by the directory server.
      • PasswordModifyExtendedRequest

        public PasswordModifyExtendedRequest​(@Nullable
                                             byte[] oldPassword,
                                             @Nullable
                                             byte[] newPassword)
        Creates a new password modify extended request that will attempt to change the password of the currently-authenticated user.
        Parameters:
        oldPassword - The current password for the user. It may be null if the directory server does not require the user's current password for self changes.
        newPassword - The new password for the user. It may be null if the new password should be generated by the directory server.
      • PasswordModifyExtendedRequest

        public PasswordModifyExtendedRequest​(@Nullable
                                             java.lang.String userIdentity,
                                             @Nullable
                                             java.lang.String oldPassword,
                                             @Nullable
                                             java.lang.String newPassword)
        Creates a new password modify extended request that will attempt to change the password for the specified user.
        Parameters:
        userIdentity - The string that identifies the user whose password should be changed. It may or may not be a DN, but if it is not a DN, then the directory server must be able to identify the appropriate user from the provided identifier. It may be null to indicate that the password change should be for the currently-authenticated user.
        oldPassword - The current password for the user. It may be null if the directory server does not require the user's current password for self changes.
        newPassword - The new password for the user. It may be null if the new password should be generated by the directory server.
      • PasswordModifyExtendedRequest

        public PasswordModifyExtendedRequest​(@Nullable
                                             java.lang.String userIdentity,
                                             @Nullable
                                             byte[] oldPassword,
                                             @Nullable
                                             byte[] newPassword)
        Creates a new password modify extended request that will attempt to change the password for the specified user.
        Parameters:
        userIdentity - The string that identifies the user whose password should be changed. It may or may not be a DN, but if it is not a DN, then the directory server must be able to identify the appropriate user from the provided identifier. It may be null to indicate that the password change should be for the currently-authenticated user.
        oldPassword - The current password for the user. It may be null if the directory server does not require the user's current password for self changes.
        newPassword - The new password for the user. It may be null if the new password should be generated by the directory server.
      • PasswordModifyExtendedRequest

        public PasswordModifyExtendedRequest​(@Nullable
                                             java.lang.String userIdentity,
                                             @Nullable
                                             java.lang.String oldPassword,
                                             @Nullable
                                             java.lang.String newPassword,
                                             @Nullable
                                             Control[] controls)
        Creates a new password modify extended request that will attempt to change the password for the specified user.
        Parameters:
        userIdentity - The string that identifies the user whose password should be changed. It may or may not be a DN, but if it is not a DN, then the directory server must be able to identify the appropriate user from the provided identifier. It may be null to indicate that the password change should be for the currently-authenticated user.
        oldPassword - The current password for the user. It may be null if the directory server does not require the user's current password for self changes.
        newPassword - The new password for the user. It may be null if the new password should be generated by the directory server.
        controls - The set of controls to include in the request.
      • PasswordModifyExtendedRequest

        public PasswordModifyExtendedRequest​(@Nullable
                                             java.lang.String userIdentity,
                                             @Nullable
                                             byte[] oldPassword,
                                             @Nullable
                                             byte[] newPassword,
                                             @Nullable
                                             Control[] controls)
        Creates a new password modify extended request that will attempt to change the password for the specified user.
        Parameters:
        userIdentity - The string that identifies the user whose password should be changed. It may or may not be a DN, but if it is not a DN, then the directory server must be able to identify the appropriate user from the provided identifier. It may be null to indicate that the password change should be for the currently-authenticated user.
        oldPassword - The current password for the user. It may be null if the directory server does not require the user's current password for self changes.
        newPassword - The new password for the user. It may be null if the new password should be generated by the directory server.
        controls - The set of controls to include in the request.
      • PasswordModifyExtendedRequest

        public PasswordModifyExtendedRequest​(@NotNull
                                             ExtendedRequest extendedRequest)
                                      throws LDAPException
        Creates a new password modify extended request from the provided generic extended request.
        Parameters:
        extendedRequest - The generic extended request to use to create this password modify extended request.
        Throws:
        LDAPException - If a problem occurs while decoding the request.
    • Method Detail

      • getUserIdentity

        @Nullable
        public java.lang.String getUserIdentity()
        Retrieves the user identity for this request, if available.
        Returns:
        The user identity for this request, or null if the password change should target the currently-authenticated user.
      • getOldPassword

        @Nullable
        public java.lang.String getOldPassword()
        Retrieves the string representation of the old password for this request, if available.
        Returns:
        The string representation of the old password for this request, or null if it was not provided.
      • getOldPasswordBytes

        @Nullable
        public byte[] getOldPasswordBytes()
        Retrieves the binary representation of the old password for this request, if available.
        Returns:
        The binary representation of the old password for this request, or null if it was not provided.
      • getRawOldPassword

        @Nullable
        public ASN1OctetString getRawOldPassword()
        Retrieves the raw old password for this request, if available.
        Returns:
        The raw old password for this request, or null if it was not provided.
      • getNewPassword

        @Nullable
        public java.lang.String getNewPassword()
        Retrieves the string representation of the new password for this request, if available.
        Returns:
        The string representation of the new password for this request, or null if it was not provided.
      • getNewPasswordBytes

        @Nullable
        public byte[] getNewPasswordBytes()
        Retrieves the binary representation of the new password for this request, if available.
        Returns:
        The binary representation of the new password for this request, or null if it was not provided.
      • getRawNewPassword

        @Nullable
        public ASN1OctetString getRawNewPassword()
        Retrieves the raw new password for this request, if available.
        Returns:
        The raw new password for this request, or null if it was not provided.
      • process

        @NotNull
        public PasswordModifyExtendedResult process​(@NotNull
                                                    LDAPConnection connection,
                                                    int depth)
                                             throws LDAPException
        Sends this extended request to the directory server over the provided connection and returns the associated response.
        Overrides:
        process in class ExtendedRequest
        Parameters:
        connection - The connection to use to communicate with the directory server.
        depth - The current referral depth for this request. It should always be one for the initial request, and should only be incremented when following referrals.
        Returns:
        An LDAP result object that provides information about the result of the extended operation processing.
        Throws:
        LDAPException - If a problem occurs while sending the request or reading the response.
      • duplicate

        @NotNull
        public PasswordModifyExtendedRequest duplicate​(@Nullable
                                                       Control[] controls)
        Creates a new instance of this LDAP request that may be modified without impacting this request. The provided controls will be used for the new request instead of duplicating the controls from this request.. Subclasses should override this method to return a duplicate of the appropriate type.
        Specified by:
        duplicate in interface ReadOnlyLDAPRequest
        Overrides:
        duplicate in class ExtendedRequest
        Parameters:
        controls - The set of controls to include in the duplicate request.
        Returns:
        A new instance of this LDAP request that may be modified without impacting this request.
      • getExtendedRequestName

        @NotNull
        public java.lang.String getExtendedRequestName()
        Retrieves the user-friendly name for the extended request, if available. If no user-friendly name has been defined, then the OID will be returned.
        Overrides:
        getExtendedRequestName in class ExtendedRequest
        Returns:
        The user-friendly name for this extended request, or the OID if no user-friendly name is available.