001/*
002 * Copyright 2012-2017 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2015-2017 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 Alcatel-Lucent 8661
051 *   server products.  These classes provide support for proprietary
052 *   functionality or for external specifications that are not considered stable
053 *   or mature enough to be guaranteed to work in an interoperable way with
054 *   other types of LDAP servers.
055 * </BLOCKQUOTE>
056 * <BR>
057 * See the documentation for the {@link SoftDeleteRequestControl} class for an
058 * example demonstrating the use of this control.
059 *
060 * @see  SoftDeleteRequestControl
061 */
062@NotMutable()
063@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
064public final class SoftDeleteResponseControl
065       extends Control
066       implements DecodeableControl
067{
068  /**
069   * The OID (1.3.6.1.4.1.30221.2.5.21) for the soft delete response control.
070   */
071  public static final String SOFT_DELETE_RESPONSE_OID =
072       "1.3.6.1.4.1.30221.2.5.21";
073
074
075
076  /**
077   * The serial version UID for this serializable class.
078   */
079  private static final long serialVersionUID = 3163679387266190228L;
080
081
082
083  // The DN of the soft-deleted representation of the target entry.
084  private final String softDeletedEntryDN;
085
086
087
088  /**
089   * Creates a new empty control instance that is intended to be used only for
090   * decoding controls via the {@code DecodeableControl} interface.
091   */
092  SoftDeleteResponseControl()
093  {
094    softDeletedEntryDN = null;
095  }
096
097
098
099  /**
100   * Creates a new soft delete response control with the provided information.
101   *
102   * @param  softDeletedEntryDN  The DN of the soft-deleted representation of
103   *                             the target entry.
104   */
105  public SoftDeleteResponseControl(final String softDeletedEntryDN)
106  {
107    super(SOFT_DELETE_RESPONSE_OID, false,
108         new ASN1OctetString(softDeletedEntryDN));
109
110    Validator.ensureNotNull(softDeletedEntryDN);
111
112    this.softDeletedEntryDN = softDeletedEntryDN;
113  }
114
115
116
117  /**
118   * Creates a new soft delete response control with the provided information.
119   *
120   * @param  oid         The OID for the control.
121   * @param  isCritical  Indicates whether the control should be considered
122   *                     critical.
123   * @param  value       The value for the control.
124   *
125   * @throws  LDAPException  If the provided information cannot be used to
126   *                         create a valid soft delete response control.
127   */
128  public SoftDeleteResponseControl(final String oid, final boolean isCritical,
129                                   final ASN1OctetString value)
130         throws LDAPException
131  {
132    super(oid, isCritical, value);
133
134    if (value == null)
135    {
136      throw new LDAPException(ResultCode.DECODING_ERROR,
137           ERR_SOFT_DELETE_RESPONSE_NO_VALUE.get());
138    }
139
140    softDeletedEntryDN = value.stringValue();
141    if (! DN.isValidDN(softDeletedEntryDN))
142    {
143      throw new LDAPException(ResultCode.DECODING_ERROR,
144           ERR_SOFT_DELETE_RESPONSE_VALUE_NOT_DN.get());
145    }
146  }
147
148
149
150  /**
151   * {@inheritDoc}
152   */
153  @Override()
154  public SoftDeleteResponseControl decodeControl(final String oid,
155                                                 final boolean isCritical,
156                                                 final ASN1OctetString value)
157         throws LDAPException
158  {
159    return new SoftDeleteResponseControl(oid, isCritical, value);
160  }
161
162
163
164  /**
165   * Retrieves the DN of the entry containing the soft-deleted representation of
166   * the target entry.
167   *
168   * @return  The DN of the entry containing the soft-deleted representation of
169   *          the target entry.
170   */
171  public String getSoftDeletedEntryDN()
172  {
173    return softDeletedEntryDN;
174  }
175
176
177
178  /**
179   * Extracts a soft delete response control from the provided delete result.
180   *
181   * @param  deleteResult  The delete result from which to retrieve the soft
182   *                       delete response control.
183   *
184   * @return  The soft delete response control contained in the provided delete
185   *          result, or {@code null} if the result did not contain a soft
186   *          delete response control.
187   *
188   * @throws  LDAPException  If a problem is encountered while attempting to
189   *                         decode the soft delete response control contained
190   *                         in the provided result.
191   */
192  public static SoftDeleteResponseControl get(final LDAPResult deleteResult)
193         throws LDAPException
194  {
195    final Control c = deleteResult.getResponseControl(SOFT_DELETE_RESPONSE_OID);
196    if (c == null)
197    {
198      return null;
199    }
200
201    if (c instanceof SoftDeleteResponseControl)
202    {
203      return (SoftDeleteResponseControl) c;
204    }
205    else
206    {
207      return new SoftDeleteResponseControl(c.getOID(), c.isCritical(),
208           c.getValue());
209    }
210  }
211
212
213
214  /**
215   * {@inheritDoc}
216   */
217  @Override()
218  public String getControlName()
219  {
220    return INFO_CONTROL_NAME_SOFT_DELETE_RESPONSE.get();
221  }
222
223
224
225  /**
226   * {@inheritDoc}
227   */
228  @Override()
229  public void toString(final StringBuilder buffer)
230  {
231    buffer.append("SoftDeleteResponseControl(softDeletedEntryDN='");
232    buffer.append(softDeletedEntryDN);
233    buffer.append("')");
234  }
235}