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