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