001/* 002 * Copyright 2012-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.asn1.ASN1OctetString; 026import com.unboundid.ldap.sdk.Control; 027import com.unboundid.ldap.sdk.DecodeableControl; 028import com.unboundid.ldap.sdk.DN; 029import com.unboundid.ldap.sdk.LDAPException; 030import com.unboundid.ldap.sdk.LDAPResult; 031import com.unboundid.ldap.sdk.ResultCode; 032import com.unboundid.util.NotMutable; 033import com.unboundid.util.ThreadSafety; 034import com.unboundid.util.ThreadSafetyLevel; 035import com.unboundid.util.Validator; 036 037import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*; 038 039 040 041/** 042 * This class provides a response control that holds information about the 043 * soft-deleted entry that results from a soft delete request, and may also be 044 * included in a search result entry which represents a soft-deleted entry. The 045 * value of this control will be the DN of the soft-deleted entry. 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 has an OID of 1.3.6.1.4.1.30221.2.5.21, a criticality of false, 058 * and a value that is simply the string representation of the new DN for the 059 * soft-deleted entry. 060 * <BR><BR> 061 * See the documentation for the {@link SoftDeleteRequestControl} class for an 062 * example demonstrating the use of this control. 063 * 064 * @see SoftDeleteRequestControl 065 */ 066@NotMutable() 067@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 068public final class SoftDeleteResponseControl 069 extends Control 070 implements DecodeableControl 071{ 072 /** 073 * The OID (1.3.6.1.4.1.30221.2.5.21) for the soft delete response control. 074 */ 075 public static final String SOFT_DELETE_RESPONSE_OID = 076 "1.3.6.1.4.1.30221.2.5.21"; 077 078 079 080 /** 081 * The serial version UID for this serializable class. 082 */ 083 private static final long serialVersionUID = 3163679387266190228L; 084 085 086 087 // The DN of the soft-deleted representation of the target entry. 088 private final String softDeletedEntryDN; 089 090 091 092 /** 093 * Creates a new empty control instance that is intended to be used only for 094 * decoding controls via the {@code DecodeableControl} interface. 095 */ 096 SoftDeleteResponseControl() 097 { 098 softDeletedEntryDN = null; 099 } 100 101 102 103 /** 104 * Creates a new soft delete response control with the provided information. 105 * 106 * @param softDeletedEntryDN The DN of the soft-deleted representation of 107 * the target entry. 108 */ 109 public SoftDeleteResponseControl(final String softDeletedEntryDN) 110 { 111 super(SOFT_DELETE_RESPONSE_OID, false, 112 new ASN1OctetString(softDeletedEntryDN)); 113 114 Validator.ensureNotNull(softDeletedEntryDN); 115 116 this.softDeletedEntryDN = softDeletedEntryDN; 117 } 118 119 120 121 /** 122 * Creates a new soft delete response control with the provided information. 123 * 124 * @param oid The OID for the control. 125 * @param isCritical Indicates whether the control should be considered 126 * critical. 127 * @param value The value for the control. 128 * 129 * @throws LDAPException If the provided information cannot be used to 130 * create a valid soft delete response control. 131 */ 132 public SoftDeleteResponseControl(final String oid, final boolean isCritical, 133 final ASN1OctetString value) 134 throws LDAPException 135 { 136 super(oid, isCritical, value); 137 138 if (value == null) 139 { 140 throw new LDAPException(ResultCode.DECODING_ERROR, 141 ERR_SOFT_DELETE_RESPONSE_NO_VALUE.get()); 142 } 143 144 softDeletedEntryDN = value.stringValue(); 145 if (! DN.isValidDN(softDeletedEntryDN)) 146 { 147 throw new LDAPException(ResultCode.DECODING_ERROR, 148 ERR_SOFT_DELETE_RESPONSE_VALUE_NOT_DN.get()); 149 } 150 } 151 152 153 154 /** 155 * {@inheritDoc} 156 */ 157 @Override() 158 public SoftDeleteResponseControl decodeControl(final String oid, 159 final boolean isCritical, 160 final ASN1OctetString value) 161 throws LDAPException 162 { 163 return new SoftDeleteResponseControl(oid, isCritical, value); 164 } 165 166 167 168 /** 169 * Retrieves the DN of the entry containing the soft-deleted representation of 170 * the target entry. 171 * 172 * @return The DN of the entry containing the soft-deleted representation of 173 * the target entry. 174 */ 175 public String getSoftDeletedEntryDN() 176 { 177 return softDeletedEntryDN; 178 } 179 180 181 182 /** 183 * Extracts a soft delete response control from the provided delete result. 184 * 185 * @param deleteResult The delete result from which to retrieve the soft 186 * delete response control. 187 * 188 * @return The soft delete response control contained in the provided delete 189 * result, or {@code null} if the result did not contain a soft 190 * delete response control. 191 * 192 * @throws LDAPException If a problem is encountered while attempting to 193 * decode the soft delete response control contained 194 * in the provided result. 195 */ 196 public static SoftDeleteResponseControl get(final LDAPResult deleteResult) 197 throws LDAPException 198 { 199 final Control c = deleteResult.getResponseControl(SOFT_DELETE_RESPONSE_OID); 200 if (c == null) 201 { 202 return null; 203 } 204 205 if (c instanceof SoftDeleteResponseControl) 206 { 207 return (SoftDeleteResponseControl) c; 208 } 209 else 210 { 211 return new SoftDeleteResponseControl(c.getOID(), c.isCritical(), 212 c.getValue()); 213 } 214 } 215 216 217 218 /** 219 * {@inheritDoc} 220 */ 221 @Override() 222 public String getControlName() 223 { 224 return INFO_CONTROL_NAME_SOFT_DELETE_RESPONSE.get(); 225 } 226 227 228 229 /** 230 * {@inheritDoc} 231 */ 232 @Override() 233 public void toString(final StringBuilder buffer) 234 { 235 buffer.append("SoftDeleteResponseControl(softDeletedEntryDN='"); 236 buffer.append(softDeletedEntryDN); 237 buffer.append("')"); 238 } 239}