001/*
002 * Copyright 2010-2024 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2010-2024 Ping Identity Corporation
007 *
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *    http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020/*
021 * Copyright (C) 2010-2024 Ping Identity Corporation
022 *
023 * This program is free software; you can redistribute it and/or modify
024 * it under the terms of the GNU General Public License (GPLv2 only)
025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
026 * as published by the Free Software Foundation.
027 *
028 * This program is distributed in the hope that it will be useful,
029 * but WITHOUT ANY WARRANTY; without even the implied warranty of
030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
031 * GNU General Public License for more details.
032 *
033 * You should have received a copy of the GNU General Public License
034 * along with this program; if not, see <http://www.gnu.org/licenses>.
035 */
036package com.unboundid.ldap.sdk.controls;
037
038
039
040import java.util.ArrayList;
041
042import com.unboundid.asn1.ASN1Boolean;
043import com.unboundid.asn1.ASN1Constants;
044import com.unboundid.asn1.ASN1Element;
045import com.unboundid.asn1.ASN1OctetString;
046import com.unboundid.asn1.ASN1Sequence;
047import com.unboundid.ldap.sdk.Control;
048import com.unboundid.ldap.sdk.DecodeableControl;
049import com.unboundid.ldap.sdk.LDAPException;
050import com.unboundid.ldap.sdk.LDAPResult;
051import com.unboundid.ldap.sdk.ResultCode;
052import com.unboundid.util.Debug;
053import com.unboundid.util.NotMutable;
054import com.unboundid.util.NotNull;
055import com.unboundid.util.Nullable;
056import com.unboundid.util.StaticUtils;
057import com.unboundid.util.ThreadSafety;
058import com.unboundid.util.ThreadSafetyLevel;
059
060import static com.unboundid.ldap.sdk.controls.ControlMessages.*;
061
062
063
064/**
065 * This class provides an implementation of the LDAP content synchronization
066 * done control as defined in
067 * <a href="http://www.ietf.org/rfc/rfc4533.txt">RFC 4533</a>.  Directory
068 * servers may include this control in the search result done message for a
069 * search request containing the content synchronization request control.  See
070 * the documentation for the {@link ContentSyncRequestControl} class for more
071 * information about using the content synchronization operation.
072 */
073@NotMutable()
074@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
075public final class ContentSyncDoneControl
076       extends Control
077       implements DecodeableControl
078{
079  /**
080   * The OID (1.3.6.1.4.1.4203.1.9.1.3) for the sync done control.
081   */
082  @NotNull public static final String SYNC_DONE_OID =
083       "1.3.6.1.4.1.4203.1.9.1.3";
084
085
086
087  /**
088   * The serial version UID for this serializable class.
089   */
090  private static final long serialVersionUID = -2723009401737612274L;
091
092
093
094  // The synchronization state cookie.
095  @Nullable private final ASN1OctetString cookie;
096
097  // Indicates whether to refresh information about deleted entries.
098  private final boolean refreshDeletes;
099
100
101
102  /**
103   * Creates a new empty control instance that is intended to be used only for
104   * decoding controls via the {@code DecodeableControl} interface.
105   */
106  ContentSyncDoneControl()
107  {
108    cookie         = null;
109    refreshDeletes = false;
110  }
111
112
113
114  /**
115   * Creates a new content synchronization done control that provides updated
116   * information about the state of a content synchronization session.
117   *
118   * @param  cookie          A cookie with an updated synchronization state.  It
119   *                         may be {@code null} if no updated state is
120   *                         available.
121   * @param  refreshDeletes  Indicates whether the synchronization processing
122   *                         has completed a delete phase.
123   */
124  public ContentSyncDoneControl(@Nullable final ASN1OctetString cookie,
125                                final boolean refreshDeletes)
126  {
127    super(SYNC_DONE_OID, false, encodeValue(cookie, refreshDeletes));
128
129    this.cookie          = cookie;
130    this.refreshDeletes = refreshDeletes;
131  }
132
133
134
135  /**
136   * Creates a new content synchronization done control which is decoded from
137   * the provided information from a generic control.
138   *
139   * @param  oid         The OID for the control used to create this control.
140   * @param  isCritical  Indicates whether the control is marked critical.
141   * @param  value       The encoded value for the control.
142   *
143   * @throws  LDAPException  If the provided control cannot be decoded as a
144   *                         content synchronization done control.
145   */
146  public ContentSyncDoneControl(@NotNull final String oid,
147                                final boolean isCritical,
148                                @Nullable final ASN1OctetString value)
149         throws LDAPException
150  {
151    super(oid, isCritical, value);
152
153    if (value == null)
154    {
155      throw new LDAPException(ResultCode.DECODING_ERROR,
156           ERR_SYNC_DONE_NO_VALUE.get());
157    }
158
159    ASN1OctetString c = null;
160    Boolean         r = null;
161
162    try
163    {
164      final ASN1Sequence s = ASN1Sequence.decodeAsSequence(value.getValue());
165      for (final ASN1Element e : s.elements())
166      {
167        switch (e.getType())
168        {
169          case ASN1Constants.UNIVERSAL_OCTET_STRING_TYPE:
170            if (c == null)
171            {
172              c = ASN1OctetString.decodeAsOctetString(e);
173            }
174            else
175            {
176              throw new LDAPException(ResultCode.DECODING_ERROR,
177                   ERR_SYNC_DONE_VALUE_MULTIPLE_COOKIES.get());
178            }
179            break;
180
181          case ASN1Constants.UNIVERSAL_BOOLEAN_TYPE:
182            if (r == null)
183            {
184              r = ASN1Boolean.decodeAsBoolean(e).booleanValue();
185            }
186            else
187            {
188              throw new LDAPException(ResultCode.DECODING_ERROR,
189                   ERR_SYNC_DONE_VALUE_MULTIPLE_REFRESH_DELETE.get());
190            }
191            break;
192
193          default:
194            throw new LDAPException(ResultCode.DECODING_ERROR,
195                 ERR_SYNC_DONE_VALUE_INVALID_ELEMENT_TYPE.get(
196                      StaticUtils.toHex(e.getType())));
197        }
198      }
199    }
200    catch (final LDAPException le)
201    {
202      throw le;
203    }
204    catch (final Exception e)
205    {
206      Debug.debugException(e);
207
208      throw new LDAPException(ResultCode.DECODING_ERROR,
209           ERR_SYNC_DONE_VALUE_CANNOT_DECODE.get(
210                StaticUtils.getExceptionMessage(e)), e);
211    }
212
213    cookie = c;
214
215    if (r == null)
216    {
217      refreshDeletes = false;
218    }
219    else
220    {
221      refreshDeletes = r;
222    }
223  }
224
225
226
227  /**
228   * Encodes the provided information into a form suitable for use as the value
229   * of this control.
230   *
231   * @param  cookie          A cookie with an updated synchronization state.  It
232   *                         may be {@code null} if no updated state is
233   *                         available.
234   * @param  refreshDeletes  Indicates whether the synchronization processing
235   *                         has completed a delete phase.
236   *
237   * @return  An ASN.1 octet string containing the encoded control value.
238   */
239  @NotNull()
240  private static ASN1OctetString encodeValue(
241                                      @Nullable final ASN1OctetString cookie,
242                                      final boolean refreshDeletes)
243  {
244    final ArrayList<ASN1Element> elements = new ArrayList<>(2);
245
246    if (cookie != null)
247    {
248      elements.add(cookie);
249    }
250
251    if (refreshDeletes)
252    {
253      elements.add(new ASN1Boolean(refreshDeletes));
254    }
255
256    return new ASN1OctetString(new ASN1Sequence(elements).encode());
257  }
258
259
260
261  /**
262   * {@inheritDoc}
263   */
264  @Override()
265  @NotNull()
266  public ContentSyncDoneControl decodeControl(@NotNull final String oid,
267                                     final boolean isCritical,
268                                     @Nullable final ASN1OctetString value)
269         throws LDAPException
270  {
271    return new ContentSyncDoneControl(oid, isCritical, value);
272  }
273
274
275
276  /**
277   * Extracts a content synchronization done control from the provided result.
278   *
279   * @param  result  The result from which to retrieve the content
280   *                 synchronization done control.
281   *
282   * @return  The content synchronization done control contained in the provided
283   *          result, or {@code null} if the result did not contain a content
284   *          synchronization done control.
285   *
286   * @throws  LDAPException  If a problem is encountered while attempting to
287   *                         decode the content synchronization done control
288   *                         contained in the provided result.
289   */
290  @Nullable()
291  public static ContentSyncDoneControl get(@NotNull final LDAPResult result)
292         throws LDAPException
293  {
294    final Control c =
295         result.getResponseControl(SYNC_DONE_OID);
296    if (c == null)
297    {
298      return null;
299    }
300
301    if (c instanceof ContentSyncDoneControl)
302    {
303      return (ContentSyncDoneControl) c;
304    }
305    else
306    {
307      return new ContentSyncDoneControl(c.getOID(), c.isCritical(),
308           c.getValue());
309    }
310  }
311
312
313
314  /**
315   * Retrieves a cookie providing updated state information for the
316   * synchronization session, if available.
317   *
318   * @return  A cookie providing updated state information for the
319   *          synchronization session, or {@code null} if none was included in
320   *          the control.
321   */
322  @Nullable()
323  public ASN1OctetString getCookie()
324  {
325    return cookie;
326  }
327
328
329
330  /**
331   * Indicates whether the synchronization processing has completed a delete
332   * phase.
333   *
334   * @return  {@code true} if the synchronization processing has completed a
335   *          delete phase, or {@code false} if not.
336   */
337  public boolean refreshDeletes()
338  {
339    return refreshDeletes;
340  }
341
342
343
344  /**
345   * {@inheritDoc}
346   */
347  @Override()
348  @NotNull()
349  public String getControlName()
350  {
351    return INFO_CONTROL_NAME_CONTENT_SYNC_DONE.get();
352  }
353
354
355
356  /**
357   * {@inheritDoc}
358   */
359  @Override()
360  public void toString(@NotNull final StringBuilder buffer)
361  {
362    buffer.append("ContentSyncDoneControl(");
363
364    if (cookie != null)
365    {
366      buffer.append("cookie='");
367      StaticUtils.toHex(cookie.getValue(), buffer);
368      buffer.append("', ");
369    }
370
371    buffer.append("refreshDeletes=");
372    buffer.append(refreshDeletes);
373    buffer.append(')');
374  }
375}