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