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 defines a request control that may be used to indicate that the 038 * server should process all aspects of the associated bind request (including 039 * password policy processing) but should not actually change the identity for 040 * the client connection, regardless of whether the authentication is 041 * successful. 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 047 * Nokia/Alcatel-Lucent 8661 server products. These classes provide support 048 * for proprietary functionality or for external specifications that are not 049 * considered stable or mature enough to be guaranteed to work in an 050 * interoperable way with other types of LDAP servers. 051 * </BLOCKQUOTE> 052 * <BR> 053 * This control can be very useful for applications that perform binds to 054 * authenticate users but also use connection pooling to re-use connections 055 * for multiple operations. Bind operations are normally not well-suited for 056 * use on pooled connections because they change the identity of that 057 * connection, but the retain identity request control solves that problem by 058 * performing all bind processing but does not change the identity associated 059 * with the client connection. 060 * <BR><BR> 061 * There is no corresponding response control. If the bind is successful, then 062 * the server should return a bind response with the {@code ResultCode#SUCCESS} 063 * result code just as if the bind request had not included the retain identity 064 * request control. 065 * <BR><BR> 066 * This control is not based on any public standard. It was originally 067 * developed for use with the Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 068 * 8661 Directory Server. It does not have a value. 069 * <BR><BR> 070 * <H2>Example</H2> 071 * The following example demonstrates the use of the retain identity request 072 * control: 073 * <PRE> 074 * SimpleBindRequest bindRequest = new SimpleBindRequest( 075 * "uid=john.doe,ou=People,dc=example,dc=com", "password", 076 * new RetainIdentityRequestControl()); 077 * 078 * BindResult bindResult; 079 * try 080 * { 081 * bindResult = connection.bind(bindRequest); 082 * // The bind was successful and the account is usable, but the identity 083 * // associated with the client connection hasn't changed. 084 * } 085 * catch (LDAPException le) 086 * { 087 * bindResult = new BindResult(le.toLDAPResult()); 088 * // The bind was unsuccessful, potentially because the credentials were 089 * // invalid or the account is unusable for some reason (e.g., disabled, 090 * // locked, expired password, etc.). The identity associated with the 091 * // client connection hasn't changed. 092 * } 093 * </PRE> 094 */ 095@NotMutable() 096@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 097public final class RetainIdentityRequestControl 098 extends Control 099{ 100 /** 101 * The OID (1.3.6.1.4.1.30221.2.5.3) for the retain identity request control. 102 */ 103 public static final String RETAIN_IDENTITY_REQUEST_OID = 104 "1.3.6.1.4.1.30221.2.5.3"; 105 106 107 108 /** 109 * The serial version UID for this serializable class. 110 */ 111 private static final long serialVersionUID = 9066549673766581236L; 112 113 114 115 /** 116 * Creates a new retain identity request control. It will be marked critical. 117 */ 118 public RetainIdentityRequestControl() 119 { 120 super(RETAIN_IDENTITY_REQUEST_OID, true, null); 121 } 122 123 124 125 /** 126 * Creates a new retain identity request control which is decoded from 127 * the provided generic control. 128 * 129 * @param control The generic control to be decoded as a retain identity 130 * request control. 131 * 132 * @throws LDAPException If the provided control cannot be decoded as a 133 * retain identity request control. 134 */ 135 public RetainIdentityRequestControl(final Control control) 136 throws LDAPException 137 { 138 super(control); 139 140 if (control.hasValue()) 141 { 142 throw new LDAPException(ResultCode.DECODING_ERROR, 143 ERR_RETAIN_IDENTITY_REQUEST_HAS_VALUE.get()); 144 } 145 } 146 147 148 149 /** 150 * {@inheritDoc} 151 */ 152 @Override() 153 public String getControlName() 154 { 155 return INFO_CONTROL_NAME_RETAIN_IDENTITY_REQUEST.get(); 156 } 157 158 159 160 /** 161 * {@inheritDoc} 162 */ 163 @Override() 164 public void toString(final StringBuilder buffer) 165 { 166 buffer.append("RetainIdentityRequestControl(isCritical="); 167 buffer.append(isCritical()); 168 buffer.append(')'); 169 } 170}