001/*
002 * Copyright 2014-2020 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2014-2020 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) 2015-2020 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.unboundidds.controls;
037
038
039
040import java.util.ArrayList;
041import java.util.Collection;
042import java.util.Collections;
043import java.util.Iterator;
044import java.util.LinkedHashSet;
045import java.util.List;
046import java.util.Set;
047
048import com.unboundid.asn1.ASN1Element;
049import com.unboundid.asn1.ASN1OctetString;
050import com.unboundid.asn1.ASN1Sequence;
051import com.unboundid.asn1.ASN1Set;
052import com.unboundid.ldap.sdk.Control;
053import com.unboundid.ldap.sdk.DecodeableControl;
054import com.unboundid.ldap.sdk.ExtendedResult;
055import com.unboundid.ldap.sdk.LDAPException;
056import com.unboundid.ldap.sdk.LDAPResult;
057import com.unboundid.ldap.sdk.ResultCode;
058import com.unboundid.ldap.sdk.SearchResultEntry;
059import com.unboundid.util.Debug;
060import com.unboundid.util.NotMutable;
061import com.unboundid.util.StaticUtils;
062import com.unboundid.util.ThreadSafety;
063import com.unboundid.util.ThreadSafetyLevel;
064import com.unboundid.util.Validator;
065
066import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*;
067
068
069
070/**
071 * This class provides a response control that may be used to provide the
072 * backend set ID(s) for any relevant backend sets accessed during the course
073 * of processing an operation.  It may be returned in response to a request
074 * containing either the get backend set ID request control or the route to
075 * backend set request control.  For add, simple bind, compare, delete,
076 * modify, and modify DN operations, the LDAP result message for the operation
077 * may contain zero or one get backend set ID response control.  For extended
078 * operations, the extended result message may contain zero, one, or multiple
079 * get backend set ID response controls.  For search operations, each search
080 * result entry may contain zero or one get backend set ID response control,
081 * while the search result done message will not contain any such control.  See
082 * the {@link GetBackendSetIDRequestControl} class documentation for a more
083 * complete description of the usage for these controls.
084 * <BR>
085 * <BLOCKQUOTE>
086 *   <B>NOTE:</B>  This class, and other classes within the
087 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
088 *   supported for use against Ping Identity, UnboundID, and
089 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
090 *   for proprietary functionality or for external specifications that are not
091 *   considered stable or mature enough to be guaranteed to work in an
092 *   interoperable way with other types of LDAP servers.
093 * </BLOCKQUOTE>
094 * <BR>
095 * The get backend set ID response control has an OID of
096 * "1.3.6.1.4.1.30221.2.5.34", a criticality of false, and a value with the
097 * following encoding:
098 * <PRE>
099 *   GET_BACKEND_SET_ID_RESPONSE_VALUE ::= SEQUENCE {
100 *     entryBalancingRequestProcessorID     OCTET STRING,
101 *     backendSetIDs                        SET SIZE (1..MAX) OF OCTET STRING,
102 *     ... }
103 * </PRE>
104 *
105 * @see  GetBackendSetIDRequestControl
106 * @see  RouteToBackendSetRequestControl
107 */
108@NotMutable()
109@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
110public final class GetBackendSetIDResponseControl
111       extends Control
112       implements DecodeableControl
113{
114  /**
115   * The OID (1.3.6.1.4.1.30221.2.5.34) for the get backend set ID response
116   * control.
117   */
118  public static final  String GET_BACKEND_SET_ID_RESPONSE_OID =
119       "1.3.6.1.4.1.30221.2.5.34";
120
121
122
123  /**
124   * The serial version UID for this serializable class.
125   */
126  private static final long serialVersionUID = 117359364981309726L;
127
128
129
130  // The backend set IDs for backend sets used during processing.
131  private final Set<String> backendSetIDs;
132
133  // The identifier for the entry-balancing request processor with which the
134  // backend set IDs are associated.
135  private final String entryBalancingRequestProcessorID;
136
137
138
139  /**
140   * Creates a new empty control instance that is intended to be used only for
141   * decoding controls via the {@code DecodeableControl} interface.
142   */
143  GetBackendSetIDResponseControl()
144  {
145    entryBalancingRequestProcessorID = null;
146    backendSetIDs = null;
147  }
148
149
150
151  /**
152   * Creates a new get backend set ID response control with the provided
153   * information.
154   *
155   * @param  entryBalancingRequestProcessorID  The identifier for the
156   *                                           entry-balancing request processor
157   *                                           with which the backend set IDs
158   *                                           are associated.  It must not be
159   *                                           {@code null}.
160   * @param  backendSetID                      The backend set ID for the
161   *                                           backend set used during
162   *                                           processing.  It must not be
163   *                                           {@code null}.
164   */
165  public GetBackendSetIDResponseControl(
166              final String entryBalancingRequestProcessorID,
167              final String backendSetID)
168  {
169    this(entryBalancingRequestProcessorID,
170         Collections.singletonList(backendSetID));
171  }
172
173
174
175  /**
176   * Creates a new get backend set ID response control with the provided
177   * information.
178   *
179   * @param  entryBalancingRequestProcessorID  The identifier for the
180   *                                           entry-balancing request processor
181   *                                           with which the backend set IDs
182   *                                           are associated.  It must not be
183   *                                           {@code null}.
184   * @param  backendSetIDs                     The backend set IDs for backend
185   *                                           sets used during processing.  It
186   *                                           must not be {@code null} or
187   *                                           empty.
188   */
189  public GetBackendSetIDResponseControl(
190              final String entryBalancingRequestProcessorID,
191              final Collection<String> backendSetIDs)
192  {
193    super(GET_BACKEND_SET_ID_RESPONSE_OID, false,
194         encodeValue(entryBalancingRequestProcessorID, backendSetIDs));
195
196    this.entryBalancingRequestProcessorID = entryBalancingRequestProcessorID;
197    this.backendSetIDs =
198         Collections.unmodifiableSet(new LinkedHashSet<>(backendSetIDs));
199  }
200
201
202
203  /**
204   * Creates a new get backend set ID response control decoded from the given
205   * generic control contents.
206   *
207   * @param  oid         The OID for the control.
208   * @param  isCritical  Indicates whether this control should be marked
209   *                     critical.
210   * @param  value       The encoded value for the control.
211   *
212   * @throws LDAPException  If a problem occurs while attempting to decode the
213   *                        generic control as a get backend set ID response
214   *                        control.
215   */
216  public GetBackendSetIDResponseControl(final String oid,
217                                        final boolean isCritical,
218                                        final ASN1OctetString value)
219       throws LDAPException
220  {
221    super(oid, isCritical, value);
222
223    if (value == null)
224    {
225      throw new LDAPException(ResultCode.DECODING_ERROR,
226           ERR_GET_BACKEND_SET_ID_RESPONSE_MISSING_VALUE.get());
227    }
228
229    try
230    {
231      final ASN1Element[] elements =
232           ASN1Sequence.decodeAsSequence(value.getValue()).elements();
233      entryBalancingRequestProcessorID =
234           ASN1OctetString.decodeAsOctetString(elements[0]).stringValue();
235
236      final ASN1Element[] backendSetIDElements =
237           ASN1Set.decodeAsSet(elements[1]).elements();
238      final LinkedHashSet<String> setIDs = new LinkedHashSet<>(
239           StaticUtils.computeMapCapacity(backendSetIDElements.length));
240      for (final ASN1Element e : backendSetIDElements)
241      {
242        setIDs.add(ASN1OctetString.decodeAsOctetString(e).stringValue());
243      }
244      backendSetIDs = Collections.unmodifiableSet(setIDs);
245    }
246    catch (final Exception e)
247    {
248      Debug.debugException(e);
249      throw new LDAPException(ResultCode.DECODING_ERROR,
250           ERR_GET_BACKEND_SET_ID_RESPONSE_CANNOT_DECODE.get(
251                StaticUtils.getExceptionMessage(e)),
252           e);
253    }
254  }
255
256
257
258  /**
259   * Encodes the provided information into an octet string suitable for use as
260   * the value of this control.
261   *
262   * @param  entryBalancingRequestProcessorID  The identifier for the
263   *                                           entry-balancing request processor
264   *                                           with which the backend set IDs
265   *                                           are associated.  It must not be
266   *                                           {@code null}.
267   * @param  backendSetIDs                     The backend set IDs for backend
268   *                                           sets used during processing.  It
269   *                                           must not be {@code null} or
270   *                                           empty.
271   *
272   * @return  The encoded representation of the control value.
273   */
274  private static ASN1OctetString encodeValue(
275                      final String entryBalancingRequestProcessorID,
276                      final Collection<String> backendSetIDs)
277  {
278    Validator.ensureNotNull(entryBalancingRequestProcessorID);
279    Validator.ensureNotNull(backendSetIDs);
280    Validator.ensureFalse(backendSetIDs.isEmpty());
281
282    final ArrayList<ASN1Element> backendSetIDElements =
283         new ArrayList<>(backendSetIDs.size());
284    for (final String s : backendSetIDs)
285    {
286      backendSetIDElements.add(new ASN1OctetString(s));
287    }
288
289    final ASN1Sequence valueSequence = new ASN1Sequence(
290         new ASN1OctetString(entryBalancingRequestProcessorID),
291         new ASN1Set(backendSetIDElements));
292    return new ASN1OctetString(valueSequence.encode());
293  }
294
295
296
297  /**
298   * {@inheritDoc}
299   */
300  @Override()
301  public GetBackendSetIDResponseControl decodeControl(final String oid,
302                                             final boolean isCritical,
303                                             final ASN1OctetString value)
304         throws LDAPException
305  {
306    return new GetBackendSetIDResponseControl(oid, isCritical, value);
307  }
308
309
310
311  /**
312   * Retrieves the identifier for the entry-balancing request processor with
313   * which the backend sets IDs are associated.
314   *
315   * @return  The identifier for the entry-balancing request processor with
316   *          which the backend set IDs are associated.
317   */
318  public String getEntryBalancingRequestProcessorID()
319  {
320    return entryBalancingRequestProcessorID;
321  }
322
323
324
325  /**
326   * Retrieves the backend set IDs for the backend sets used during processing.
327   *
328   * @return  The backend set IDs for the backend sets used during processing.
329   */
330  public Set<String> getBackendSetIDs()
331  {
332    return backendSetIDs;
333  }
334
335
336
337  /**
338   * Extracts a get backend set ID response control from the provided result.
339   *
340   * @param  result  The result from which to retrieve the get backend set ID
341   *                 response control.
342   *
343   * @return  The get backend set ID response control contained in the provided
344   *          result, or {@code null} if the result did not contain a get
345   *          backend set ID response control.
346   *
347   * @throws  LDAPException  If a problem is encountered while attempting to
348   *                         decode the get backend set ID response control
349   *                         contained in the provided result.
350   */
351  public static GetBackendSetIDResponseControl get(final LDAPResult result)
352         throws LDAPException
353  {
354    final Control c =
355         result.getResponseControl(GET_BACKEND_SET_ID_RESPONSE_OID);
356    if (c == null)
357    {
358      return null;
359    }
360
361    if (c instanceof GetBackendSetIDResponseControl)
362    {
363      return (GetBackendSetIDResponseControl) c;
364    }
365    else
366    {
367      return new GetBackendSetIDResponseControl(c.getOID(), c.isCritical(),
368           c.getValue());
369    }
370  }
371
372
373
374  /**
375   * Extracts a get backend set ID response control from the provided search
376   * result entry.
377   *
378   * @param  entry  The entry from which to retrieve the get backend set ID
379   *                response control.
380   *
381   * @return  The get backend set ID response control contained in the provided
382   *          entry, or {@code null} if the entry did not contain a get backend
383   *          set ID response control.
384   *
385   * @throws  LDAPException  If a problem is encountered while attempting to
386   *                         decode the get backend set ID response control
387   *                         contained in the provided result.
388   */
389  public static GetBackendSetIDResponseControl
390                     get(final SearchResultEntry entry)
391         throws LDAPException
392  {
393    final Control c = entry.getControl(GET_BACKEND_SET_ID_RESPONSE_OID);
394    if (c == null)
395    {
396      return null;
397    }
398
399    if (c instanceof GetBackendSetIDResponseControl)
400    {
401      return (GetBackendSetIDResponseControl) c;
402    }
403    else
404    {
405      return new GetBackendSetIDResponseControl(c.getOID(), c.isCritical(),
406           c.getValue());
407    }
408  }
409
410
411
412  /**
413   * Extracts any get backend set ID response controls from the provided
414   * extended result.
415   *
416   * @param  result  The extended result from which to retrieve the get backend
417   *                 set ID response control(s).
418   *
419   * @return  A list of get backend set ID response controls contained in the
420   *          provided extended result, or an empty list if the result did not
421   *          contain a get any backend set ID response controls.
422   *
423   * @throws  LDAPException  If a problem is encountered while attempting to
424   *                         decode the any backend set ID response control
425   *                         contained in the provided result.
426   */
427  public static List<GetBackendSetIDResponseControl>
428                     get(final ExtendedResult result)
429         throws LDAPException
430  {
431    final Control[] controls = result.getResponseControls();
432    if (controls.length == 0)
433    {
434      return Collections.emptyList();
435    }
436
437    final ArrayList<GetBackendSetIDResponseControl> decodedControls =
438         new ArrayList<>(controls.length);
439    for (final Control c : controls)
440    {
441      if (c instanceof GetBackendSetIDResponseControl)
442      {
443        decodedControls.add((GetBackendSetIDResponseControl) c);
444      }
445      else if (c.getOID().equals(GET_BACKEND_SET_ID_RESPONSE_OID))
446      {
447        decodedControls.add(new GetBackendSetIDResponseControl(c.getOID(),
448             c.isCritical(), c.getValue()));
449      }
450    }
451
452    return Collections.unmodifiableList(decodedControls);
453  }
454
455
456
457  /**
458   * {@inheritDoc}
459   */
460  @Override()
461  public String getControlName()
462  {
463    return INFO_CONTROL_NAME_GET_BACKEND_SET_ID_RESPONSE.get();
464  }
465
466
467
468  /**
469   * {@inheritDoc}
470   */
471  @Override()
472  public void toString(final StringBuilder buffer)
473  {
474    buffer.append("GetBackendSetIDResponseControl(" +
475         "entryBalancingRequestProcessorID='");
476    buffer.append(entryBalancingRequestProcessorID);
477    buffer.append("', backendSetIDs={");
478
479    final Iterator<String> iterator = backendSetIDs.iterator();
480    while (iterator.hasNext())
481    {
482      buffer.append('\'');
483      buffer.append(iterator.next());
484      buffer.append('\'');
485
486      if (iterator.hasNext())
487      {
488        buffer.append(", ");
489      }
490    }
491
492    buffer.append("})");
493  }
494}