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