001/* 002 * Copyright 2008-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 account usable request control. 038 * It may be included in search requests, in which case each search result entry 039 * matching that request should include the corresponding response control to 040 * obtain information about the usability of the user account associated with 041 * that entry. In particular, it indicates whether a bind with valid 042 * credentials would likely succeed and the resulting connection would be 043 * usable, and if not the reason for the potential failure. See the 044 * {@link AccountUsableResponseControl} for information about the information 045 * that is taken into account. 046 * <BR> 047 * <BLOCKQUOTE> 048 * <B>NOTE:</B> This class, and other classes within the 049 * {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only 050 * supported for use against Ping Identity, UnboundID, and 051 * Nokia/Alcatel-Lucent 8661 server products. These classes provide support 052 * for proprietary functionality or for external specifications that are not 053 * considered stable or mature enough to be guaranteed to work in an 054 * interoperable way with other types of LDAP servers. 055 * </BLOCKQUOTE> 056 * <BR> 057 * This control was designed by Sun Microsystems and is not based on any RFC or 058 * Internet draft. It does not include a value. 059 * <BR><BR> 060 * <H2>Example</H2> 061 * The following example demonstrates the use of the account usable controls to 062 * determine whether the account for user with uid "john.doe" is usable: 063 * <PRE> 064 * SearchRequest searchRequest = 065 * new SearchRequest("dc=example,dc=com", SearchScope.SUB, 066 * Filter.createEqualityFilter("uid", "john.doe")); 067 * searchRequest.addControl(new AccountUsableRequestControl()); 068 * SearchResult searchResult = connection.search(searchRequest); 069 * 070 * boolean isUsable = false; 071 * for (SearchResultEntry entry : searchResult.getSearchEntries()) 072 * { 073 * AccountUsableResponseControl c = 074 * AccountUsableResponseControl.get(entry); 075 * isUsable = c.isUsable(); 076 * if (isUsable) 077 * { 078 * // The account is usable. 079 * } 080 * else 081 * { 082 * // The account is not usable. 083 * List<String> unusableReasons = c.getUnusableReasons(); 084 * } 085 * } 086 * </PRE> 087 */ 088@NotMutable() 089@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 090public final class AccountUsableRequestControl 091 extends Control 092{ 093 /** 094 * The OID (1.3.6.1.4.1.42.2.27.9.5.8) for the account usable request control. 095 */ 096 public static final String ACCOUNT_USABLE_REQUEST_OID = 097 "1.3.6.1.4.1.42.2.27.9.5.8"; 098 099 100 101 /** 102 * The serial version UID for this serializable class. 103 */ 104 private static final long serialVersionUID = 2776055961624360982L; 105 106 107 108 /** 109 * Creates a new account usable request control. It will not be marked 110 * critical. 111 */ 112 public AccountUsableRequestControl() 113 { 114 this(false); 115 } 116 117 118 119 /** 120 * Creates a new account usable request control with the specified 121 * criticality. 122 * 123 * @param isCritical Indicates whether this control should be marked 124 * critical. 125 */ 126 public AccountUsableRequestControl(final boolean isCritical) 127 { 128 super(ACCOUNT_USABLE_REQUEST_OID, isCritical, null); 129 } 130 131 132 133 /** 134 * Creates a new account usable request control which is decoded from the 135 * provided generic control. 136 * 137 * @param control The generic control to be decoded as an account usable 138 * request control. 139 * 140 * @throws LDAPException If the provided control cannot be decoded as an 141 * account usable request control. 142 */ 143 public AccountUsableRequestControl(final Control control) 144 throws LDAPException 145 { 146 super(control); 147 148 if (control.hasValue()) 149 { 150 throw new LDAPException(ResultCode.DECODING_ERROR, 151 ERR_ACCOUNT_USABLE_REQUEST_HAS_VALUE.get()); 152 } 153 } 154 155 156 157 /** 158 * {@inheritDoc} 159 */ 160 @Override() 161 public String getControlName() 162 { 163 return INFO_CONTROL_NAME_ACCOUNT_USABLE_REQUEST.get(); 164 } 165 166 167 168 /** 169 * {@inheritDoc} 170 */ 171 @Override() 172 public void toString(final StringBuilder buffer) 173 { 174 buffer.append("AccountUsableRequestControl(isCritical="); 175 buffer.append(isCritical()); 176 buffer.append(')'); 177 } 178}