001    /*
002     * Copyright 2008-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.extensions;
022    
023    
024    
025    import java.io.Serializable;
026    import java.text.ParseException;
027    import java.util.Date;
028    
029    import com.unboundid.asn1.ASN1Element;
030    import com.unboundid.asn1.ASN1Enumerated;
031    import com.unboundid.asn1.ASN1OctetString;
032    import com.unboundid.asn1.ASN1Sequence;
033    import com.unboundid.ldap.sdk.LDAPException;
034    import com.unboundid.ldap.sdk.ResultCode;
035    import com.unboundid.util.NotMutable;
036    import com.unboundid.util.ThreadSafety;
037    import com.unboundid.util.ThreadSafetyLevel;
038    
039    import static com.unboundid.ldap.sdk.unboundidds.extensions.ExtOpMessages.*;
040    import static com.unboundid.util.Debug.*;
041    import static com.unboundid.util.StaticUtils.*;
042    
043    
044    
045    /**
046     * <BLOCKQUOTE>
047     *   <B>NOTE:</B>  This class is part of the Commercial Edition of the UnboundID
048     *   LDAP SDK for Java.  It is not available for use in applications that
049     *   include only the Standard Edition of the LDAP SDK, and is not supported for
050     *   use in conjunction with non-UnboundID products.
051     * </BLOCKQUOTE>
052     * This class defines an operation that may be used in conjunction with the
053     * password policy state extended operation.  A password policy state operation
054     * can be used to get or set various properties of the password policy state for
055     * a user.  Operations that are available for use with the password policy state
056     * operation include:
057     * <UL>
058     *   <LI>Get the DN of the password policy configuration entry for the target
059     *       user.</LI>
060     *   <LI>Get, set, and clear the account disabled flag for the target user.</LI>
061     *   <LI>Get, set, and clear the account expiration time for the target
062     *       user.</LI>
063     *   <LI>Get the length of time in seconds until the target user account
064     *       expires.</LI>
065     *   <LI>Get the time that the target user's password was last changed.</LI>
066     *   <LI>Get and clear the time that the first password expiration warning was
067     *       sent to the user.</LI>
068     *   <LI>Get the length of time in seconds until the target user's password
069     *       expires.</LI>
070     *   <LI>Get the length of time in seconds until the user should receive the
071     *       first warning about an upcoming password expiration.</LI>
072     *   <LI>Get, update, set, and clear the list of times that the target user has
073     *       unsuccessfully tried to authenticate since the last successful
074     *       authentication.</LI>
075     *   <LI>Get the number of remaining failed authentication attempts for the
076     *       target user before the account is locked.</LI>
077     *   <LI>Get the length of time in seconds until the target user's account is
078     *       automatically unlocked after it was locked due to failed authentication
079     *       attempts.</LI>
080     *   <LI>Get, set, and clear the time that the user last authenticated to the
081     *       server.</LI>
082     *   <LI>Get the length of time in seconds until the user account may be locked
083     *       after remaining idle.</LI>
084     *   <LI>Get, set, and clear the flag that controls whether the target user must
085     *       change his/her password before being allowed to perform any other
086     *       operations.</LI>
087     *   <LI>Get the length of time in seconds until the user's account is locked
088     *       after failing to change the password after an administrative
089     *       reset.</LI>
090     *   <LI>Get, update, set, and clear the times that the target user has
091     *       authenticated using a grace login after the password had expired.</LI>
092     *   <LI>Retrieve the number of remaining grace logins for the user.</LI>
093     *   <LI>Get, set, and clear the required password change time for the target
094     *       user.</LI>
095     *   <LI>Retrieve the length of time in seconds until the target user's account
096     *       will be locked as a result of failing to comply with a password change
097     *       by required time.</LI>
098     *   <LI>Get and clear the password history for the target user.</LI>
099     *   <LI>Get information about or purge a user's retired password.</LI>
100     * </UL>
101     * Note that many of these methods are dependent upon the password policy
102     * configuration for the target user and therefore some of them may not be
103     * applicable for some users.  For example, if password expiration is not
104     * enabled in the password policy associated with the target user, then
105     * operations that involve password expiration will have no effect and/or will
106     * have a return value that indicates that password expiration is not in effect.
107     */
108    @NotMutable()
109    @ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
110    public final class PasswordPolicyStateOperation
111           implements Serializable
112    {
113      /**
114       * The operation type that may be used to retrieve the DN of the password
115       * policy to which the user is subject.
116       */
117      public static final int OP_TYPE_GET_PW_POLICY_DN = 0;
118    
119    
120    
121      /**
122       * The operation type that may be used to determine whether the user account
123       * is disabled.
124       */
125      public static final int OP_TYPE_GET_ACCOUNT_DISABLED_STATE = 1;
126    
127    
128    
129      /**
130       * The operation type that may be used to specify whether the user account is
131       * disabled.
132       */
133      public static final int OP_TYPE_SET_ACCOUNT_DISABLED_STATE = 2;
134    
135    
136    
137      /**
138       * The operation type that may be used to clear the account disabled flag in
139       * the user's entry.
140       */
141      public static final int OP_TYPE_CLEAR_ACCOUNT_DISABLED_STATE = 3;
142    
143    
144    
145      /**
146       * The operation type that may be used to get the time that the user's account
147       * will expire.
148       */
149      public static final int OP_TYPE_GET_ACCOUNT_EXPIRATION_TIME = 4;
150    
151    
152    
153      /**
154       * The operation type that may be used to set the time that the user's account
155       * will expire.
156       */
157      public static final int OP_TYPE_SET_ACCOUNT_EXPIRATION_TIME = 5;
158    
159    
160    
161      /**
162       * The operation type that may be used to clear the user's account expiration
163       * time.
164       */
165      public static final int OP_TYPE_CLEAR_ACCOUNT_EXPIRATION_TIME = 6;
166    
167    
168    
169      /**
170       * The operation type that may be used to retrieve the length of time in
171       * seconds until the user's account expires.
172       */
173      public static final int OP_TYPE_GET_SECONDS_UNTIL_ACCOUNT_EXPIRATION = 7;
174    
175    
176    
177      /**
178       * The operation type that may be used to get the time that the user's
179       * password was last changed.
180       */
181      public static final int OP_TYPE_GET_PW_CHANGED_TIME = 8;
182    
183    
184    
185      /**
186       * The operation type that may be used to set the time that the user's
187       * password was last changed.
188       */
189      public static final int OP_TYPE_SET_PW_CHANGED_TIME = 9;
190    
191    
192    
193      /**
194       * The operation type that may be used to clear the password changed time in
195       * the user's account.
196       */
197      public static final int OP_TYPE_CLEAR_PW_CHANGED_TIME = 10;
198    
199    
200    
201      /**
202       * The operation type that may be used to get the time that the user was
203       * first sent a password expiration warning.
204       */
205      public static final int OP_TYPE_GET_PW_EXPIRATION_WARNED_TIME = 11;
206    
207    
208    
209      /**
210       * The operation type that may be used to set the time that the user was
211       * first sent a password expiration warning.
212       */
213      public static final int OP_TYPE_SET_PW_EXPIRATION_WARNED_TIME = 12;
214    
215    
216    
217      /**
218       * The operation type that may be used to clear the password expiration warned
219       * time from the user's entry.
220       */
221      public static final int OP_TYPE_CLEAR_PW_EXPIRATION_WARNED_TIME = 13;
222    
223    
224    
225      /**
226       * The operation type that may be used to get the length of time in seconds
227       * until the user's password expires.
228       */
229      public static final int OP_TYPE_GET_SECONDS_UNTIL_PW_EXPIRATION = 14;
230    
231    
232    
233      /**
234       * The operation type that may be used to get the length of time in seconds
235       * until the user will be eligible to receive a password expiration warning.
236       */
237      public static final int OP_TYPE_GET_SECONDS_UNTIL_PW_EXPIRATION_WARNING = 15;
238    
239    
240    
241      /**
242       * The operation type that may be used to get the set of times that the user
243       * has unsuccessfully tried to authenticate since the last successful attempt.
244       */
245      public static final int OP_TYPE_GET_AUTH_FAILURE_TIMES = 16;
246    
247    
248    
249      /**
250       * The operation type that may be used to add a new authentication failure
251       * time to the user's account.
252       */
253      public static final int OP_TYPE_ADD_AUTH_FAILURE_TIME = 17;
254    
255    
256    
257      /**
258       * The operation type that may be used to set the set of times that the user
259       * has unsuccessfully tried to authenticate since the last successful attempt.
260       */
261      public static final int OP_TYPE_SET_AUTH_FAILURE_TIMES = 18;
262    
263    
264    
265      /**
266       * The operation type that may be used to clear the authentication failure
267       * times in the user account.
268       */
269      public static final int OP_TYPE_CLEAR_AUTH_FAILURE_TIMES = 19;
270    
271    
272    
273      /**
274       * The operation type that may be used to retrieve the length of time in
275       * seconds until the user's account is unlocked.
276       */
277      public static final int OP_TYPE_GET_SECONDS_UNTIL_AUTH_FAILURE_UNLOCK = 20;
278    
279    
280    
281      /**
282       * The operation type that may be used to retrieve the number of failed
283       * authentication attempts that the user has before the account is locked.
284       */
285      public static final int OP_TYPE_GET_REMAINING_AUTH_FAILURE_COUNT = 21;
286    
287    
288    
289      /**
290       * The operation type that may be used to retrieve the time that the user last
291       * authenticated to the server.
292       */
293      public static final int OP_TYPE_GET_LAST_LOGIN_TIME = 22;
294    
295    
296    
297      /**
298       * The operation type that may be used to set the time that the user last
299       * authenticated to the server.
300       */
301      public static final int OP_TYPE_SET_LAST_LOGIN_TIME = 23;
302    
303    
304    
305      /**
306       * The operation type that may be used to clear the last login time in the
307       * user's entry.
308       */
309      public static final int OP_TYPE_CLEAR_LAST_LOGIN_TIME = 24;
310    
311    
312    
313      /**
314       * The operation type that may be used to get the length of time in seconds
315       * until the user account is locked due to inactivity.
316       */
317      public static final int OP_TYPE_GET_SECONDS_UNTIL_IDLE_LOCKOUT = 25;
318    
319    
320    
321      /**
322       * The operation type that may be used to determine whether a user's password
323       * has been reset by an administrator and must be changed.
324       */
325      public static final int OP_TYPE_GET_PW_RESET_STATE = 26;
326    
327    
328    
329      /**
330       * The operation type that may be used to set the flag to indicate whether a
331       * user's password has been reset by an administrator and must be changed.
332       */
333      public static final int OP_TYPE_SET_PW_RESET_STATE = 27;
334    
335    
336    
337      /**
338       * The operation type that may be used to clear the password reset flag in the
339       * user's entry.
340       */
341      public static final int OP_TYPE_CLEAR_PW_RESET_STATE = 28;
342    
343    
344    
345      /**
346       * The operation type that may be used to get the length of time in seconds
347       * until the user's account is locked due to failure to change the password
348       * after an administrative reset.
349       */
350      public static final int OP_TYPE_GET_SECONDS_UNTIL_PW_RESET_LOCKOUT = 29;
351    
352    
353    
354      /**
355       * The operation type that may be used to retrieve the times that the user has
356       * authenticated using a grace login after his/her password has expired.
357       */
358      public static final int OP_TYPE_GET_GRACE_LOGIN_USE_TIMES = 30;
359    
360    
361    
362      /**
363       * The operation type that may be used add a value to the set of times that
364       * the user has authenticated using a grace login after his/her password has
365       * expired.
366       */
367      public static final int OP_TYPE_ADD_GRACE_LOGIN_USE_TIME = 31;
368    
369    
370    
371      /**
372       * The operation type that may be used to set the times that the user has
373       * authenticated using a grace login after his/her password has expired.
374       */
375      public static final int OP_TYPE_SET_GRACE_LOGIN_USE_TIMES = 32;
376    
377    
378    
379      /**
380       * The operation type that may be used to clear the set of times that the user
381       * has authenticated using a grace login after his/her password has expired.
382       */
383      public static final int OP_TYPE_CLEAR_GRACE_LOGIN_USE_TIMES = 33;
384    
385    
386    
387      /**
388       * The operation type that may be used to retrieve the number of grace logins
389       * available for the user.
390       */
391      public static final int OP_TYPE_GET_REMAINING_GRACE_LOGIN_COUNT = 34;
392    
393    
394    
395      /**
396       * The operation type that may be used to retrieve the last time that the
397       * user's password was changed during a required change period.
398       */
399      public static final int OP_TYPE_GET_PW_CHANGED_BY_REQUIRED_TIME = 35;
400    
401    
402    
403      /**
404       * The operation type that may be used to set the last time that the
405       * user's password was changed during a required change period.
406       */
407      public static final int OP_TYPE_SET_PW_CHANGED_BY_REQUIRED_TIME = 36;
408    
409    
410    
411      /**
412       * The operation type that may be used to clear the last time that the
413       * user's password was changed during a required change period.
414       */
415      public static final int OP_TYPE_CLEAR_PW_CHANGED_BY_REQUIRED_TIME = 37;
416    
417    
418    
419      /**
420       * The operation type that may be used to get the length of time in seconds
421       * until the user's account will be locked due to a failure to change the
422       * password by a required time.
423       */
424      public static final int OP_TYPE_GET_SECONDS_UNTIL_REQUIRED_CHANGE_TIME = 38;
425    
426    
427    
428      /**
429       * The operation type that may be used to retrieve the stored password history
430       * values for a user.
431       */
432      public static final int OP_TYPE_GET_PW_HISTORY = 39;
433    
434    
435    
436      /**
437       * The operation type that may be used to clear the stored password history
438       * values for a user.
439       */
440      public static final int OP_TYPE_CLEAR_PW_HISTORY = 40;
441    
442    
443    
444      /**
445       * The operation type that may be used to determine whether a user has a valid
446       * retired password.
447       */
448      public static final int OP_TYPE_HAS_RETIRED_PASSWORD = 41;
449    
450    
451    
452      /**
453       * The operation type that may be used to retrieve the time that the user's
454       * former password was retired.
455       */
456      public static final int OP_TYPE_GET_PASSWORD_RETIRED_TIME = 42;
457    
458    
459    
460      /**
461       * The operation type that may be used to retrieve the time that the user's
462       * retired password will expire.
463       */
464      public static final int OP_TYPE_GET_RETIRED_PASSWORD_EXPIRATION_TIME = 43;
465    
466    
467    
468      /**
469       * The operation type that may be used to purge any retired password from the
470       * user's entry.
471       */
472      public static final int OP_TYPE_PURGE_RETIRED_PASSWORD = 44;
473    
474    
475    
476      /**
477       * The set of values that will be used if there are no values.
478       */
479      private static final ASN1OctetString[] NO_VALUES = new ASN1OctetString[0];
480    
481    
482    
483      /**
484       * The serial version UID for this serializable class.
485       */
486      private static final long serialVersionUID = -7430165299583556387L;
487    
488    
489    
490      // The set of values for this operation.
491      private final ASN1OctetString[] values;
492    
493      // The operation type for this operation.
494      private final int opType;
495    
496    
497    
498      /**
499       * Creates a new password policy state operation with the specified operation
500       * type and no values.
501       *
502       * @param  opType  The operation type for this password policy state
503       *                 operation.
504       */
505      public PasswordPolicyStateOperation(final int opType)
506      {
507        this(opType, NO_VALUES);
508      }
509    
510    
511    
512      /**
513       * Creates a new password policy state operation with the specified operation
514       * type and set of values.
515       *
516       * @param  opType  The operation type for this password policy state
517       *                 operation.
518       * @param  values  The set of values for this password policy state operation.
519       */
520      public PasswordPolicyStateOperation(final int opType,
521                                          final ASN1OctetString[] values)
522      {
523        this.opType = opType;
524    
525        if (values == null)
526        {
527          this.values = NO_VALUES;
528        }
529        else
530        {
531          this.values = values;
532        }
533      }
534    
535    
536    
537      /**
538       * Creates a new password policy state operation that may be used to request
539       * the DN of the password policy configuration entry for the user.
540       *
541       * @return  The created password policy state operation.
542       */
543      public static PasswordPolicyStateOperation
544           createGetPasswordPolicyDNOperation()
545      {
546        return new PasswordPolicyStateOperation(OP_TYPE_GET_PW_POLICY_DN);
547      }
548    
549    
550    
551      /**
552       * Creates a new password policy state operation that may be used to determine
553       * whether the user account is disabled.
554       *
555       * @return  The created password policy state operation.
556       */
557      public static PasswordPolicyStateOperation
558           createGetAccountDisabledStateOperation()
559      {
560        return new PasswordPolicyStateOperation(OP_TYPE_GET_ACCOUNT_DISABLED_STATE);
561      }
562    
563    
564    
565      /**
566       * Creates a new password policy state operation that may be used to specify
567       * whether the user account is disabled.
568       *
569       * @param  isDisabled  Indicates whether the user account should be disabled.
570       *
571       * @return  The created password policy state operation.
572       */
573      public static PasswordPolicyStateOperation
574           createSetAccountDisabledStateOperation(final boolean isDisabled)
575      {
576        final ASN1OctetString[] values =
577        {
578          new ASN1OctetString(String.valueOf(isDisabled))
579        };
580    
581        return new PasswordPolicyStateOperation(OP_TYPE_SET_ACCOUNT_DISABLED_STATE,
582                                                values);
583      }
584    
585    
586    
587      /**
588       * Creates a new password policy state operation that may be used to clear
589       * the user account disabled state in the user's entry.
590       *
591       * @return  The created password policy state operation.
592       */
593      public static PasswordPolicyStateOperation
594           createClearAccountDisabledStateOperation()
595      {
596        return new PasswordPolicyStateOperation(
597                        OP_TYPE_CLEAR_ACCOUNT_DISABLED_STATE);
598      }
599    
600    
601    
602      /**
603       * Creates a new password policy state operation that may be used to retrieve
604       * the time that the user's account expires.
605       *
606       * @return  The created password policy state operation.
607       */
608      public static PasswordPolicyStateOperation
609           createGetAccountExpirationTimeOperation()
610      {
611        return new PasswordPolicyStateOperation(
612                        OP_TYPE_GET_ACCOUNT_EXPIRATION_TIME);
613      }
614    
615    
616    
617      /**
618       * Creates a new password policy state operation that may be used to set the
619       * time that the user's account expires.
620       *
621       * @param  expirationTime  The time that the user's account should expire.
622       *
623       * @return  The created password policy state operation.
624       */
625      public static PasswordPolicyStateOperation
626           createSetAccountExpirationTimeOperation(final Date expirationTime)
627      {
628        final ASN1OctetString[] values =
629        {
630          new ASN1OctetString(encodeGeneralizedTime(expirationTime))
631        };
632    
633        return new PasswordPolicyStateOperation(OP_TYPE_SET_ACCOUNT_EXPIRATION_TIME,
634                                                values);
635      }
636    
637    
638    
639      /**
640       * Creates a new password policy state operation that may be used to clear
641       * the account expiration time in the user's entry.
642       *
643       * @return  The created password policy state operation.
644       */
645      public static PasswordPolicyStateOperation
646           createClearAccountExpirationTimeOperation()
647      {
648        return new PasswordPolicyStateOperation(
649                        OP_TYPE_CLEAR_ACCOUNT_EXPIRATION_TIME);
650      }
651    
652    
653    
654      /**
655       * Creates a new password policy state operation that may be used to determine
656       * the length of time in seconds until the user's account is expired.
657       *
658       * @return  The created password policy state operation.
659       */
660      public static PasswordPolicyStateOperation
661           createGetSecondsUntilAccountExpirationOperation()
662      {
663        return new PasswordPolicyStateOperation(
664                        OP_TYPE_GET_SECONDS_UNTIL_ACCOUNT_EXPIRATION);
665      }
666    
667    
668    
669      /**
670       * Creates a new password policy state operation that may be used to determine
671       * when the user's password was last changed.
672       *
673       * @return  The created password policy state operation.
674       */
675      public static PasswordPolicyStateOperation
676           createGetPasswordChangedTimeOperation()
677      {
678        return new PasswordPolicyStateOperation(OP_TYPE_GET_PW_CHANGED_TIME);
679      }
680    
681    
682    
683      /**
684       * Creates a new password policy state operation that may be used to determine
685       * when the user first received a password expiration warning.
686       *
687       * @return  The created password policy state operation.
688       */
689      public static PasswordPolicyStateOperation
690           createGetPasswordExpirationWarnedTimeOperation()
691      {
692        return new PasswordPolicyStateOperation(
693                        OP_TYPE_GET_PW_EXPIRATION_WARNED_TIME);
694      }
695    
696    
697    
698      /**
699       * Creates a new password policy state operation that may be used to clear the
700       * password expiration warned time from the user's entry.
701       *
702       * @return  The created password policy state operation.
703       */
704      public static PasswordPolicyStateOperation
705           createClearPasswordExpirationWarnedTimeOperation()
706      {
707        return new PasswordPolicyStateOperation(
708                        OP_TYPE_CLEAR_PW_EXPIRATION_WARNED_TIME);
709      }
710    
711    
712    
713      /**
714       * Creates a new password policy state operation that may be used to determine
715       * the length of time in seconds until the user's password expires.
716       *
717       * @return  The created password policy state operation.
718       */
719      public static PasswordPolicyStateOperation
720           createGetSecondsUntilPasswordExpirationOperation()
721      {
722        return new PasswordPolicyStateOperation(
723                        OP_TYPE_GET_SECONDS_UNTIL_PW_EXPIRATION);
724      }
725    
726    
727    
728      /**
729       * Creates a new password policy state operation that may be used to determine
730       * the length of time in seconds until the user is eligible to start receiving
731       * password expiration warnings.
732       *
733       * @return  The created password policy state operation.
734       */
735      public static PasswordPolicyStateOperation
736           createGetSecondsUntilPasswordExpirationWarningOperation()
737      {
738        return new PasswordPolicyStateOperation(
739                        OP_TYPE_GET_SECONDS_UNTIL_PW_EXPIRATION_WARNING);
740      }
741    
742    
743    
744      /**
745       * Creates a new password policy state operation that may be used to retrieve
746       * the times that the user has unsuccessfully tried to authenticate since the
747       * last successful authentication.
748       *
749       * @return  The created password policy state operation.
750       */
751      public static PasswordPolicyStateOperation
752           createGetAuthenticationFailureTimesOperation()
753      {
754        return new PasswordPolicyStateOperation(OP_TYPE_GET_AUTH_FAILURE_TIMES);
755      }
756    
757    
758    
759      /**
760       * Creates a new password policy state operation that may be used to add the
761       * current time to the set of times that the user has unsuccessfully tried to
762       * authenticate since the last successful authentication.
763       *
764       * @return  The created password policy state operation.
765       */
766      public static PasswordPolicyStateOperation
767           createAddAuthenticationFailureTimeOperation()
768      {
769        final ASN1OctetString[] values =
770        {
771          new ASN1OctetString(encodeGeneralizedTime(new Date()))
772        };
773    
774        return new PasswordPolicyStateOperation(OP_TYPE_ADD_AUTH_FAILURE_TIME,
775                                                values);
776      }
777    
778    
779    
780      /**
781       * Creates a new password policy state operation that may be used to specify
782       * the set of times that the user has unsuccessfully tried to authenticate
783       * since the last successful authentication.
784       *
785       * @param  authFailureTimes  The set of times that the user has unsuccessfully
786       *                           tried to authenticate since the last successful
787       *                           authentication.
788       *
789       * @return  The created password policy state operation.
790       */
791      public static PasswordPolicyStateOperation
792           createSetAuthenticationFailureTimesOperation(
793                final Date[] authFailureTimes)
794      {
795        final ASN1OctetString[] values;
796        if ((authFailureTimes == null) || (authFailureTimes.length == 0))
797        {
798          values = NO_VALUES;
799        }
800        else
801        {
802          values = new ASN1OctetString[authFailureTimes.length];
803          for (int i=0; i < authFailureTimes.length; i++)
804          {
805            values[i] =
806                 new ASN1OctetString(encodeGeneralizedTime(authFailureTimes[i]));
807          }
808        }
809    
810        return new PasswordPolicyStateOperation(OP_TYPE_SET_AUTH_FAILURE_TIMES,
811                                                values);
812      }
813    
814    
815    
816      /**
817       * Creates a new password policy state operation that may be used to clear the
818       * set of times that the user has unsuccessfully tried to authenticate since
819       * the last successful authentication.
820       *
821       * @return  The created password policy state operation.
822       */
823      public static PasswordPolicyStateOperation
824           createClearAuthenticationFailureTimesOperation()
825      {
826        return new PasswordPolicyStateOperation(OP_TYPE_CLEAR_AUTH_FAILURE_TIMES);
827      }
828    
829    
830    
831      /**
832       * Creates a new password policy state operation that may be used to determine
833       * the length of time in seconds until the user's account is automatically
834       * unlocked after too many failed authentication attempts.
835       *
836       * @return  The created password policy state operation.
837       */
838      public static PasswordPolicyStateOperation
839           createGetSecondsUntilAuthenticationFailureUnlockOperation()
840      {
841        return new PasswordPolicyStateOperation(
842                        OP_TYPE_GET_SECONDS_UNTIL_AUTH_FAILURE_UNLOCK);
843      }
844    
845    
846    
847      /**
848       * Creates a new password policy state operation that may be used to determine
849       * the number of authentication failures required to lock the user's account.
850       *
851       * @return  The created password policy state operation.
852       */
853      public static PasswordPolicyStateOperation
854           createGetRemainingAuthenticationFailureCountOperation()
855      {
856        return new PasswordPolicyStateOperation(
857                        OP_TYPE_GET_REMAINING_AUTH_FAILURE_COUNT);
858      }
859    
860    
861    
862      /**
863       * Creates a new password policy state operation that may be used to determine
864       * the time that the user last successfully authenticated to the server.
865       *
866       * @return  The created password policy state operation.
867       */
868      public static PasswordPolicyStateOperation createGetLastLoginTimeOperation()
869      {
870        return new PasswordPolicyStateOperation(OP_TYPE_GET_LAST_LOGIN_TIME);
871      }
872    
873    
874    
875      /**
876       * Creates a new password policy state operation that may be used to set
877       * the time that the user last successfully authenticated to the server.
878       *
879       * @param  lastLoginTime  The last login time to set in the user's entry.
880       *
881       * @return  The created password policy state operation.
882       */
883      public static PasswordPolicyStateOperation
884           createSetLastLoginTimeOperation(final Date lastLoginTime)
885      {
886        final ASN1OctetString[] values =
887        {
888          new ASN1OctetString(encodeGeneralizedTime(lastLoginTime))
889        };
890    
891        return new PasswordPolicyStateOperation(OP_TYPE_SET_LAST_LOGIN_TIME,
892                                                values);
893      }
894    
895    
896    
897      /**
898       * Creates a new password policy state operation that may be used to clear
899       * the last login time time from the user's entry.
900       *
901       * @return  The created password policy state operation.
902       */
903      public static PasswordPolicyStateOperation createClearLastLoginTimeOperation()
904      {
905        return new PasswordPolicyStateOperation(OP_TYPE_CLEAR_LAST_LOGIN_TIME);
906      }
907    
908    
909    
910      /**
911       * Creates a new password policy state operation that may be used to determine
912       * the length of time in seconds until the user's account is locked due to
913       * inactivity.
914       *
915       * @return  The created password policy state operation.
916       */
917      public static PasswordPolicyStateOperation
918           createGetSecondsUntilIdleLockoutOperation()
919      {
920        return new PasswordPolicyStateOperation(
921                        OP_TYPE_GET_SECONDS_UNTIL_IDLE_LOCKOUT);
922      }
923    
924    
925    
926      /**
927       * Creates a new password policy state operation that may be used to determine
928       * whether the user's password has been reset by an administrator and must be
929       * changed before performing any other operations.
930       *
931       * @return  The created password policy state operation.
932       */
933      public static PasswordPolicyStateOperation
934           createGetPasswordResetStateOperation()
935      {
936        return new PasswordPolicyStateOperation(OP_TYPE_GET_PW_RESET_STATE);
937      }
938    
939    
940    
941      /**
942       * Creates a new password policy state operation that may be used to specify
943       * whether the user's password has been reset by an administrator and must be
944       * changed before performing any other operations.
945       *
946       * @param  isReset  Specifies whether the user's password must be changed
947       *                  before performing any other operations.
948       *
949       * @return  The created password policy state operation.
950       */
951      public static PasswordPolicyStateOperation
952           createSetPasswordResetStateOperation(final boolean isReset)
953      {
954        final ASN1OctetString[] values =
955        {
956          new ASN1OctetString(String.valueOf(isReset))
957        };
958    
959        return new PasswordPolicyStateOperation(OP_TYPE_SET_PW_RESET_STATE, values);
960      }
961    
962    
963    
964      /**
965       * Creates a new password policy state operation that may be used to clear the
966       * password reset state information in the user's entry.
967       *
968       * @return  The created password policy state operation.
969       */
970      public static PasswordPolicyStateOperation
971           createClearPasswordResetStateOperation()
972      {
973        return new PasswordPolicyStateOperation(OP_TYPE_CLEAR_PW_RESET_STATE);
974      }
975    
976    
977    
978      /**
979       * Creates a new password policy state operation that may be used to determine
980       * the length of time in seconds that the user has left to change his/her
981       * password after an administrative reset before the account is locked.
982       *
983       * @return  The created password policy state operation.
984       */
985      public static PasswordPolicyStateOperation
986           createGetSecondsUntilPasswordResetLockoutOperation()
987      {
988        return new PasswordPolicyStateOperation(
989                        OP_TYPE_GET_SECONDS_UNTIL_PW_RESET_LOCKOUT);
990      }
991    
992    
993    
994      /**
995       * Creates a new password policy state operation that may be used to retrieve
996       * the set of times that the user has authenticated using grace logins since
997       * his/her password expired.
998       *
999       * @return  The created password policy state operation.
1000       */
1001      public static PasswordPolicyStateOperation
1002           createGetGraceLoginUseTimesOperation()
1003      {
1004        return new PasswordPolicyStateOperation(OP_TYPE_GET_GRACE_LOGIN_USE_TIMES);
1005      }
1006    
1007    
1008    
1009      /**
1010       * Creates a new password policy state operation that may be used to add the
1011       * current time to the set of times that the user has authenticated using
1012       * grace logins since his/her password expired.
1013       *
1014       * @return  The created password policy state operation.
1015       */
1016      public static PasswordPolicyStateOperation
1017           createAddGraceLoginUseTimeOperation()
1018      {
1019        final ASN1OctetString[] values =
1020        {
1021          new ASN1OctetString(encodeGeneralizedTime(new Date()))
1022        };
1023    
1024        return new PasswordPolicyStateOperation(OP_TYPE_ADD_GRACE_LOGIN_USE_TIME,
1025                                                values);
1026      }
1027    
1028    
1029    
1030      /**
1031       * Creates a new password policy state operation that may be used to specify
1032       * the set of times that the user has authenticated using grace logins since
1033       * his/her password expired.
1034       *
1035       * @param  graceLoginUseTimes  The set of times that the user has
1036       *                             authenticated using grace logins since his/her
1037       *                             password expired.
1038       *
1039       * @return  The created password policy state operation.
1040       */
1041      public static PasswordPolicyStateOperation
1042           createSetGraceLoginUseTimesOperation(final Date[] graceLoginUseTimes)
1043      {
1044        final ASN1OctetString[] values;
1045        if ((graceLoginUseTimes == null) || (graceLoginUseTimes.length == 0))
1046        {
1047          values = NO_VALUES;
1048        }
1049        else
1050        {
1051          values = new ASN1OctetString[graceLoginUseTimes.length];
1052          for (int i=0; i < graceLoginUseTimes.length; i++)
1053          {
1054            values[i] =
1055                 new ASN1OctetString(encodeGeneralizedTime(graceLoginUseTimes[i]));
1056          }
1057        }
1058    
1059        return new PasswordPolicyStateOperation(OP_TYPE_SET_GRACE_LOGIN_USE_TIMES,
1060                                                values);
1061      }
1062    
1063    
1064    
1065      /**
1066       * Creates a new password policy state operation that may be used to clear
1067       * the set of times that the user has authenticated using grace logins since
1068       * his/her password expired.
1069       *
1070       * @return  The created password policy state operation.
1071       */
1072      public static PasswordPolicyStateOperation
1073           createClearGraceLoginUseTimesOperation()
1074      {
1075        return new PasswordPolicyStateOperation(
1076                        OP_TYPE_CLEAR_GRACE_LOGIN_USE_TIMES);
1077      }
1078    
1079    
1080    
1081      /**
1082       * Creates a new password policy state operation that may be used to retrieve
1083       * the number of remaining grace logins available to the user.
1084       *
1085       * @return  The created password policy state operation.
1086       */
1087      public static PasswordPolicyStateOperation
1088           createGetRemainingGraceLoginCountOperation()
1089      {
1090        return new PasswordPolicyStateOperation(
1091                        OP_TYPE_GET_REMAINING_GRACE_LOGIN_COUNT);
1092      }
1093    
1094    
1095    
1096      /**
1097       * Creates a new password policy state operation that may be used to retrieve
1098       * the last required password change time that with which the user has
1099       * complied.
1100       *
1101       * @return  The created password policy state operation.
1102       */
1103      public static PasswordPolicyStateOperation
1104           createGetPasswordChangedByRequiredTimeOperation()
1105      {
1106        return new PasswordPolicyStateOperation(
1107                        OP_TYPE_GET_PW_CHANGED_BY_REQUIRED_TIME);
1108      }
1109    
1110    
1111    
1112      /**
1113       * Creates a new password policy state operation that may be used to update
1114       * the user's entry to indicate that he/she has complied with the required
1115       * password change time.
1116       *
1117       * @return  The created password policy state operation.
1118       */
1119      public static PasswordPolicyStateOperation
1120           createSetPasswordChangedByRequiredTimeOperation()
1121      {
1122        return new PasswordPolicyStateOperation(
1123                        OP_TYPE_SET_PW_CHANGED_BY_REQUIRED_TIME);
1124      }
1125    
1126    
1127    
1128      /**
1129       * Creates a new password policy state operation that may be used to clear
1130       * the last required password change time from the user's entry.
1131       *
1132       * @return  The created password policy state operation.
1133       */
1134      public static PasswordPolicyStateOperation
1135           createClearPasswordChangedByRequiredTimeOperation()
1136      {
1137        return new PasswordPolicyStateOperation(
1138                        OP_TYPE_CLEAR_PW_CHANGED_BY_REQUIRED_TIME);
1139      }
1140    
1141    
1142    
1143      /**
1144       * Creates a new password policy state operation that may be used to retrieve
1145       * the length of time in seconds until the required password change time
1146       * arrives.
1147       *
1148       * @return  The created password policy state operation.
1149       */
1150      public static PasswordPolicyStateOperation
1151           createGetSecondsUntilRequiredChangeTimeOperation()
1152      {
1153        return new PasswordPolicyStateOperation(
1154                        OP_TYPE_GET_SECONDS_UNTIL_REQUIRED_CHANGE_TIME);
1155      }
1156    
1157    
1158    
1159      /**
1160       * Creates a new password policy state operation that may be used to retrieve
1161       * the password history values stored in the user's entry.
1162       *
1163       * @return  The created password policy state operation.
1164       */
1165      public static PasswordPolicyStateOperation createGetPasswordHistoryOperation()
1166      {
1167        return new PasswordPolicyStateOperation(OP_TYPE_GET_PW_HISTORY);
1168      }
1169    
1170    
1171    
1172      /**
1173       * Creates a new password policy state operation that may be used to clear the
1174       * password history values stored in the user's entry.
1175       *
1176       * @return  The created password policy state operation.
1177       */
1178      public static PasswordPolicyStateOperation
1179           createClearPasswordHistoryOperation()
1180      {
1181        return new PasswordPolicyStateOperation(OP_TYPE_CLEAR_PW_HISTORY);
1182      }
1183    
1184    
1185    
1186      /**
1187       * Creates a new password policy state operation that may be used to determine
1188       * whether the user has a valid retired password.
1189       *
1190       * @return  The created password policy state operation.
1191       */
1192      public static PasswordPolicyStateOperation createHasRetiredPasswordOperation()
1193      {
1194        return new PasswordPolicyStateOperation(OP_TYPE_HAS_RETIRED_PASSWORD);
1195      }
1196    
1197    
1198    
1199      /**
1200       * Creates a new password policy state operation that may be used to determine
1201       * the time that the user's former password was retired.
1202       *
1203       * @return  The created password policy state operation.
1204       */
1205      public static PasswordPolicyStateOperation
1206                         createGetPasswordRetiredTimeOperation()
1207      {
1208        return new PasswordPolicyStateOperation(OP_TYPE_GET_PASSWORD_RETIRED_TIME);
1209      }
1210    
1211    
1212    
1213      /**
1214       * Creates a new password policy state operation that may be used to determine
1215       * the length of time until the user's retired password expires.
1216       *
1217       * @return  The created password policy state operation.
1218       */
1219      public static PasswordPolicyStateOperation
1220                         createGetRetiredPasswordExpirationTimeOperation()
1221      {
1222        return new PasswordPolicyStateOperation(
1223             OP_TYPE_GET_RETIRED_PASSWORD_EXPIRATION_TIME);
1224      }
1225    
1226    
1227    
1228      /**
1229       * Creates a new password policy state operation that may be used to purge
1230       * any retired password from the user's entry.
1231       *
1232       * @return  The created password policy state operation.
1233       */
1234      public static PasswordPolicyStateOperation
1235                         createPurgeRetiredPasswordOperation()
1236      {
1237        return new PasswordPolicyStateOperation(OP_TYPE_PURGE_RETIRED_PASSWORD);
1238      }
1239    
1240    
1241    
1242      /**
1243       * Retrieves the operation type for this password policy state operation.
1244       *
1245       * @return  The operation type for this password policy state operation.
1246       */
1247      public int getOperationType()
1248      {
1249        return opType;
1250      }
1251    
1252    
1253    
1254      /**
1255       * Retrieves the set of raw values for this password policy state operation.
1256       *
1257       * @return  The set of raw values for this password policy state operation.
1258       */
1259      public ASN1OctetString[] getRawValues()
1260      {
1261        return values;
1262      }
1263    
1264    
1265    
1266      /**
1267       * Retrieves the string representation of the value for this password policy
1268       * state operation.  If there are multiple values, then the first will be
1269       * returned.
1270       *
1271       * @return  The string representation of the value for this password policy
1272       *          state operation, or {@code null} if there are no values.
1273       */
1274      public String getStringValue()
1275      {
1276        if (values.length == 0)
1277        {
1278          return null;
1279        }
1280        else
1281        {
1282          return values[0].stringValue();
1283        }
1284      }
1285    
1286    
1287    
1288      /**
1289       * Retrieves the string representations of the values for this password policy
1290       * state operation.
1291       *
1292       * @return  The string representations of the values for this password policy
1293       *          state operation.
1294       */
1295      public String[] getStringValues()
1296      {
1297        final String[] stringValues = new String[values.length];
1298        for (int i=0; i < values.length; i++)
1299        {
1300          stringValues[i] = values[i].stringValue();
1301        }
1302    
1303        return stringValues;
1304      }
1305    
1306    
1307    
1308      /**
1309       * Retrieves the boolean representation of the value for this password policy
1310       * state operation.
1311       *
1312       * @return  The boolean representation of the value for this password policy
1313       *          state operation.
1314       *
1315       * @throws  IllegalStateException  If this operation does not have exactly one
1316       *                                 value, or if the value cannot be decoded as
1317       *                                 a boolean value.
1318       */
1319      public boolean getBooleanValue()
1320             throws IllegalStateException
1321      {
1322        if (values.length != 1)
1323        {
1324          throw new IllegalStateException(
1325               ERR_PWP_STATE_INVALID_BOOLEAN_VALUE_COUNT.get(values.length));
1326        }
1327    
1328        final String valueString = toLowerCase(values[0].stringValue());
1329        if (valueString.equals("true"))
1330        {
1331          return true;
1332        }
1333        else if (valueString.equals("false"))
1334        {
1335          return false;
1336        }
1337        else
1338        {
1339          throw new IllegalStateException(
1340               ERR_PWP_STATE_VALUE_NOT_BOOLEAN.get(values[0].stringValue()));
1341        }
1342      }
1343    
1344    
1345    
1346      /**
1347       * Retrieves the integer representation of the value for this password policy
1348       * state operation.  If there are multiple values, then the first will be
1349       * returned.
1350       *
1351       * @return  The integer representation of the value for this password policy
1352       *          operation.
1353       *
1354       * @throws  IllegalStateException  If this operation does not have any values.
1355       *
1356       * @throws  NumberFormatException  If the value cannot be parsed as an
1357       *                                 integer.
1358       */
1359      public int getIntValue()
1360             throws IllegalStateException, NumberFormatException
1361      {
1362        if (values.length == 0)
1363        {
1364          throw new IllegalStateException(ERR_PWP_STATE_NO_VALUES.get());
1365        }
1366    
1367        return Integer.parseInt(values[0].stringValue());
1368      }
1369    
1370    
1371    
1372      /**
1373       * Retrieves the {@code Date} object represented by the value for this
1374       * password policy state operation treated as a timestamp in generalized time
1375       * form.  If there are multiple values, then the first will be returned.
1376       *
1377       * @return  The {@code Date} object represented by the value for this password
1378       *          policy state operation treated as a timestamp in generalized time
1379       *          form, or {@code null} if this operation does not have any values.
1380       *
1381       * @throws  ParseException  If the value cannot be decoded as a timestamp in
1382       *                          generalized time form.
1383       */
1384      public Date getGeneralizedTimeValue()
1385             throws ParseException
1386      {
1387        if (values.length == 0)
1388        {
1389          return null;
1390        }
1391    
1392        return decodeGeneralizedTime(values[0].stringValue());
1393      }
1394    
1395    
1396    
1397      /**
1398       * Retrieves the {@code Date} objects represented by the values for this
1399       * password policy state operation treated as timestamps in generalized time
1400       * form.
1401       *
1402       * @return  The {@code Date} objects represented by the values for this
1403       *          password policy state operation treated as timestamps in
1404       *          generalized time form.
1405       *
1406       * @throws  ParseException  If any of the values cannot be decoded as a
1407       *                          timestamp in generalized time form.
1408       */
1409      public Date[] getGeneralizedTimeValues()
1410             throws ParseException
1411      {
1412        final Date[] dateValues = new Date[values.length];
1413        for (int i=0; i < values.length; i++)
1414        {
1415          dateValues[i] = decodeGeneralizedTime(values[i].stringValue());
1416        }
1417    
1418        return dateValues;
1419      }
1420    
1421    
1422    
1423      /**
1424       * Encodes this password policy state operation for use in the extended
1425       * request or response.
1426       *
1427       * @return  An ASN.1 element containing an encoded representation of this
1428       *          password policy state operation.
1429       */
1430      public ASN1Element encode()
1431      {
1432        final ASN1Element[] elements;
1433        if (values.length > 0)
1434        {
1435          elements = new ASN1Element[]
1436          {
1437            new ASN1Enumerated(opType),
1438            new ASN1Sequence(values)
1439          };
1440        }
1441        else
1442        {
1443          elements = new ASN1Element[]
1444          {
1445            new ASN1Enumerated(opType),
1446          };
1447        }
1448    
1449        return new ASN1Sequence(elements);
1450      }
1451    
1452    
1453    
1454      /**
1455       * Decodes the provided ASN.1 element as a password policy state operation.
1456       *
1457       * @param  element  The ASN.1 element to be decoded.
1458       *
1459       * @return  The decoded password policy state operation.
1460       *
1461       * @throws  LDAPException  If a problem occurs while attempting to decode the
1462       *                         provided ASN.1 element as a password policy state
1463       *                         operation.
1464       */
1465      public static PasswordPolicyStateOperation decode(final ASN1Element element)
1466             throws LDAPException
1467      {
1468        final ASN1Element[] elements;
1469        try
1470        {
1471          elements = ASN1Sequence.decodeAsSequence(element).elements();
1472        }
1473        catch (Exception e)
1474        {
1475          debugException(e);
1476          throw new LDAPException(ResultCode.DECODING_ERROR,
1477                                  ERR_PWP_STATE_ELEMENT_NOT_SEQUENCE.get(e), e);
1478        }
1479    
1480        if ((elements.length < 1) || (elements.length > 2))
1481        {
1482          throw new LDAPException(ResultCode.DECODING_ERROR,
1483                                  ERR_PWP_STATE_INVALID_ELEMENT_COUNT.get(
1484                                       elements.length));
1485        }
1486    
1487        final int opType;
1488        try
1489        {
1490          opType = ASN1Enumerated.decodeAsEnumerated(elements[0]).intValue();
1491        }
1492        catch (Exception e)
1493        {
1494          debugException(e);
1495          throw new LDAPException(ResultCode.DECODING_ERROR,
1496                                  ERR_PWP_STATE_OP_TYPE_NOT_INTEGER.get(e), e);
1497        }
1498    
1499        final ASN1OctetString[] values;
1500        if (elements.length == 2)
1501        {
1502          try
1503          {
1504            final ASN1Element[] valueElements =
1505                 ASN1Sequence.decodeAsSequence(elements[1]).elements();
1506            values = new ASN1OctetString[valueElements.length];
1507            for (int i=0; i < valueElements.length; i++)
1508            {
1509              values[i] = ASN1OctetString.decodeAsOctetString(valueElements[i]);
1510            }
1511          }
1512          catch (Exception e)
1513          {
1514            debugException(e);
1515            throw new LDAPException(ResultCode.DECODING_ERROR,
1516                                    ERR_PWP_STATE_CANNOT_DECODE_VALUES.get(e), e);
1517          }
1518        }
1519        else
1520        {
1521          values = NO_VALUES;
1522        }
1523    
1524        return new PasswordPolicyStateOperation(opType, values);
1525      }
1526    
1527    
1528    
1529      /**
1530       * Retrieves a string representation of this password policy state operation.
1531       *
1532       * @return  A string representation of this password policy state operation.
1533       */
1534      @Override()
1535      public String toString()
1536      {
1537        final StringBuilder buffer = new StringBuilder();
1538        toString(buffer);
1539        return buffer.toString();
1540      }
1541    
1542    
1543    
1544      /**
1545       * Appends a string representation of this password policy state operation to
1546       * the provided buffer.
1547       *
1548       * @param  buffer  The buffer to which the information should be appended.
1549       */
1550      public void toString(final StringBuilder buffer)
1551      {
1552        buffer.append("PasswordPolicyStateOperation(opType=");
1553        buffer.append(opType);
1554    
1555        if (values.length > 0)
1556        {
1557          buffer.append(", values={");
1558          for (int i=0; i < values.length; i++)
1559          {
1560            if (i > 0)
1561            {
1562              buffer.append(", ");
1563            }
1564    
1565            buffer.append('\'');
1566            buffer.append(values[i].stringValue());
1567            buffer.append('\'');
1568          }
1569          buffer.append('}');
1570        }
1571    
1572        buffer.append(')');
1573      }
1574    }