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