001/* 002 * Copyright 2010-2020 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2010-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 java.util.ArrayList; 041import java.util.Collection; 042 043import com.unboundid.asn1.ASN1Element; 044import com.unboundid.asn1.ASN1OctetString; 045import com.unboundid.asn1.ASN1Sequence; 046import com.unboundid.ldap.sdk.Attribute; 047import com.unboundid.ldap.sdk.ChangeLogEntry; 048import com.unboundid.ldap.sdk.Control; 049import com.unboundid.ldap.sdk.Entry; 050import com.unboundid.ldap.sdk.IntermediateResponse; 051import com.unboundid.ldap.sdk.LDAPException; 052import com.unboundid.ldap.sdk.LDAPRuntimeException; 053import com.unboundid.ldap.sdk.ResultCode; 054import com.unboundid.ldap.sdk.unboundidds.UnboundIDChangeLogEntry; 055import com.unboundid.util.Base64; 056import com.unboundid.util.Debug; 057import com.unboundid.util.NotMutable; 058import com.unboundid.util.StaticUtils; 059import com.unboundid.util.ThreadSafety; 060import com.unboundid.util.ThreadSafetyLevel; 061import com.unboundid.util.Validator; 062 063import static com.unboundid.ldap.sdk.unboundidds.extensions.ExtOpMessages.*; 064 065 066 067/** 068 * This class provides an implementation of an intermediate response which 069 * provides information about a changelog entry returned from a Directory 070 * Server. 071 * <BR> 072 * <BLOCKQUOTE> 073 * <B>NOTE:</B> This class, and other classes within the 074 * {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only 075 * supported for use against Ping Identity, UnboundID, and 076 * Nokia/Alcatel-Lucent 8661 server products. These classes provide support 077 * for proprietary functionality or for external specifications that are not 078 * considered stable or mature enough to be guaranteed to work in an 079 * interoperable way with other types of LDAP servers. 080 * </BLOCKQUOTE> 081 * <BR> 082 * The changelog entry intermediate response value is encoded as follows: 083 * <PRE> 084 * ChangelogEntryIntermediateResponse ::= SEQUENCE { 085 * resumeToken OCTET STRING, 086 * serverID OCTET STRING, 087 * changelogEntryDN LDAPDN, 088 * changelogEntryAttributes PartialAttributeList, 089 * ... } 090 * </PRE> 091 */ 092@NotMutable() 093@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 094public final class ChangelogEntryIntermediateResponse 095 extends IntermediateResponse 096{ 097 /** 098 * The OID (1.3.6.1.4.1.30221.2.6.11) for the get stream directory values 099 * intermediate response. 100 */ 101 public static final String CHANGELOG_ENTRY_INTERMEDIATE_RESPONSE_OID = 102 "1.3.6.1.4.1.30221.2.6.11"; 103 104 105 106 /** 107 * The serial version UID for this serializable class. 108 */ 109 private static final long serialVersionUID = 5616371094806687752L; 110 111 112 113 // A token that may be used to start retrieving changelog entries 114 // immediately after this entry. 115 private final ASN1OctetString resumeToken; 116 117 // The changelog entry included in this intermediate response. 118 private final UnboundIDChangeLogEntry changeLogEntry; 119 120 // The server ID for the server from which the changelog entry was retrieved. 121 private final String serverID; 122 123 124 125 /** 126 * Creates a new changelog entry intermediate response with the provided 127 * information. 128 * 129 * @param changeLogEntry The changelog entry included in this intermediate 130 * response. It must not be {@code null}. 131 * @param serverID The server ID for the server from which the 132 * changelog entry was received. It must not be 133 * {@code null}. 134 * @param resumeToken A token that may be used to resume the process of 135 * retrieving changes at the point immediately after 136 * this change. It must not be {@code null}. 137 * @param controls The set of controls to include in the response. It 138 * may be {@code null} or empty if no controls should 139 * be included. 140 */ 141 public ChangelogEntryIntermediateResponse( 142 final ChangeLogEntry changeLogEntry, 143 final String serverID, final ASN1OctetString resumeToken, 144 final Control... controls) 145 { 146 super(CHANGELOG_ENTRY_INTERMEDIATE_RESPONSE_OID, 147 encodeValue(changeLogEntry, serverID, resumeToken), controls); 148 149 if (changeLogEntry instanceof UnboundIDChangeLogEntry) 150 { 151 this.changeLogEntry = (UnboundIDChangeLogEntry) changeLogEntry; 152 } 153 else 154 { 155 try 156 { 157 this.changeLogEntry = new UnboundIDChangeLogEntry(changeLogEntry); 158 } 159 catch (final LDAPException le) 160 { 161 // This should never happen. 162 Debug.debugException(le); 163 throw new LDAPRuntimeException(le); 164 } 165 } 166 167 this.serverID = serverID; 168 this.resumeToken = resumeToken; 169 } 170 171 172 173 /** 174 * Creates a new changelog entry intermediate response from the provided 175 * generic intermediate response. 176 * 177 * @param r The generic intermediate response to be decoded. 178 * 179 * @throws LDAPException If the provided intermediate response cannot be 180 * decoded as a changelog entry response. 181 */ 182 public ChangelogEntryIntermediateResponse(final IntermediateResponse r) 183 throws LDAPException 184 { 185 super(r); 186 187 final ASN1OctetString value = r.getValue(); 188 if (value == null) 189 { 190 throw new LDAPException(ResultCode.DECODING_ERROR, 191 ERR_CHANGELOG_ENTRY_IR_NO_VALUE.get()); 192 } 193 194 final ASN1Sequence valueSequence; 195 try 196 { 197 valueSequence = ASN1Sequence.decodeAsSequence(value.getValue()); 198 } 199 catch (final Exception e) 200 { 201 Debug.debugException(e); 202 throw new LDAPException(ResultCode.DECODING_ERROR, 203 ERR_CHANGELOG_ENTRY_IR_VALUE_NOT_SEQUENCE.get( 204 StaticUtils.getExceptionMessage(e)), e); 205 } 206 207 final ASN1Element[] valueElements = valueSequence.elements(); 208 if (valueElements.length != 4) 209 { 210 throw new LDAPException(ResultCode.DECODING_ERROR, 211 ERR_CHANGELOG_ENTRY_IR_INVALID_VALUE_COUNT.get( 212 valueElements.length)); 213 } 214 215 resumeToken = ASN1OctetString.decodeAsOctetString(valueElements[0]); 216 217 serverID = 218 ASN1OctetString.decodeAsOctetString(valueElements[1]).stringValue(); 219 220 final String dn = 221 ASN1OctetString.decodeAsOctetString(valueElements[2]).stringValue(); 222 223 try 224 { 225 final ASN1Element[] attrsElements = 226 ASN1Sequence.decodeAsSequence(valueElements[3]).elements(); 227 final ArrayList<Attribute> attributes = 228 new ArrayList<>(attrsElements.length); 229 for (final ASN1Element e : attrsElements) 230 { 231 attributes.add(Attribute.decode(ASN1Sequence.decodeAsSequence(e))); 232 } 233 234 changeLogEntry = new UnboundIDChangeLogEntry(new Entry(dn, attributes)); 235 } 236 catch (final Exception e) 237 { 238 Debug.debugException(e); 239 throw new LDAPException(ResultCode.DECODING_ERROR, 240 ERR_CHANGELOG_ENTRY_IR_ERROR_PARSING_VALUE.get( 241 StaticUtils.getExceptionMessage(e)), e); 242 } 243 } 244 245 246 247 /** 248 * Encodes the provided information in a form suitable for use as the value of 249 * this intermediate response. 250 * 251 * @param changeLogEntry The changelog entry included in this intermediate 252 * response. 253 * @param serverID The server ID for the server from which the 254 * changelog entry was received. 255 * @param resumeToken A token that may be used to resume the process of 256 * retrieving changes at the point immediately after 257 * this change. 258 * 259 * @return The encoded value. 260 */ 261 private static ASN1OctetString encodeValue( 262 final ChangeLogEntry changeLogEntry, 263 final String serverID, 264 final ASN1OctetString resumeToken) 265 { 266 Validator.ensureNotNull(changeLogEntry); 267 Validator.ensureNotNull(serverID); 268 Validator.ensureNotNull(resumeToken); 269 270 final Collection<Attribute> attrs = changeLogEntry.getAttributes(); 271 final ArrayList<ASN1Element> attrElements = 272 new ArrayList<>(attrs.size()); 273 for (final Attribute a : attrs) 274 { 275 attrElements.add(a.encode()); 276 } 277 278 final ASN1Sequence s = new ASN1Sequence( 279 resumeToken, 280 new ASN1OctetString(serverID), 281 new ASN1OctetString(changeLogEntry.getDN()), 282 new ASN1Sequence(attrElements)); 283 284 return new ASN1OctetString(s.encode()); 285 } 286 287 288 289 /** 290 * Retrieves the changelog entry contained in this intermediate response. 291 * 292 * @return The changelog entry contained in this intermediate response. 293 */ 294 public UnboundIDChangeLogEntry getChangeLogEntry() 295 { 296 return changeLogEntry; 297 } 298 299 300 301 /** 302 * Retrieves the server ID for the server from which the changelog entry was 303 * retrieved. 304 * 305 * @return The server ID for the server from which the changelog entry was 306 * retrieved. 307 */ 308 public String getServerID() 309 { 310 return serverID; 311 } 312 313 314 315 /** 316 * Retrieves a token that may be used to resume the process of retrieving 317 * changes at the point immediately after this change. 318 * 319 * @return A token that may be used to resume the process of retrieving 320 * changes at the point immediately after this change. 321 */ 322 public ASN1OctetString getResumeToken() 323 { 324 return resumeToken; 325 } 326 327 328 329 /** 330 * {@inheritDoc} 331 */ 332 @Override() 333 public String getIntermediateResponseName() 334 { 335 return INFO_CHANGELOG_ENTRY_IR_NAME.get(); 336 } 337 338 339 340 /** 341 * {@inheritDoc} 342 */ 343 @Override() 344 public String valueToString() 345 { 346 final StringBuilder buffer = new StringBuilder(); 347 348 buffer.append("changeNumber='"); 349 buffer.append(changeLogEntry.getChangeNumber()); 350 buffer.append("' changeType='"); 351 buffer.append(changeLogEntry.getChangeType().getName()); 352 buffer.append("' targetDN='"); 353 buffer.append(changeLogEntry.getTargetDN()); 354 buffer.append("' serverID='"); 355 buffer.append(serverID); 356 buffer.append("' resumeToken='"); 357 Base64.encode(resumeToken.getValue(), buffer); 358 buffer.append('\''); 359 360 return buffer.toString(); 361 } 362 363 364 365 /** 366 * {@inheritDoc} 367 */ 368 @Override() 369 public void toString(final StringBuilder buffer) 370 { 371 buffer.append("ChangelogEntryIntermediateResponse("); 372 373 final int messageID = getMessageID(); 374 if (messageID >= 0) 375 { 376 buffer.append("messageID="); 377 buffer.append(messageID); 378 buffer.append(", "); 379 } 380 381 buffer.append("changelogEntry="); 382 changeLogEntry.toString(buffer); 383 buffer.append(", serverID='"); 384 buffer.append(serverID); 385 buffer.append("', resumeToken='"); 386 Base64.encode(resumeToken.getValue(), buffer); 387 buffer.append('\''); 388 389 final Control[] controls = getControls(); 390 if (controls.length > 0) 391 { 392 buffer.append(", controls={"); 393 for (int i=0; i < controls.length; i++) 394 { 395 if (i > 0) 396 { 397 buffer.append(", "); 398 } 399 400 buffer.append(controls[i]); 401 } 402 buffer.append('}'); 403 } 404 405 buffer.append(')'); 406 } 407}