001/* 002 * Copyright 2007-2017 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2008-2017 UnboundID Corp. 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.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.controls.ControlMessages.*; 033 034 035 036/** 037 * This class provides an implementation of the ManageDsaIT control as described 038 * in <A HREF="http://www.ietf.org/rfc/rfc3296.txt">RFC 3296</A>. This control 039 * may be used to request that the directory server treat all entries as if they 040 * were regular entries. 041 * <BR><BR> 042 * One of the most common uses of the ManageDsaIT control is to request that the 043 * directory server to treat an entry containing the "{@code referral}" object 044 * class as a regular entry rather than a smart referral. Normally, when the 045 * server encounters an entry with the {@code referral} object class, it sends 046 * a referral with the URLs contained in the {@code ref} attribute of that 047 * entry. However, if the ManageDsaIT control is included then the operation 048 * will attempt to operate on the referral definition itself rather than sending 049 * that referral to the client. 050 * <BR><BR> 051 * <H2>Example</H2> 052 * The following example demonstrates the use of the ManageDsaIT control to 053 * delete an entry that may or may not be a referral: 054 * <PRE> 055 * // Establish a connection to the directory server. Even though it's the 056 * // default behavior, we'll explicitly configure the connection to not follow 057 * // referrals. 058 * LDAPConnectionOptions connectionOptions = new LDAPConnectionOptions(); 059 * connectionOptions.setFollowReferrals(false); 060 * LDAPConnection connection = new LDAPConnection(connectionOptions, 061 * serverAddress, serverPort, bindDN, bindPassword); 062 * 063 * // Try to delete an entry that will result in a referral. Without the 064 * // ManageDsaIT request control, we should get an exception. 065 * DeleteRequest deleteRequest = 066 * new DeleteRequest("ou=referral entry,dc=example,dc=com"); 067 * LDAPResult deleteResult; 068 * try 069 * { 070 * deleteResult = connection.delete(deleteRequest); 071 * } 072 * catch (LDAPException le) 073 * { 074 * // This exception is expected because we should get a referral, and 075 * // the connection is configured to not follow referrals. 076 * deleteResult = le.toLDAPResult(); 077 * ResultCode resultCode = le.getResultCode(); 078 * String errorMessageFromServer = le.getDiagnosticMessage(); 079 * String[] referralURLs = le.getReferralURLs(); 080 * } 081 * LDAPTestUtils.assertResultCodeEquals(deleteResult, ResultCode.REFERRAL); 082 * LDAPTestUtils.assertHasReferral(deleteResult); 083 * 084 * // Update the delete request to include the ManageDsaIT request control, 085 * // which will cause the server to try to delete the referral entry instead 086 * // of returning a referral response. We'll assume that the delete is 087 * // successful. 088 * deleteRequest.addControl(new ManageDsaITRequestControl()); 089 * try 090 * { 091 * deleteResult = connection.delete(deleteRequest); 092 * } 093 * catch (LDAPException le) 094 * { 095 * // The delete shouldn't trigger a referral, but it's possible that the 096 * // operation failed for some other reason (e.g., entry doesn't exist, the 097 * // user doesn't have permission to delete it, etc.). 098 * deleteResult = le.toLDAPResult(); 099 * } 100 * LDAPTestUtils.assertResultCodeEquals(deleteResult, ResultCode.SUCCESS); 101 * LDAPTestUtils.assertMissingReferral(deleteResult); 102 * 103 * connection.close(); 104 * </PRE> 105 */ 106@NotMutable() 107@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 108public final class ManageDsaITRequestControl 109 extends Control 110{ 111 /** 112 * The OID (2.16.840.1.113730.3.4.2) for the ManageDsaIT request control. 113 */ 114 public static final String MANAGE_DSA_IT_REQUEST_OID = 115 "2.16.840.1.113730.3.4.2"; 116 117 118 119 /** 120 * The serial version UID for this serializable class. 121 */ 122 private static final long serialVersionUID = -4540943247829123783L; 123 124 125 126 /** 127 * Creates a new ManageDsaIT request control. The control will not be marked 128 * critical. 129 */ 130 public ManageDsaITRequestControl() 131 { 132 super(MANAGE_DSA_IT_REQUEST_OID, false, null); 133 } 134 135 136 137 /** 138 * Creates a new ManageDsaIT request control. 139 * 140 * @param isCritical Indicates whether the control should be marked 141 * critical. 142 */ 143 public ManageDsaITRequestControl(final boolean isCritical) 144 { 145 super(MANAGE_DSA_IT_REQUEST_OID, isCritical, null); 146 } 147 148 149 150 /** 151 * Creates a new ManageDsaIT request control which is decoded from the 152 * provided generic control. 153 * 154 * @param control The generic control to be decoded as a ManageDsaIT request 155 * control. 156 * 157 * @throws LDAPException If the provided control cannot be decoded as a 158 * ManageDsaIT request control. 159 */ 160 public ManageDsaITRequestControl(final Control control) 161 throws LDAPException 162 { 163 super(control); 164 165 if (control.hasValue()) 166 { 167 throw new LDAPException(ResultCode.DECODING_ERROR, 168 ERR_MANAGE_DSA_IT_HAS_VALUE.get()); 169 } 170 } 171 172 173 174 /** 175 * {@inheritDoc} 176 */ 177 @Override() 178 public String getControlName() 179 { 180 return INFO_CONTROL_NAME_MANAGE_DSAIT_REQUEST.get(); 181 } 182 183 184 185 /** 186 * {@inheritDoc} 187 */ 188 @Override() 189 public void toString(final StringBuilder buffer) 190 { 191 buffer.append("ManageDsaITRequestControl(isCritical="); 192 buffer.append(isCritical()); 193 buffer.append(')'); 194 } 195}