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