001/*
002 * Copyright 2013-2024 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2013-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) 2013-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.unboundidds.extensions;
037
038
039
040import com.unboundid.ldap.sdk.Control;
041import com.unboundid.ldap.sdk.ExtendedRequest;
042import com.unboundid.ldap.sdk.ExtendedResult;
043import com.unboundid.ldap.sdk.LDAPConnection;
044import com.unboundid.ldap.sdk.LDAPException;
045import com.unboundid.ldap.sdk.ResultCode;
046import com.unboundid.util.NotNull;
047import com.unboundid.util.Nullable;
048import com.unboundid.util.ThreadSafety;
049import com.unboundid.util.ThreadSafetyLevel;
050
051import static com.unboundid.ldap.sdk.unboundidds.extensions.ExtOpMessages.*;
052
053
054
055/**
056 * This class provides an implementation of an extended request that can be used
057 * to retrieve a list of all available versions of the configuration within a
058 * server.  This may include not only the currently-active configuration, but
059 * also former configurations that have been archived, and the baseline
060 * configuration for the current server version.
061 * <BR>
062 * <BLOCKQUOTE>
063 *   <B>NOTE:</B>  This class, and other classes within the
064 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
065 *   supported for use against Ping Identity, UnboundID, and
066 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
067 *   for proprietary functionality or for external specifications that are not
068 *   considered stable or mature enough to be guaranteed to work in an
069 *   interoperable way with other types of LDAP servers.
070 * </BLOCKQUOTE>
071 * <BR>
072 * The OID for this extended request is 1.3.6.1.4.1.30221.2.6.26.  It does not
073 * have a value.
074 * <BR><BR>
075 * <H2>Example</H2>
076 * The following example demonstrates the process for using the list
077 * configurations and get configuration extended requests to obtain the oldest
078 * archived configuration from the server:
079 * <PRE>
080 * // Get a list of the available configurations from the server.
081 * ListConfigurationsExtendedResult listConfigsResult =
082 *      (ListConfigurationsExtendedResult)
083 *      connection.processExtendedOperation(
084 *           new ListConfigurationsExtendedRequest());
085 * String archivedConfigFileName =
086 *      listConfigsResult.getArchivedFileNames().get(0);
087 *
088 * // Retrieve the first archived configuration from the list configurations
089 * // result.
090 * GetConfigurationExtendedResult getConfigResult =
091 *      (GetConfigurationExtendedResult)
092 *      connection.processExtendedOperation(GetConfigurationExtendedRequest.
093 *           createGetArchivedConfigurationRequest(archivedConfigFileName));
094 *
095 * InputStream fileDataStream = getConfigResult.getFileDataInputStream();
096 * // Read data from the file.
097 * fileDataStream.close();
098 * </PRE>
099 *
100 * @see  GetConfigurationExtendedRequest
101 */
102@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
103public final class ListConfigurationsExtendedRequest
104       extends ExtendedRequest
105{
106  /**
107   * The OID (1.3.6.1.4.1.30221.2.6.26) for the list configurations extended
108   * request.
109   */
110  @NotNull public static final  String LIST_CONFIGS_REQUEST_OID =
111       "1.3.6.1.4.1.30221.2.6.26";
112
113
114
115  /**
116   * The serial version UID for this serializable class.
117   */
118  private static final long serialVersionUID = -5511054471842622735L;
119
120
121
122  /**
123   * Creates a new list configurations extended request with the provided
124   * information.
125   *
126   * @param  controls  An optional set of controls to include in the request.
127   *                   This may be {@code null} or empty if no controls should
128   *                   be included in the request.
129   */
130  public ListConfigurationsExtendedRequest(@Nullable final Control... controls)
131  {
132    super(LIST_CONFIGS_REQUEST_OID, controls);
133  }
134
135
136
137  /**
138   * Creates a new list configurations extended request that has been decoded
139   * from the provided generic extended request.
140   *
141   * @param  r  The generic extended request to decode as a list configurations
142   *            extended request.
143   *
144   * @throws LDAPException  If the provided request cannot be decoded as a
145   *                         valid list configurations extended request.
146   */
147  public ListConfigurationsExtendedRequest(@NotNull final ExtendedRequest r)
148         throws LDAPException
149  {
150    super(r);
151
152    if (r.hasValue())
153    {
154      throw new LDAPException(ResultCode.DECODING_ERROR,
155           ERR_LIST_CONFIGS_REQUEST_HAS_VALUE.get());
156    }
157  }
158
159
160
161  /**
162   * {@inheritDoc}
163   */
164  @Override()
165  @NotNull()
166  public ListConfigurationsExtendedResult process(
167              @NotNull final LDAPConnection connection, final int depth)
168         throws LDAPException
169  {
170    final ExtendedResult extendedResponse = super.process(connection, depth);
171    return new ListConfigurationsExtendedResult(extendedResponse);
172  }
173
174
175
176  /**
177   * {@inheritDoc}
178   */
179  @Override()
180  @NotNull()
181  public ListConfigurationsExtendedRequest duplicate()
182  {
183    return duplicate(getControls());
184  }
185
186
187
188  /**
189   * {@inheritDoc}
190   */
191  @Override()
192  @NotNull()
193  public ListConfigurationsExtendedRequest duplicate(
194              @Nullable final Control[] controls)
195  {
196    final ListConfigurationsExtendedRequest r =
197         new ListConfigurationsExtendedRequest(controls);
198    r.setResponseTimeoutMillis(getResponseTimeoutMillis(null));
199    r.setIntermediateResponseListener(getIntermediateResponseListener());
200    r.setReferralDepth(getReferralDepth());
201    r.setReferralConnector(getReferralConnectorInternal());
202    return r;
203  }
204
205
206
207  /**
208   * {@inheritDoc}
209   */
210  @Override()
211  @NotNull()
212  public String getExtendedRequestName()
213  {
214    return INFO_EXTENDED_REQUEST_NAME_LIST_CONFIGS.get();
215  }
216
217
218
219  /**
220   * {@inheritDoc}
221   */
222  @Override()
223  public void toString(@NotNull final StringBuilder buffer)
224  {
225    buffer.append("ListConfigurationsExtendedRequest(");
226
227    final Control[] controls = getControls();
228    if (controls.length > 0)
229    {
230      buffer.append("controls={");
231      for (int i=0; i < controls.length; i++)
232      {
233        if (i > 0)
234        {
235          buffer.append(", ");
236        }
237
238        buffer.append(controls[i]);
239      }
240      buffer.append('}');
241    }
242
243    buffer.append(')');
244  }
245}