001/*
002 * Copyright 2012-2019 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2015-2019 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}