001/*
002 * Copyright 2013-2019 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2015-2019 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.extensions;
022
023
024
025import com.unboundid.asn1.ASN1Element;
026import com.unboundid.asn1.ASN1OctetString;
027import com.unboundid.asn1.ASN1Sequence;
028import com.unboundid.ldap.sdk.Control;
029import com.unboundid.ldap.sdk.ExtendedRequest;
030import com.unboundid.ldap.sdk.ExtendedResult;
031import com.unboundid.ldap.sdk.LDAPConnection;
032import com.unboundid.ldap.sdk.LDAPException;
033import com.unboundid.ldap.sdk.ResultCode;
034import com.unboundid.util.Debug;
035import com.unboundid.util.StaticUtils;
036import com.unboundid.util.ThreadSafety;
037import com.unboundid.util.ThreadSafetyLevel;
038import com.unboundid.util.Validator;
039
040import static com.unboundid.ldap.sdk.unboundidds.extensions.ExtOpMessages.*;
041
042
043
044/**
045 * This class provides an implementation of an extended request that can be used
046 * to retrieve backup compatibility data for a Directory Server backend.  This
047 * includes both a token that can be used to compare compatibility data with
048 * other servers (or potentially the same server at a later date, for example
049 * to check compatibility after upgrading to a new version), and a set of
050 * capability strings that may provide additional context about how the backup
051 * descriptor may be used.
052 * <BR>
053 * <BLOCKQUOTE>
054 *   <B>NOTE:</B>  This class, and other classes within the
055 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
056 *   supported for use against Ping Identity, UnboundID, and
057 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
058 *   for proprietary functionality or for external specifications that are not
059 *   considered stable or mature enough to be guaranteed to work in an
060 *   interoperable way with other types of LDAP servers.
061 * </BLOCKQUOTE>
062 * <BR>
063 * The OID for this extended request is 1.3.6.1.4.1.30221.2.6.30.  It must have
064 * a value with the following encoding:
065 * <PRE>
066 *   GetBackupCompatibilityDescriptorRequest ::= SEQUENCE {
067 *        baseDN     [0] OCTET STRING,
068 *        ... }
069 * </PRE>
070 *
071 * @see  GetBackupCompatibilityDescriptorExtendedResult
072 * @see  IdentifyBackupCompatibilityProblemsExtendedRequest
073 */
074@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
075public final class GetBackupCompatibilityDescriptorExtendedRequest
076       extends ExtendedRequest
077{
078  /**
079   * The OID (1.3.6.1.4.1.30221.2.6.30) for the get backup compatibility
080   * descriptor extended request.
081   */
082  public static final String GET_BACKUP_COMPATIBILITY_DESCRIPTOR_REQUEST_OID =
083       "1.3.6.1.4.1.30221.2.6.30";
084
085
086
087  /**
088   * The BER type for the base DN element in the value sequence.
089   */
090  private static final byte TYPE_BASE_DN = (byte) 0x80;
091
092
093
094  /**
095   * The serial version UID for this serializable class.
096   */
097  private static final long serialVersionUID = 8170562432854535935L;
098
099
100
101  // The base DN for the backend for which to obtain the backup compatibility
102  // descriptor.
103  private final String baseDN;
104
105
106
107  /**
108   * Creates a new get backup compatibility descriptor extended request with the
109   * provided base DN.
110   *
111   * @param  baseDN    The base DN for the backend for which to obtain the
112   *                   backup compatibility descriptor.  It must not be
113   *                   {@code null}, and should be the base DN of a backend
114   *                   defined in the server.
115   * @param  controls  The set of controls to include in the request.  It may be
116   *                   {@code null} or empty if no controls should be included.
117   */
118  public GetBackupCompatibilityDescriptorExtendedRequest(final String baseDN,
119              final Control... controls)
120  {
121    super(GET_BACKUP_COMPATIBILITY_DESCRIPTOR_REQUEST_OID, encodeValue(baseDN),
122         controls);
123
124    this.baseDN = baseDN;
125  }
126
127
128
129  /**
130   * Creates a new get backup compatibility descriptor extended request from the
131   * provided generic extended request.
132   *
133   * @param  r  The generic extended request to decode as a get backup
134   *            compatibility descriptor extended request.
135   *
136   * @throws LDAPException  If the provided request cannot be decoded as a get
137   *                        backup compatibility descriptor extended request.
138   */
139  public GetBackupCompatibilityDescriptorExtendedRequest(
140       final ExtendedRequest r)
141       throws LDAPException
142  {
143    super(r);
144
145    final ASN1OctetString value = r.getValue();
146    if (value == null)
147    {
148      throw new LDAPException(ResultCode.DECODING_ERROR,
149           ERR_GET_BACKUP_COMPAT_REQUEST_NO_VALUE.get());
150    }
151
152    try
153    {
154      final ASN1Element[] elements =
155           ASN1Sequence.decodeAsSequence(value.getValue()).elements();
156      baseDN = ASN1OctetString.decodeAsOctetString(elements[0]).stringValue();
157    }
158    catch (final Exception e)
159    {
160      Debug.debugException(e);
161      throw new LDAPException(ResultCode.DECODING_ERROR,
162           ERR_GET_BACKUP_COMPAT_REQUEST_ERROR_PARSING_VALUE.get(
163                StaticUtils.getExceptionMessage(e)),
164           e);
165    }
166  }
167
168
169
170  /**
171   * Encodes the provided information into a format suitable for use as the
172   * value of this extended request.
173   *
174   * @param  baseDN  The base DN for the backend for which to obtain the
175   *                 backup compatibility descriptor.  It must not be
176   *                 {@code null}, and should be the base DN of a backend
177   *                 defined in the server.
178   *
179   * @return  The ASN.1 octet string containing the encoded representation of
180   *          the provided information.
181   */
182  private static ASN1OctetString encodeValue(final String baseDN)
183  {
184    Validator.ensureNotNull(baseDN);
185
186    final ASN1Sequence valueSequence = new ASN1Sequence(
187         new ASN1OctetString(TYPE_BASE_DN, baseDN));
188    return new ASN1OctetString(valueSequence.encode());
189  }
190
191
192
193  /**
194   * Retrieves the base DN for the backend for which to obtain the backup
195   * compatibility descriptor.
196   *
197   * @return  The base DN for the backend for which to obtain the backup
198   *          compatibility descriptor.
199   */
200  public String getBaseDN()
201  {
202    return baseDN;
203  }
204
205
206
207  /**
208   * {@inheritDoc}
209   */
210  @Override()
211  public GetBackupCompatibilityDescriptorExtendedResult process(
212              final LDAPConnection connection, final int depth)
213         throws LDAPException
214  {
215    final ExtendedResult extendedResponse = super.process(connection, depth);
216    return new GetBackupCompatibilityDescriptorExtendedResult(extendedResponse);
217  }
218
219
220
221  /**
222   * {@inheritDoc}
223   */
224  @Override()
225  public GetBackupCompatibilityDescriptorExtendedRequest duplicate()
226  {
227    return duplicate(getControls());
228  }
229
230
231
232  /**
233   * {@inheritDoc}
234   */
235  @Override()
236  public GetBackupCompatibilityDescriptorExtendedRequest duplicate(
237              final Control[] controls)
238  {
239    final GetBackupCompatibilityDescriptorExtendedRequest r =
240         new GetBackupCompatibilityDescriptorExtendedRequest(baseDN, controls);
241    r.setResponseTimeoutMillis(getResponseTimeoutMillis(null));
242    return r;
243  }
244
245
246
247  /**
248   * {@inheritDoc}
249   */
250  @Override()
251  public String getExtendedRequestName()
252  {
253    return INFO_EXTENDED_REQUEST_NAME_GET_BACKUP_COMPAT.get();
254  }
255
256
257
258  /**
259   * {@inheritDoc}
260   */
261  @Override()
262  public void toString(final StringBuilder buffer)
263  {
264    buffer.append("GetBackupCompatibilityDescriptorExtendedRequest(baseDN='");
265    buffer.append(baseDN);
266    buffer.append('\'');
267
268    final Control[] controls = getControls();
269    if (controls.length > 0)
270    {
271      buffer.append(", controls={");
272      for (int i=0; i < controls.length; i++)
273      {
274        if (i > 0)
275        {
276          buffer.append(", ");
277        }
278
279        buffer.append(controls[i]);
280      }
281      buffer.append('}');
282    }
283
284    buffer.append(')');
285  }
286}