001/* 002 * Copyright 2013-2018 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2015-2018 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}