001/* 002 * Copyright 2007-2020 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2007-2020 Ping Identity Corporation 007 * 008 * Licensed under the Apache License, Version 2.0 (the "License"); 009 * you may not use this file except in compliance with the License. 010 * You may obtain a copy of the License at 011 * 012 * http://www.apache.org/licenses/LICENSE-2.0 013 * 014 * Unless required by applicable law or agreed to in writing, software 015 * distributed under the License is distributed on an "AS IS" BASIS, 016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 017 * See the License for the specific language governing permissions and 018 * limitations under the License. 019 */ 020/* 021 * Copyright (C) 2015-2020 Ping Identity Corporation 022 * 023 * This program is free software; you can redistribute it and/or modify 024 * it under the terms of the GNU General Public License (GPLv2 only) 025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 026 * as published by the Free Software Foundation. 027 * 028 * This program is distributed in the hope that it will be useful, 029 * but WITHOUT ANY WARRANTY; without even the implied warranty of 030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 031 * GNU General Public License for more details. 032 * 033 * You should have received a copy of the GNU General Public License 034 * along with this program; if not, see <http://www.gnu.org/licenses>. 035 */ 036package com.unboundid.ldap.sdk.unboundidds.controls; 037 038 039 040import com.unboundid.ldap.sdk.Control; 041import com.unboundid.ldap.sdk.LDAPException; 042import com.unboundid.ldap.sdk.ResultCode; 043import com.unboundid.util.NotMutable; 044import com.unboundid.util.ThreadSafety; 045import com.unboundid.util.ThreadSafetyLevel; 046 047import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*; 048 049 050 051/** 052 * This class provides an implementation of the password policy request control 053 * as described in draft-behera-ldap-password-policy. It may be used to request 054 * information related to a user's password policy. In the Ping Identity, 055 * UnboundID, and Nokia/Alcatel-Lucent 8661 Directory Server, this control may 056 * be included with add, bind, compare, modify, and password modify requests. 057 * <BR> 058 * <BLOCKQUOTE> 059 * <B>NOTE:</B> This class, and other classes within the 060 * {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only 061 * supported for use against Ping Identity, UnboundID, and 062 * Nokia/Alcatel-Lucent 8661 server products. These classes provide support 063 * for proprietary functionality or for external specifications that are not 064 * considered stable or mature enough to be guaranteed to work in an 065 * interoperable way with other types of LDAP servers. 066 * </BLOCKQUOTE> 067 * <BR> 068 * This request control has an OID of 1.3.6.1.4.1.42.2.27.8.5.1. The 069 * criticality may be either true or false. It does not have a value. 070 * <BR><BR> 071 * The corresponding {@link PasswordPolicyResponseControl} may include at most 072 * one warning from the set of {@link PasswordPolicyWarningType} values and at 073 * most one error from the set of {@link PasswordPolicyErrorType} values. See 074 * the documentation for those classes for more information on the information 075 * that may be included. 076 * <BR><BR> 077 * <H2>Example</H2> 078 * The following example demonstrates the use of the password policy request 079 * control in conjunction with a bind operation: 080 * <PRE> 081 * SimpleBindRequest bindRequest = new SimpleBindRequest( 082 * "uid=john.doe,ou=People,dc=example,dc=com", "password", 083 * new PasswordPolicyRequestControl()); 084 * 085 * BindResult bindResult; 086 * try 087 * { 088 * bindResult = connection.bind(bindRequest); 089 * } 090 * catch (LDAPException le) 091 * { 092 * // The bind failed. There may be a password policy response control to 093 * // help tell us why. 094 * bindResult = new BindResult(le.toLDAPResult()); 095 * } 096 * 097 * PasswordPolicyResponseControl pwpResponse = 098 * PasswordPolicyResponseControl.get(bindResult); 099 * if (pwpResponse != null) 100 * { 101 * PasswordPolicyErrorType errorType = pwpResponse.getErrorType(); 102 * if (errorType != null) 103 * { 104 * // There was a password policy-related error. 105 * } 106 * 107 * PasswordPolicyWarningType warningType = pwpResponse.getWarningType(); 108 * if (warningType != null) 109 * { 110 * // There was a password policy-related warning. 111 * int value = pwpResponse.getWarningValue(); 112 * switch (warningType) 113 * { 114 * case TIME_BEFORE_EXPIRATION: 115 * // The warning value is the number of seconds until the user's 116 * // password expires. 117 * break; 118 * case GRACE_LOGINS_REMAINING: 119 * // The warning value is the number of grace logins remaining for 120 * // the user. 121 * } 122 * } 123 * } 124 * </PRE> 125 */ 126@NotMutable() 127@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 128public final class PasswordPolicyRequestControl 129 extends Control 130{ 131 /** 132 * The OID (1.3.6.1.4.1.42.2.27.8.5.1) for the password policy request 133 * control. 134 */ 135 public static final String PASSWORD_POLICY_REQUEST_OID = 136 "1.3.6.1.4.1.42.2.27.8.5.1"; 137 138 139 140 /** 141 * The serial version UID for this serializable class. 142 */ 143 private static final long serialVersionUID = 6495056761590890150L; 144 145 146 147 /** 148 * Creates a new password policy request control. The control will not be 149 * marked critical. 150 */ 151 public PasswordPolicyRequestControl() 152 { 153 super(PASSWORD_POLICY_REQUEST_OID, false, null); 154 } 155 156 157 158 /** 159 * Creates a new password policy request control. 160 * 161 * @param isCritical Indicates whether the control should be marked 162 * critical. 163 */ 164 public PasswordPolicyRequestControl(final boolean isCritical) 165 { 166 super(PASSWORD_POLICY_REQUEST_OID, isCritical, null); 167 } 168 169 170 171 /** 172 * Creates a new password policy request control which is decoded from the 173 * provided generic control. 174 * 175 * @param control The generic control to be decoded as a password policy 176 * request control. 177 * 178 * @throws LDAPException If the provided control cannot be decoded as a 179 * password policy request control. 180 */ 181 public PasswordPolicyRequestControl(final Control control) 182 throws LDAPException 183 { 184 super(control); 185 186 if (control.hasValue()) 187 { 188 throw new LDAPException(ResultCode.DECODING_ERROR, 189 ERR_PWP_REQUEST_HAS_VALUE.get()); 190 } 191 } 192 193 194 195 /** 196 * {@inheritDoc} 197 */ 198 @Override() 199 public String getControlName() 200 { 201 return INFO_CONTROL_NAME_PW_POLICY_REQUEST.get(); 202 } 203 204 205 206 /** 207 * {@inheritDoc} 208 */ 209 @Override() 210 public void toString(final StringBuilder buffer) 211 { 212 buffer.append("PasswordPolicyRequestControl(isCritical="); 213 buffer.append(isCritical()); 214 buffer.append(')'); 215 } 216}