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