001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2010 Sun Microsystems, Inc.
015 * Portions copyright 2012-2015 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap.requests;
019
020import java.util.List;
021
022import org.forgerock.opendj.ldap.ByteString;
023import org.forgerock.opendj.ldap.DecodeException;
024import org.forgerock.opendj.ldap.DecodeOptions;
025import org.forgerock.opendj.ldap.controls.Control;
026import org.forgerock.opendj.ldap.controls.ControlDecoder;
027import org.forgerock.opendj.ldap.responses.ExtendedResultDecoder;
028import org.forgerock.opendj.ldap.responses.PasswordModifyExtendedResult;
029
030/**
031 * The password modify extended request as defined in RFC 3062. This operation
032 * allows directory clients to update user passwords. The user may or may not be
033 * associated with a directory entry. The user may or may not be represented as
034 * an LDAP DN. The user's password may or may not be stored in the directory. In
035 * addition, it includes support for requiring the user's current password as
036 * well as for generating a new password if none was provided.
037 *
038 * <pre>
039 * String userIdentity = ...; // For example, u:&lt;uid> or dn:&lt;DN>
040 * char[] oldPassword = ...;
041 * char[] newPassword = ...;
042 * Connection connection = ...;
043 *
044 * PasswordModifyExtendedRequest request =
045 *         Requests.newPasswordModifyExtendedRequest()
046 *             .setUserIdentity(userIdentity)
047 *             .setOldPassword(oldPassword)
048 *             .setNewPassword(newPassword);
049 *
050 * PasswordModifyExtendedResult result = connection.extendedRequest(request);
051 * if (result.isSuccess()) {
052 *     // Changed password
053 * } else {
054 *     // Use result to diagnose error.
055 * }
056 * </pre>
057 *
058 * @see PasswordModifyExtendedResult
059 * @see <a href="http://tools.ietf.org/html/rfc3062">RFC 3062 - LDAP Password
060 *      Modify Extended Operation </a>
061 */
062public interface PasswordModifyExtendedRequest extends
063        ExtendedRequest<PasswordModifyExtendedResult> {
064
065    /**
066     * A decoder which can be used to decode password modify extended operation
067     * requests.
068     */
069    ExtendedRequestDecoder<PasswordModifyExtendedRequest, PasswordModifyExtendedResult> DECODER =
070            new PasswordModifyExtendedRequestImpl.RequestDecoder();
071
072    /**
073     * The OID for the password modify extended operation request.
074     */
075    String OID = "1.3.6.1.4.1.4203.1.11.1";
076
077    @Override
078    PasswordModifyExtendedRequest addControl(Control control);
079
080    @Override
081    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
082            throws DecodeException;
083
084    @Override
085    List<Control> getControls();
086
087    /**
088     * Returns the desired password for the user, or {@code null} if a new
089     * password should be generated.
090     *
091     * @return The desired password for the user, or {@code null} if a new
092     *         password should be generated.
093     */
094    byte[] getNewPassword();
095
096    @Override
097    String getOID();
098
099    /**
100     * Returns the current password for the user, if known.
101     *
102     * @return The current password for the user, or {@code null} if the
103     *         password is not known.
104     */
105    byte[] getOldPassword();
106
107    @Override
108    ExtendedResultDecoder<PasswordModifyExtendedResult> getResultDecoder();
109
110    /**
111     * Returns the identity of the user whose password is to be modified, or
112     * {@code null} if the request should be applied to the user currently
113     * associated with the session. The returned identity may or may not be a
114     * distinguished name.
115     *
116     * @return The identity of the user whose password is to be modified, or
117     *         {@code null} if the request should be applied to the user
118     *         currently associated with the session.
119     */
120    ByteString getUserIdentity();
121
122    /**
123     * Returns the identity of the user whose password is to be modified decoded
124     * as a UTF-8 string, or {@code null} if the request should be applied to
125     * the user currently associated with the session. The returned identity may
126     * or may not be a distinguished name.
127     *
128     * @return The identity of the user whose password is to be modified decoded
129     *         as a UTF-8 string, or {@code null} if the request should be
130     *         applied to the user currently associated with the session.
131     */
132    String getUserIdentityAsString();
133
134    @Override
135    ByteString getValue();
136
137    @Override
138    boolean hasValue();
139
140    /**
141     * Sets the desired password for the user.
142     *
143     * @param newPassword
144     *            The desired password for the user, or {@code null} if a new
145     *            password should be generated.
146     * @return This password modify request.
147     * @throws UnsupportedOperationException
148     *             If this password modify extended request does not permit the
149     *             new password to be set.
150     */
151    PasswordModifyExtendedRequest setNewPassword(byte[] newPassword);
152
153    /**
154     * Sets the desired password for the user. The password will be converted to
155     * a UTF-8 octet string.
156     *
157     * @param newPassword
158     *            The desired password for the user, or {@code null} if a new
159     *            password should be generated.
160     * @return This password modify request.
161     * @throws UnsupportedOperationException
162     *             If this password modify extended request does not permit the
163     *             new password to be set.
164     */
165    PasswordModifyExtendedRequest setNewPassword(char[] newPassword);
166
167    /**
168     * Sets the current password for the user.
169     *
170     * @param oldPassword
171     *            The current password for the user, or {@code null} if the
172     *            password is not known.
173     * @return This password modify request.
174     * @throws UnsupportedOperationException
175     *             If this password modify extended request does not permit the
176     *             old password to be set.
177     */
178    PasswordModifyExtendedRequest setOldPassword(byte[] oldPassword);
179
180    /**
181     * Sets the current password for the user. The password will be converted to
182     * a UTF-8 octet string.
183     *
184     * @param oldPassword
185     *            The current password for the user, or {@code null} if the
186     *            password is not known.
187     * @return This password modify request.
188     * @throws UnsupportedOperationException
189     *             If this password modify extended request does not permit the
190     *             old password to be set.
191     */
192    PasswordModifyExtendedRequest setOldPassword(char[] oldPassword);
193
194    /**
195     * Sets the identity of the user whose password is to be modified. The
196     * identity may or may not be a distinguished name.
197     * <p>
198     * If {@code userIdentity} is not an instance of {@code ByteString} then it
199     * will be converted using the {@link ByteString#valueOfObject(Object)} method.
200     *
201     * @param userIdentity
202     *            The identity of the user whose password is to be modified, or
203     *            {@code null} if the request should be applied to the user
204     *            currently associated with the session.
205     * @return This password modify request.
206     * @throws UnsupportedOperationException
207     *             If this password modify extended request does not permit the
208     *             user identity to be set.
209     */
210    PasswordModifyExtendedRequest setUserIdentity(Object userIdentity);
211
212}