001/*
002 * Copyright 2013-2019 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2015-2019 Ping Identity Corporation
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021package com.unboundid.ldap.sdk.unboundidds.controls;
022
023
024
025import com.unboundid.ldap.sdk.Control;
026import com.unboundid.ldap.sdk.LDAPException;
027import com.unboundid.ldap.sdk.ResultCode;
028import com.unboundid.util.NotMutable;
029import com.unboundid.util.ThreadSafety;
030import com.unboundid.util.ThreadSafetyLevel;
031
032import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*;
033
034
035
036/**
037 * This class provides a request control that can be included in a modify
038 * request or a password modify extended request in order to indicate that if
039 * the operation results in changing the password for a user, the user's former
040 * password should be marked as "retired", which may allow it to remain in use
041 * for a brief period of time (as configured in the password policy governing
042 * that user) to allow for applications which may have been configured with that
043 * password can be updated to use the new password.
044 * <BR>
045 * <BLOCKQUOTE>
046 *   <B>NOTE:</B>  This class, and other classes within the
047 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
048 *   supported for use against Ping Identity, UnboundID, and
049 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
050 *   for proprietary functionality or for external specifications that are not
051 *   considered stable or mature enough to be guaranteed to work in an
052 *   interoperable way with other types of LDAP servers.
053 * </BLOCKQUOTE>
054 * <BR>
055 * This control has an OID of "1.3.6.1.4.1.30221.2.5.31" and does not have a
056 * value.  The criticality may be either true (in which case the operation will
057 * succeed only if the user's password policy allows passwords to be retired by
058 * a request control) or false (in which case if the password policy does not
059 * allow the use of this control, the operation will be processed as if the
060 * control had not been included in the request).
061 * <BR><BR>
062 * <H2>Example</H2>
063 * The following example demonstrates the use of the retire password request
064 * control to request that a user's current password be retired in the course of
065 * a password change.
066 * <PRE>
067 * Control[] requestControls =
068 * {
069 *   new RetirePasswordRequestControl(true)
070 * };
071 *
072 * PasswordModifyExtendedRequest passwordModifyRequest =
073 *      new PasswordModifyExtendedRequest(
074 *           "uid=test.user,ou=People,dc=example,dc=com", // The user to update
075 *           null, // The current password -- we don't know it.
076 *           "newPassword", // The new password to assign to the user.
077 *           requestControls); // The controls to include in the request.
078 * PasswordModifyExtendedResult passwordModifyResult =
079 *      (PasswordModifyExtendedResult)
080 *      connection.processExtendedOperation(passwordModifyRequest);
081 * </PRE>
082 *
083 * @see  PurgePasswordRequestControl
084 */
085@NotMutable()
086@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
087public final class RetirePasswordRequestControl
088       extends Control
089{
090  /**
091   * The OID (1.3.6.1.4.1.30221.2.5.31) for the retire password request control.
092   */
093  public static final  String RETIRE_PASSWORD_REQUEST_OID =
094       "1.3.6.1.4.1.30221.2.5.31";
095
096
097
098  /**
099   * The serial version UID for this serializable class.
100   */
101  private static final long serialVersionUID = 7261376468186883355L;
102
103
104
105  /**
106   * Creates a new retire password request control with the specified
107   * criticality.
108   *
109   * @param  isCritical  Indicates whether the control should be considered
110   *                     critical.
111   */
112  public RetirePasswordRequestControl(final boolean isCritical)
113  {
114    super(RETIRE_PASSWORD_REQUEST_OID, isCritical, null);
115  }
116
117
118
119  /**
120   * Creates a new retire password request control which is decoded from the
121   * provided generic control.
122   *
123   * @param  control  The generic control to be decoded as a retire password
124   *                  request control.
125   *
126   * @throws LDAPException  If the provided control cannot be decoded as a
127   *                         retire password request control.
128   */
129  public RetirePasswordRequestControl(final Control control)
130       throws LDAPException
131  {
132    super(control);
133
134    if (control.hasValue())
135    {
136      throw new LDAPException(ResultCode.DECODING_ERROR,
137           ERR_RETIRE_PASSWORD_REQUEST_CONTROL_HAS_VALUE.get());
138    }
139  }
140
141
142
143  /**
144   * {@inheritDoc}
145   */
146  @Override()
147  public String getControlName()
148  {
149    return INFO_CONTROL_NAME_RETIRE_PASSWORD_REQUEST.get();
150  }
151
152
153
154  /**
155   * {@inheritDoc}
156   */
157  @Override()
158  public void toString(final StringBuilder buffer)
159  {
160    buffer.append("RetirePasswordRequestControl(isCritical=");
161    buffer.append(isCritical());
162    buffer.append(')');
163  }
164}