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 }