001/* 002 * Copyright 2009-2020 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2009-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.controls; 037 038 039 040import java.util.ArrayList; 041import java.util.Collection; 042import java.util.Collections; 043import java.util.Iterator; 044import java.util.List; 045 046import com.unboundid.asn1.ASN1Element; 047import com.unboundid.asn1.ASN1OctetString; 048import com.unboundid.asn1.ASN1Sequence; 049import com.unboundid.ldap.sdk.Attribute; 050import com.unboundid.ldap.sdk.Entry; 051import com.unboundid.ldap.sdk.LDAPException; 052import com.unboundid.ldap.sdk.ReadOnlyEntry; 053import com.unboundid.ldap.sdk.ResultCode; 054import com.unboundid.util.Debug; 055import com.unboundid.util.NotMutable; 056import com.unboundid.util.StaticUtils; 057import com.unboundid.util.ThreadSafety; 058import com.unboundid.util.ThreadSafetyLevel; 059 060import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*; 061 062 063 064/** 065 * This class provides a joined entry, which is a read-only representation of an 066 * entry that has been joined with a search result entry using the LDAP join 067 * control. See the class-level documentation for the 068 * {@link JoinRequestControl} class for additional information and an example 069 * demonstrating its use. 070 * <BR> 071 * <BLOCKQUOTE> 072 * <B>NOTE:</B> This class, and other classes within the 073 * {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only 074 * supported for use against Ping Identity, UnboundID, and 075 * Nokia/Alcatel-Lucent 8661 server products. These classes provide support 076 * for proprietary functionality or for external specifications that are not 077 * considered stable or mature enough to be guaranteed to work in an 078 * interoperable way with other types of LDAP servers. 079 * </BLOCKQUOTE> 080 * <BR> 081 * Joined entries are encoded as follows: 082 * <PRE> 083 * JoinedEntry ::= SEQUENCE { 084 * objectName LDAPDN, 085 * attributes PartialAttributeList, 086 * nestedJoinResults SEQUENCE OF JoinedEntry OPTIONAL } 087 * </PRE> 088 */ 089@NotMutable() 090@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 091public final class JoinedEntry 092 extends ReadOnlyEntry 093{ 094 /** 095 * The serial version UID for this serializable class. 096 */ 097 private static final long serialVersionUID = -6519864521813773703L; 098 099 100 101 // The list of nested join results for this joined entry. 102 private final List<JoinedEntry> nestedJoinResults; 103 104 105 106 /** 107 * Creates a new joined entry with the specified DN, attributes, and nested 108 * join results. 109 * 110 * @param entry The entry containing the DN and attributes to 111 * use for this joined entry. It must not be 112 * {@code null}. 113 * @param nestedJoinResults A list of nested join results for this joined 114 * entry. It may be {@code null} or empty if there 115 * are no nested join results. 116 */ 117 public JoinedEntry(final Entry entry, 118 final List<JoinedEntry> nestedJoinResults) 119 { 120 this(entry.getDN(), entry.getAttributes(), nestedJoinResults); 121 } 122 123 124 125 /** 126 * Creates a new joined entry with the specified DN, attributes, and nested 127 * join results. 128 * 129 * @param dn The DN for this joined entry. It must not be 130 * {@code null}. 131 * @param attributes The set of attributes for this joined entry. It 132 * must not be {@code null}. 133 * @param nestedJoinResults A list of nested join results for this joined 134 * entry. It may be {@code null} or empty if there 135 * are no nested join results. 136 */ 137 public JoinedEntry(final String dn, final Collection<Attribute> attributes, 138 final List<JoinedEntry> nestedJoinResults) 139 { 140 super(dn, attributes); 141 142 if (nestedJoinResults == null) 143 { 144 this.nestedJoinResults = Collections.emptyList(); 145 } 146 else 147 { 148 this.nestedJoinResults = Collections.unmodifiableList(nestedJoinResults); 149 } 150 } 151 152 153 154 /** 155 * Encodes this joined entry to an ASN.1 element. 156 * 157 * @return An ASN.1 element containing the encoded representation of this 158 * joined entry. 159 */ 160 ASN1Element encode() 161 { 162 final ArrayList<ASN1Element> elements = new ArrayList<>(3); 163 164 elements.add(new ASN1OctetString(getDN())); 165 166 final ArrayList<ASN1Element> attrElements = new ArrayList<>(20); 167 for (final Attribute a : getAttributes()) 168 { 169 attrElements.add(a.encode()); 170 } 171 elements.add(new ASN1Sequence(attrElements)); 172 173 if (! nestedJoinResults.isEmpty()) 174 { 175 final ArrayList<ASN1Element> nestedElements = 176 new ArrayList<>(nestedJoinResults.size()); 177 for (final JoinedEntry je : nestedJoinResults) 178 { 179 nestedElements.add(je.encode()); 180 } 181 elements.add(new ASN1Sequence(nestedElements)); 182 } 183 184 return new ASN1Sequence(elements); 185 } 186 187 188 189 /** 190 * Decodes the provided ASN.1 element as a joined entry. 191 * 192 * @param element The ASN.1 element to decode as a joined entry. 193 * 194 * @return The decoded joined entry. 195 * 196 * @throws LDAPException If a problem occurs while attempting to decode the 197 * provided ASN.1 element as a joined entry. 198 */ 199 static JoinedEntry decode(final ASN1Element element) 200 throws LDAPException 201 { 202 try 203 { 204 final ASN1Element[] elements = 205 ASN1Sequence.decodeAsSequence(element).elements(); 206 final String dn = 207 ASN1OctetString.decodeAsOctetString(elements[0]).stringValue(); 208 209 final ASN1Element[] attrElements = 210 ASN1Sequence.decodeAsSequence(elements[1]).elements(); 211 final ArrayList<Attribute> attrs = new ArrayList<>(attrElements.length); 212 for (final ASN1Element e : attrElements) 213 { 214 attrs.add(Attribute.decode(ASN1Sequence.decodeAsSequence(e))); 215 } 216 217 final ArrayList<JoinedEntry> nestedJoinResults; 218 if (elements.length == 3) 219 { 220 final ASN1Element[] nestedElements = 221 ASN1Sequence.decodeAsSequence(elements[2]).elements(); 222 nestedJoinResults = new ArrayList<>(nestedElements.length); 223 for (final ASN1Element e : nestedElements) 224 { 225 nestedJoinResults.add(decode(e)); 226 } 227 } 228 else 229 { 230 nestedJoinResults = new ArrayList<>(0); 231 } 232 233 return new JoinedEntry(dn, attrs, nestedJoinResults); 234 } 235 catch (final Exception e) 236 { 237 Debug.debugException(e); 238 239 throw new LDAPException(ResultCode.DECODING_ERROR, 240 ERR_JOINED_ENTRY_CANNOT_DECODE.get( 241 StaticUtils.getExceptionMessage(e)), 242 e); 243 } 244 } 245 246 247 248 /** 249 * Retrieves the list of nested join results for this joined entry. 250 * 251 * @return The list of nested join results for this joined entry, or an 252 * empty list if there are none. 253 */ 254 public List<JoinedEntry> getNestedJoinResults() 255 { 256 return nestedJoinResults; 257 } 258 259 260 261 /** 262 * Appends a string representation of this joined entry to the provided 263 * buffer. 264 * 265 * @param buffer The buffer to which the information should be appended. 266 */ 267 @Override() 268 public void toString(final StringBuilder buffer) 269 { 270 buffer.append("JoinedEntry(dn='"); 271 buffer.append(getDN()); 272 buffer.append("', attributes={"); 273 274 final Iterator<Attribute> attrIterator = getAttributes().iterator(); 275 while (attrIterator.hasNext()) 276 { 277 attrIterator.next().toString(buffer); 278 if (attrIterator.hasNext()) 279 { 280 buffer.append(", "); 281 } 282 } 283 284 buffer.append("}, nestedJoinResults={"); 285 286 final Iterator<JoinedEntry> entryIterator = nestedJoinResults.iterator(); 287 while (entryIterator.hasNext()) 288 { 289 entryIterator.next().toString(buffer); 290 if (entryIterator.hasNext()) 291 { 292 buffer.append(", "); 293 } 294 } 295 296 buffer.append("})"); 297 } 298}