001    /*
002     * Copyright 2007-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2015 UnboundID Corp.
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     */
021    package com.unboundid.ldap.sdk.unboundidds.controls;
022    
023    
024    
025    import com.unboundid.ldap.sdk.Control;
026    import com.unboundid.ldap.sdk.LDAPException;
027    import com.unboundid.ldap.sdk.ResultCode;
028    import com.unboundid.util.NotMutable;
029    import com.unboundid.util.ThreadSafety;
030    import com.unboundid.util.ThreadSafetyLevel;
031    
032    import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*;
033    
034    
035    
036    /**
037     * <BLOCKQUOTE>
038     *   <B>NOTE:</B>  This class is part of the Commercial Edition of the UnboundID
039     *   LDAP SDK for Java.  It is not available for use in applications that
040     *   include only the Standard Edition of the LDAP SDK, and is not supported for
041     *   use in conjunction with non-UnboundID products.
042     * </BLOCKQUOTE>
043     * This class provides an implementation of the password policy request control
044     * as described in draft-behera-ldap-password-policy.  It may be used to request
045     * information related to a user's password policy.  In the UnboundID Directory
046     * Server, this control may be included with add, bind, compare, modify, and
047     * password modify requests.
048     * <BR><BR>
049     * The corresponding {@link PasswordPolicyResponseControl} may include at most
050     * one warning from the set of {@link PasswordPolicyWarningType} values and at
051     * most one error from the set of {@link PasswordPolicyErrorType} values.  See
052     * the documentation for those classes for more information on the information
053     * that may be included.
054     * <BR><BR>
055     * <H2>Example</H2>
056     * The following example demonstrates the use of the password policy request
057     * control in conjunction with a bind operation:
058     * <PRE>
059     * SimpleBindRequest bindRequest = new SimpleBindRequest(
060     *      "uid=john.doe,ou=People,dc=example,dc=com", "password",
061     *      new PasswordPolicyRequestControl());
062     *
063     * BindResult bindResult;
064     * try
065     * {
066     *   bindResult = connection.bind(bindRequest);
067     * }
068     * catch (LDAPException le)
069     * {
070     *   // The bind failed.  There may be a password policy response control to
071     *   // help tell us why.
072     *   bindResult = new BindResult(le.toLDAPResult());
073     * }
074     *
075     * PasswordPolicyResponseControl pwpResponse =
076     *      PasswordPolicyResponseControl.get(bindResult);
077     * if (pwpResponse != null)
078     * {
079     *   PasswordPolicyErrorType errorType = pwpResponse.getErrorType();
080     *   if (errorType != null)
081     *   {
082     *     // There was a password policy-related error.
083     *   }
084     *
085     *   PasswordPolicyWarningType warningType = pwpResponse.getWarningType();
086     *   if (warningType != null)
087     *   {
088     *     // There was a password policy-related warning.
089     *     int value = pwpResponse.getWarningValue();
090     *     switch (warningType)
091     *     {
092     *       case TIME_BEFORE_EXPIRATION:
093     *         // The warning value is the number of seconds until the user's
094     *         // password expires.
095     *         break;
096     *       case GRACE_LOGINS_REMAINING:
097     *         // The warning value is the number of grace logins remaining for
098     *         // the user.
099     *     }
100     *   }
101     * }
102     * </PRE>
103     */
104    @NotMutable()
105    @ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
106    public final class PasswordPolicyRequestControl
107           extends Control
108    {
109      /**
110       * The OID (1.3.6.1.4.1.42.2.27.8.5.1) for the password policy request
111       * control.
112       */
113      public static final String PASSWORD_POLICY_REQUEST_OID =
114           "1.3.6.1.4.1.42.2.27.8.5.1";
115    
116    
117    
118      /**
119       * The serial version UID for this serializable class.
120       */
121      private static final long serialVersionUID = 6495056761590890150L;
122    
123    
124    
125      /**
126       * Creates a new password policy request control.  The control will not be
127       * marked critical.
128       */
129      public PasswordPolicyRequestControl()
130      {
131        super(PASSWORD_POLICY_REQUEST_OID, false, null);
132      }
133    
134    
135    
136      /**
137       * Creates a new password policy request control.
138       *
139       * @param  isCritical  Indicates whether the control should be marked
140       * critical.
141       */
142      public PasswordPolicyRequestControl(final boolean isCritical)
143      {
144        super(PASSWORD_POLICY_REQUEST_OID, isCritical, null);
145      }
146    
147    
148    
149      /**
150       * Creates a new password policy request control which is decoded from the
151       * provided generic control.
152       *
153       * @param  control  The generic control to be decoded as a password policy
154       *                  request control.
155       *
156       * @throws  LDAPException  If the provided control cannot be decoded as a
157       *                         password policy request control.
158       */
159      public PasswordPolicyRequestControl(final Control control)
160             throws LDAPException
161      {
162        super(control);
163    
164        if (control.hasValue())
165        {
166          throw new LDAPException(ResultCode.DECODING_ERROR,
167                                  ERR_PWP_REQUEST_HAS_VALUE.get());
168        }
169      }
170    
171    
172    
173      /**
174       * {@inheritDoc}
175       */
176      @Override()
177      public String getControlName()
178      {
179        return INFO_CONTROL_NAME_PW_POLICY_REQUEST.get();
180      }
181    
182    
183    
184      /**
185       * {@inheritDoc}
186       */
187      @Override()
188      public void toString(final StringBuilder buffer)
189      {
190        buffer.append("PasswordPolicyRequestControl(isCritical=");
191        buffer.append(isCritical());
192        buffer.append(')');
193      }
194    }