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.ASN1Element; 026import com.unboundid.asn1.ASN1Sequence; 027import com.unboundid.ldap.sdk.Control; 028import com.unboundid.ldap.sdk.DeleteRequest; 029import com.unboundid.ldap.sdk.LDAPException; 030import com.unboundid.ldap.sdk.ResultCode; 031import com.unboundid.util.Debug; 032import com.unboundid.util.NotMutable; 033import com.unboundid.util.StaticUtils; 034import com.unboundid.util.ThreadSafety; 035import com.unboundid.util.ThreadSafetyLevel; 036 037import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*; 038 039 040 041/** 042 * This class provides a request control which may be included in a delete 043 * request to indicate that the server should completely remove the target 044 * entry, even if it would otherwise process the operation as a soft delete and 045 * merely hide the entry from most clients. 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 * The criticality for this control may be either {@code TRUE} or {@code FALSE}, 058 * but this will only impact how the delete request is to be handled by servers 059 * which do not support this control. A criticality of {@code TRUE} will cause 060 * any server which does not support this control to reject the request, while 061 * a criticality of {@code FALSE} should cause the delete request to be 062 * processed as if the control had not been included (i.e., as a regular "hard" 063 * delete). 064 * <BR><BR> 065 * The control may optionally have a value. If a value is provided, then it 066 * must be the encoded representation of an empty ASN.1 sequence, like: 067 * <PRE> 068 * HardDeleteRequestValue ::= SEQUENCE { 069 * ... } 070 * </PRE> 071 * In the future, the value sequence may allow one or more elements to customize 072 * the behavior of the hard delete operation, but at present no such elements 073 * are defined. 074 * See the documentation for the {@link SoftDeleteRequestControl} class for an 075 * example demonstrating the use of this control. 076 * 077 * @see SoftDeleteRequestControl 078 */ 079@NotMutable() 080@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 081public final class HardDeleteRequestControl 082 extends Control 083{ 084 /** 085 * The OID (1.3.6.1.4.1.30221.2.5.22) for the hard delete request control. 086 */ 087 public static final String HARD_DELETE_REQUEST_OID = 088 "1.3.6.1.4.1.30221.2.5.22"; 089 090 091 092 /** 093 * The serial version UID for this serializable class. 094 */ 095 private static final long serialVersionUID = 1169625153021056712L; 096 097 098 099 /** 100 * Creates a new hard delete request control. It will not be marked critical. 101 */ 102 public HardDeleteRequestControl() 103 { 104 this(false); 105 } 106 107 108 109 /** 110 * Creates a new hard delete request control with the provided information. 111 * 112 * @param isCritical Indicates whether this control should be marked 113 * critical. This will only have an effect on the way the 114 * associated delete operation is handled by servers which 115 * do NOT support the hard delete request control. For 116 * such servers, a control that is critical will cause the 117 * hard delete attempt to fail, while a control that is 118 * not critical will be processed as if the control was 119 * not included in the request (i.e., as a normal "hard" 120 * delete). 121 */ 122 public HardDeleteRequestControl(final boolean isCritical) 123 { 124 super(HARD_DELETE_REQUEST_OID, isCritical, null); 125 } 126 127 128 129 /** 130 * Creates a new hard delete request control which is decoded from the 131 * provided generic control. 132 * 133 * @param control The generic control to be decoded as a hard delete request 134 * control. 135 * 136 * @throws LDAPException If the provided control cannot be decoded as a hard 137 * delete request control. 138 */ 139 public HardDeleteRequestControl(final Control control) 140 throws LDAPException 141 { 142 super(control); 143 144 if (control.hasValue()) 145 { 146 try 147 { 148 final ASN1Sequence valueSequence = 149 ASN1Sequence.decodeAsSequence(control.getValue().getValue()); 150 final ASN1Element[] elements = valueSequence.elements(); 151 if (elements.length > 0) 152 { 153 throw new LDAPException(ResultCode.DECODING_ERROR, 154 ERR_HARD_DELETE_REQUEST_UNSUPPORTED_VALUE_ELEMENT_TYPE.get( 155 StaticUtils.toHex(elements[0].getType()))); 156 } 157 } 158 catch (final LDAPException le) 159 { 160 Debug.debugException(le); 161 throw le; 162 } 163 catch (final Exception e) 164 { 165 Debug.debugException(e); 166 throw new LDAPException(ResultCode.DECODING_ERROR, 167 ERR_HARD_DELETE_REQUEST_CANNOT_DECODE_VALUE.get( 168 StaticUtils.getExceptionMessage(e)), 169 e); 170 } 171 } 172 } 173 174 175 176 /** 177 * Creates a new delete request that may be used to hard delete the specified 178 * target entry. 179 * 180 * @param targetDN The DN of the entry to be hard deleted. 181 * @param isCritical Indicates whether this control should be marked 182 * critical. This will only have an effect on the way the 183 * associated delete operation is handled by servers which 184 * do NOT support the hard delete request control. For 185 * such servers, a control that is critical will cause the 186 * hard delete attempt to fail, while a control that is 187 * not critical will be processed as if the control was 188 * not included in the request (i.e., as a normal "hard" 189 * delete). 190 * 191 * @return A delete request with the specified target DN and an appropriate 192 * hard delete request control. 193 */ 194 public static DeleteRequest createHardDeleteRequest(final String targetDN, 195 final boolean isCritical) 196 { 197 final Control[] controls = 198 { 199 new HardDeleteRequestControl(isCritical) 200 }; 201 202 return new DeleteRequest(targetDN, controls); 203 } 204 205 206 207 /** 208 * {@inheritDoc} 209 */ 210 @Override() 211 public String getControlName() 212 { 213 return INFO_CONTROL_NAME_HARD_DELETE_REQUEST.get(); 214 } 215 216 217 218 /** 219 * {@inheritDoc} 220 */ 221 @Override() 222 public void toString(final StringBuilder buffer) 223 { 224 buffer.append("HardDeleteRequestControl(isCritical="); 225 buffer.append(isCritical()); 226 buffer.append(')'); 227 } 228}