001/*
002 * Copyright 2007-2022 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2007-2022 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) 2007-2022 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 com.unboundid.asn1.ASN1Element;
041import com.unboundid.asn1.ASN1Enumerated;
042import com.unboundid.asn1.ASN1Exception;
043import com.unboundid.asn1.ASN1OctetString;
044import com.unboundid.asn1.ASN1Sequence;
045import com.unboundid.ldap.sdk.Control;
046import com.unboundid.ldap.sdk.DecodeableControl;
047import com.unboundid.ldap.sdk.LDAPException;
048import com.unboundid.ldap.sdk.ResultCode;
049import com.unboundid.ldap.sdk.SearchResult;
050import com.unboundid.util.Debug;
051import com.unboundid.util.NotMutable;
052import com.unboundid.util.NotNull;
053import com.unboundid.util.Nullable;
054import com.unboundid.util.ThreadSafety;
055import com.unboundid.util.ThreadSafetyLevel;
056
057import static com.unboundid.ldap.sdk.controls.ControlMessages.*;
058
059
060
061/**
062 * This class provides an implementation of the server-side sort response
063 * control, as defined in
064 * <A HREF="http://www.ietf.org/rfc/rfc2891.txt">RFC 2891</A>.  It may be used
065 * to provide information about the result of server-side sort processing.  If
066 * the corresponding search request included the
067 * {@link ServerSideSortRequestControl}, then the search result done message
068 * may include this response control to provide information about the state of
069 * the sorting.
070 */
071@NotMutable()
072@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
073public final class ServerSideSortResponseControl
074       extends Control
075       implements DecodeableControl
076{
077  /**
078   * The OID (1.2.840.113556.1.4.474) for the server-side sort response control.
079   */
080  @NotNull public static final String SERVER_SIDE_SORT_RESPONSE_OID =
081       "1.2.840.113556.1.4.474";
082
083
084
085  /**
086   * The BER type to use for the element that holds the attribute type.
087   */
088  private static final byte TYPE_ATTRIBUTE_TYPE = (byte) 0x80;
089
090
091
092  /**
093   * The serial version UID for this serializable class.
094   */
095  private static final long serialVersionUID = -8707533262822875822L;
096
097
098
099  // The result code for this server-side sort response control.
100  @NotNull private final ResultCode resultCode;
101
102  // The name of the attribute associated with this result, if available.
103  @Nullable private final String attributeName;
104
105
106
107  /**
108   * Creates a new empty control instance that is intended to be used only for
109   * decoding controls via the {@code DecodeableControl} interface.
110   */
111  ServerSideSortResponseControl()
112  {
113    resultCode    = null;
114    attributeName = null;
115  }
116
117
118
119  /**
120   * Creates a new server-side sort response control with the provided
121   * information.
122   *
123   * @param  resultCode     The result code for this server-side sort response.
124   * @param  attributeName  The name of the attribute associated with this
125   *                        result.  It may be {@code null} if there is no
126   *                        associated attribute name.
127   */
128  public ServerSideSortResponseControl(@NotNull final ResultCode resultCode,
129                                       @Nullable final String attributeName)
130  {
131    this(resultCode, attributeName, false);
132  }
133
134
135
136  /**
137   * Creates a new server-side sort response control with the provided
138   * information.
139   *
140   * @param  resultCode     The result code for this server-side sort response.
141   * @param  attributeName  The name of the attribute associated with this
142   *                        result.  It may be {@code null} if there is no
143   *                        associated attribute name.
144   * @param  isCritical     Indicates whether this control should be marked
145   *                        critical.  Response controls should generally not be
146   *                        critical.
147   */
148  public ServerSideSortResponseControl(@NotNull final ResultCode resultCode,
149                                       @Nullable final String attributeName,
150                                       final boolean isCritical)
151  {
152    super(SERVER_SIDE_SORT_RESPONSE_OID, isCritical,
153          encodeValue(resultCode, attributeName));
154
155    this.resultCode    = resultCode;
156    this.attributeName = attributeName;
157  }
158
159
160
161  /**
162   * Creates a new server-side sort response control from the information
163   * contained in the provided control.
164   *
165   * @param  oid         The OID for the control.
166   * @param  isCritical  Indicates whether the control should be marked
167   *                     critical.
168   * @param  value       The encoded value for the control.  This may be
169   *                     {@code null} if no value was provided.
170   *
171   * @throws  LDAPException  If a problem occurs while attempting to decode the
172   *                         provided control as a server-side sort response
173   *                         control.
174   */
175  public ServerSideSortResponseControl(@NotNull final String oid,
176                                       final boolean isCritical,
177                                       @Nullable final ASN1OctetString value)
178         throws LDAPException
179  {
180    super(oid, isCritical, value);
181
182    if (value == null)
183    {
184      throw new LDAPException(ResultCode.DECODING_ERROR,
185                              ERR_SORT_RESPONSE_NO_VALUE.get());
186    }
187
188    final ASN1Sequence valueSequence;
189    try
190    {
191      final ASN1Element valueElement =
192           ASN1Element.decode(value.getValue());
193      valueSequence = ASN1Sequence.decodeAsSequence(valueElement);
194    }
195    catch (final ASN1Exception ae)
196    {
197      Debug.debugException(ae);
198      throw new LDAPException(ResultCode.DECODING_ERROR,
199                              ERR_SORT_RESPONSE_VALUE_NOT_SEQUENCE.get(ae), ae);
200    }
201
202    final ASN1Element[] valueElements = valueSequence.elements();
203    if ((valueElements.length < 1) || (valueElements.length > 2))
204    {
205      throw new LDAPException(ResultCode.DECODING_ERROR,
206                              ERR_SORT_RESPONSE_INVALID_ELEMENT_COUNT.get(
207                                   valueElements.length));
208    }
209
210    try
211    {
212      final int rc =
213           ASN1Enumerated.decodeAsEnumerated(valueElements[0]).intValue();
214      resultCode = ResultCode.valueOf(rc);
215    }
216    catch (final ASN1Exception ae)
217    {
218      Debug.debugException(ae);
219      throw new LDAPException(ResultCode.DECODING_ERROR,
220                              ERR_SORT_RESPONSE_FIRST_NOT_ENUM.get(ae), ae);
221    }
222
223    if (valueElements.length == 2)
224    {
225      attributeName =
226           ASN1OctetString.decodeAsOctetString(valueElements[1]).stringValue();
227    }
228    else
229    {
230      attributeName = null;
231    }
232  }
233
234
235
236  /**
237   * {@inheritDoc}
238   */
239  @Override()
240  @NotNull()
241  public ServerSideSortResponseControl decodeControl(@NotNull final String oid,
242              final boolean isCritical,
243              @Nullable final ASN1OctetString value)
244         throws LDAPException
245  {
246    return new ServerSideSortResponseControl(oid, isCritical, value);
247  }
248
249
250
251  /**
252   * Extracts a server-side sort response control from the provided result.
253   *
254   * @param  result  The result from which to retrieve the server-side sort
255   *                 response control.
256   *
257   * @return  The server-side sort response control contained in the provided
258   *          result, or {@code null} if the result did not contain a
259   *          server-side sort response control.
260   *
261   * @throws  LDAPException  If a problem is encountered while attempting to
262   *                         decode the server-side sort response control
263   *                         contained in the provided result.
264   */
265  @Nullable()
266  public static ServerSideSortResponseControl get(
267                     @NotNull final SearchResult result)
268         throws LDAPException
269  {
270    final Control c = result.getResponseControl(SERVER_SIDE_SORT_RESPONSE_OID);
271    if (c == null)
272    {
273      return null;
274    }
275
276    if (c instanceof ServerSideSortResponseControl)
277    {
278      return (ServerSideSortResponseControl) c;
279    }
280    else
281    {
282      return new ServerSideSortResponseControl(c.getOID(), c.isCritical(),
283           c.getValue());
284    }
285  }
286
287
288
289  /**
290   * Encodes the provided information into an octet string that can be used as
291   * the value for this control.
292   *
293   * @param  resultCode     The result code for this server-side sort response
294   *                        control.
295   * @param  attributeName  The attribute name to include in the control, or
296   *                        {@code null} if it should not be provided.
297   *
298   * @return  An ASN.1 octet string that can be used as the value for this
299   *          control.
300   */
301  @NotNull()
302  private static ASN1OctetString encodeValue(
303                      @NotNull final ResultCode resultCode,
304                      @Nullable final String attributeName)
305  {
306    final ASN1Element[] valueElements;
307    if (attributeName == null)
308    {
309      valueElements = new ASN1Element[]
310      {
311        new ASN1Enumerated(resultCode.intValue())
312      };
313    }
314    else
315    {
316      valueElements = new ASN1Element[]
317      {
318        new ASN1Enumerated(resultCode.intValue()),
319        new ASN1OctetString(TYPE_ATTRIBUTE_TYPE, attributeName)
320      };
321    }
322
323    return new ASN1OctetString(new ASN1Sequence(valueElements).encode());
324  }
325
326
327
328  /**
329   * Retrieves the result code for this server-side sort response control.
330   *
331   * @return  The result code for this server-side sort response control.
332   */
333  @NotNull()
334  public ResultCode getResultCode()
335  {
336    return resultCode;
337  }
338
339
340
341  /**
342   * Retrieves the attribute name for this server-side sort response control, if
343   * available.
344   *
345   * @return  The attribute name for this server-side sort response control, or
346   *          {@code null} if none was provided.
347   */
348  @Nullable()
349  public String getAttributeName()
350  {
351    return attributeName;
352  }
353
354
355
356  /**
357   * {@inheritDoc}
358   */
359  @Override()
360  @NotNull()
361  public String getControlName()
362  {
363    return INFO_CONTROL_NAME_SORT_RESPONSE.get();
364  }
365
366
367
368  /**
369   * {@inheritDoc}
370   */
371  @Override()
372  public void toString(@NotNull final StringBuilder buffer)
373  {
374    buffer.append("ServerSideSortResponseControl(resultCode=");
375    buffer.append(resultCode);
376
377    if (attributeName != null)
378    {
379      buffer.append(", attributeName='");
380      buffer.append(attributeName);
381      buffer.append('\'');
382    }
383
384    buffer.append(')');
385  }
386}