001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions Copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2009 Sun Microsystems, Inc. 015 * Portions copyright 2012-2016 ForgeRock AS. 016 */ 017 018package org.forgerock.opendj.ldap; 019 020import java.util.Collection; 021import java.util.Iterator; 022import java.util.NoSuchElementException; 023import java.util.Set; 024 025/** 026 * An attribute, comprising of an attribute description and zero or more 027 * attribute values. 028 * <p> 029 * Any methods which perform comparisons between attribute values use the 030 * equality matching rule associated with the attribute description. 031 * <p> 032 * Any methods which accept {@code Object} based attribute values convert the 033 * attribute values to instances of {@code ByteString} using 034 * {@link ByteString#valueOfObject(Object)}. 035 */ 036public interface Attribute extends Set<ByteString> { 037 // TODO: matching against attribute value assertions. 038 039 /** 040 * Adds {@code value} to this attribute if it is not already present 041 * (optional operation). If this attribute already contains {@code value}, 042 * the call leaves the attribute unchanged and returns {@code false}. 043 * 044 * @param value 045 * The attribute value to be added to this attribute. 046 * @return {@code true} if this attribute changed as a result of this call. 047 * @throws UnsupportedOperationException 048 * If this attribute does not support addition of attribute 049 * values. 050 * @throws NullPointerException 051 * If {@code value} was {@code null}. 052 */ 053 @Override 054 boolean add(ByteString value); 055 056 /** 057 * Adds all of the provided attribute values to this attribute if they are 058 * not already present (optional operation). 059 * <p> 060 * Any attribute values which are not instances of {@code ByteString} will 061 * be converted using the {@link ByteString#valueOfObject(Object)} method. 062 * 063 * @param values 064 * The attribute values to be added to this attribute. 065 * @return {@code true} if this attribute changed as a result of this call. 066 * @throws UnsupportedOperationException 067 * If this attribute does not support addition of attribute 068 * values. 069 * @throws NullPointerException 070 * If {@code values} was {@code null}. 071 */ 072 boolean add(Object... values); 073 074 /** 075 * Adds all of the attribute values contained in {@code values} to this 076 * attribute if they are not already present (optional operation). 077 * <p> 078 * An invocation of this method is equivalent to: 079 * 080 * <pre> 081 * attribute.addAll(values, null); 082 * </pre> 083 * 084 * @param values 085 * The attribute values to be added to this attribute. 086 * @return {@code true} if this attribute changed as a result of this call. 087 * @throws UnsupportedOperationException 088 * If this attribute does not support addition of attribute 089 * values. 090 * @throws NullPointerException 091 * If {@code values} was {@code null}. 092 */ 093 @Override 094 boolean addAll(Collection<? extends ByteString> values); 095 096 /** 097 * Adds all of the attribute values contained in {@code values} to this 098 * attribute if they are not already present (optional operation). Any 099 * attribute values which are already present will be added to 100 * {@code duplicateValues} if specified. 101 * <p> 102 * Any attribute values which are not instances of {@code ByteString} will 103 * be converted using the {@link ByteString#valueOfObject(Object)} method. 104 * 105 * @param <T> 106 * The type of the attribute value objects being added. 107 * @param values 108 * The attribute values to be added to this attribute. 109 * @param duplicateValues 110 * A collection into which duplicate values will be added, or 111 * {@code null} if duplicate values should not be saved. 112 * @return {@code true} if this attribute changed as a result of this call. 113 * @throws UnsupportedOperationException 114 * If this attribute does not support addition of attribute 115 * values. 116 * @throws NullPointerException 117 * If {@code values} was {@code null}. 118 */ 119 <T> boolean addAll(Collection<T> values, Collection<? super T> duplicateValues); 120 121 /** 122 * Removes all of the attribute values from this attribute (optional 123 * operation). This attribute will be empty after this call returns. 124 * 125 * @throws UnsupportedOperationException 126 * If this attribute does not support removal of attribute 127 * values. 128 */ 129 @Override 130 void clear(); 131 132 /** 133 * Returns {@code true} if this attribute contains {@code value}. 134 * <p> 135 * If {@code value} is not an instance of {@code ByteString} then it will be 136 * converted using the {@link ByteString#valueOfObject(Object)} method. 137 * 138 * @param value 139 * The attribute value whose presence in this attribute is to be 140 * tested. 141 * @return {@code true} if this attribute contains {@code value}, or 142 * {@code false} if not. 143 * @throws NullPointerException 144 * If {@code value} was {@code null}. 145 */ 146 @Override 147 boolean contains(Object value); 148 149 /** 150 * Returns {@code true} if this attribute contains all of the attribute 151 * values contained in {@code values}. 152 * <p> 153 * Any attribute values which are not instances of {@code ByteString} will 154 * be converted using the {@link ByteString#valueOfObject(Object)} method. 155 * 156 * @param values 157 * The attribute values whose presence in this attribute is to be 158 * tested. 159 * @return {@code true} if this attribute contains all of the attribute 160 * values contained in {@code values}, or {@code false} if not. 161 * @throws NullPointerException 162 * If {@code values} was {@code null}. 163 */ 164 @Override 165 boolean containsAll(Collection<?> values); 166 167 /** 168 * Returns {@code true} if {@code object} is an attribute which is equal to 169 * this attribute. Two attributes are considered equal if their attribute 170 * descriptions are equal, they both have the same number of attribute 171 * values, and every attribute value contained in the first attribute is 172 * also contained in the second attribute. 173 * 174 * @param object 175 * The object to be tested for equality with this attribute. 176 * @return {@code true} if {@code object} is an attribute which is equal to 177 * this attribute, or {@code false} if not. 178 */ 179 @Override 180 boolean equals(Object object); 181 182 /** 183 * Returns the first attribute value in this attribute. 184 * 185 * @return The first attribute value in this attribute. 186 * @throws NoSuchElementException 187 * If this attribute is empty. 188 */ 189 ByteString firstValue(); 190 191 /** 192 * Returns the first attribute value in this attribute decoded as a UTF-8 193 * string. 194 * 195 * @return The first attribute value in this attribute decoded as a UTF-8 196 * string. 197 * @throws NoSuchElementException 198 * If this attribute is empty. 199 */ 200 String firstValueAsString(); 201 202 /** 203 * Returns the attribute description of this attribute, which includes its 204 * attribute type and any options. 205 * 206 * @return The attribute description. 207 */ 208 AttributeDescription getAttributeDescription(); 209 210 /** 211 * Returns the string representation of the attribute description of this 212 * attribute, which includes its attribute type and any options. 213 * 214 * @return The string representation of the attribute description. 215 */ 216 String getAttributeDescriptionAsString(); 217 218 /** 219 * Returns the hash code for this attribute. It will be calculated as the 220 * sum of the hash codes of the attribute description and all of the 221 * attribute values. 222 * 223 * @return The hash code for this attribute. 224 */ 225 @Override 226 int hashCode(); 227 228 /** 229 * Returns {@code true} if this attribute contains no attribute values. 230 * 231 * @return {@code true} if this attribute contains no attribute values. 232 */ 233 @Override 234 boolean isEmpty(); 235 236 /** 237 * Returns an iterator over the attribute values in this attribute. The 238 * attribute values are returned in no particular order, unless the 239 * implementation of this attribute provides such a guarantee. 240 * 241 * @return An iterator over the attribute values in this attribute. 242 */ 243 @Override 244 Iterator<ByteString> iterator(); 245 246 /** 247 * Returns a parser for this attribute which can be used for decoding values 248 * as different types of object. 249 * 250 * @return A parser for this attribute. 251 */ 252 AttributeParser parse(); 253 254 /** 255 * Removes {@code value} from this attribute if it is present (optional 256 * operation). If this attribute does not contain {@code value}, the call 257 * leaves the attribute unchanged and returns {@code false}. 258 * <p> 259 * If {@code value} is not an instance of {@code ByteString} then it will be 260 * converted using the {@link ByteString#valueOfObject(Object)} method. 261 * 262 * @param value 263 * The attribute value to be removed from this attribute. 264 * @return {@code true} if this attribute changed as a result of this call. 265 * @throws UnsupportedOperationException 266 * If this attribute does not support removal of attribute 267 * values. 268 * @throws NullPointerException 269 * If {@code value} was {@code null}. 270 */ 271 @Override 272 boolean remove(Object value); 273 274 /** 275 * Removes all of the attribute values contained in {@code values} from this 276 * attribute if they are present (optional operation). 277 * <p> 278 * Any attribute values which are not instances of {@code ByteString} will 279 * be converted using the {@link ByteString#valueOfObject(Object)} method. 280 * <p> 281 * An invocation of this method is equivalent to: 282 * 283 * <pre> 284 * attribute.removeAll(values, null); 285 * </pre> 286 * 287 * @param values 288 * The attribute values to be removed from this attribute. 289 * @return {@code true} if this attribute changed as a result of this call. 290 * @throws UnsupportedOperationException 291 * If this attribute does not support removal of attribute 292 * values. 293 * @throws NullPointerException 294 * If {@code values} was {@code null}. 295 */ 296 @Override 297 boolean removeAll(Collection<?> values); 298 299 /** 300 * Removes all of the attribute values contained in {@code values} from this 301 * attribute if they are present (optional operation). Any attribute values 302 * which are not already present will be added to {@code missingValues} if 303 * specified. 304 * <p> 305 * Any attribute values which are not instances of {@code ByteString} will 306 * be converted using the {@link ByteString#valueOfObject(Object)} method. 307 * 308 * @param <T> 309 * The type of the attribute value objects being removed. 310 * @param values 311 * The attribute values to be removed from this attribute. 312 * @param missingValues 313 * A collection into which missing values will be added, or 314 * {@code null} if missing values should not be saved. 315 * @return {@code true} if this attribute changed as a result of this call. 316 * @throws UnsupportedOperationException 317 * If this attribute does not support removal of attribute 318 * values. 319 * @throws NullPointerException 320 * If {@code values} was {@code null}. 321 */ 322 <T> boolean removeAll(Collection<T> values, Collection<? super T> missingValues); 323 324 /** 325 * Retains only the attribute values in this attribute which are contained 326 * in {@code values} (optional operation). 327 * <p> 328 * Any attribute values which are not instances of {@code ByteString} will 329 * be converted using the {@link ByteString#valueOfObject(Object)} method. 330 * <p> 331 * An invocation of this method is equivalent to: 332 * 333 * <pre> 334 * attribute.retainAll(values, null); 335 * </pre> 336 * 337 * @param values 338 * The attribute values to be retained in this attribute. 339 * @return {@code true} if this attribute changed as a result of this call. 340 * @throws UnsupportedOperationException 341 * If this attribute does not support removal of attribute 342 * values. 343 * @throws NullPointerException 344 * If {@code values} was {@code null}. 345 */ 346 @Override 347 boolean retainAll(Collection<?> values); 348 349 /** 350 * Retains only the attribute values in this attribute which are contained 351 * in {@code values} (optional operation). Any attribute values which are 352 * not already present will be added to {@code missingValues} if specified. 353 * <p> 354 * Any attribute values which are not instances of {@code ByteString} will 355 * be converted using the {@link ByteString#valueOfObject(Object)} method. 356 * 357 * @param <T> 358 * The type of the attribute value objects being retained. 359 * @param values 360 * The attribute values to be retained in this attribute. 361 * @param missingValues 362 * A collection into which missing values will be added, or 363 * {@code null} if missing values should not be saved. 364 * @return {@code true} if this attribute changed as a result of this call. 365 * @throws UnsupportedOperationException 366 * If this attribute does not support removal of attribute 367 * values. 368 * @throws NullPointerException 369 * If {@code values} was {@code null}. 370 */ 371 <T> boolean retainAll(Collection<T> values, Collection<? super T> missingValues); 372 373 /** 374 * Returns the number of attribute values in this attribute. 375 * 376 * @return The number of attribute values in this attribute. 377 */ 378 @Override 379 int size(); 380 381 /** 382 * Returns an array containing all of the attribute values contained in this 383 * attribute. 384 * <p> 385 * If this attribute makes any guarantees as to what order its attribute 386 * values are returned by its iterator, this method must return the 387 * attribute values in the same order. 388 * <p> 389 * The returned array will be "safe" in that no references to it are 390 * maintained by this attribute. The caller is thus free to modify the 391 * returned array. 392 * 393 * @return An array containing all of the attribute values contained in this 394 * attribute. 395 */ 396 @Override 397 ByteString[] toArray(); 398 399 /** 400 * Returns an array containing all of the attribute values in this 401 * attribute; the runtime type of the returned array is that of the 402 * specified array. 403 * <p> 404 * If the set fits in the specified array, it is returned therein. 405 * Otherwise, a new array is allocated with the runtime type of the 406 * specified array and the size of this attribute. If this attribute fits in 407 * the specified array with room to spare (i.e., the array has more elements 408 * than this attribute), the elements in the array immediately following the 409 * end of the set is set to {@code null}. 410 * <p> 411 * If this attribute makes any guarantees as to what order its attribute 412 * values are returned by its iterator, this method must return the 413 * attribute values in the same order. 414 * 415 * @param <T> 416 * The type of elements contained in {@code array}. 417 * @param array 418 * An array into which the elements of this attribute should be 419 * put. 420 * @return An array containing all of the attribute values contained in this 421 * attribute. 422 * @throws ArrayStoreException 423 * If the runtime type of {@code array} is not a supertype of 424 * {@code ByteString}. 425 * @throws NullPointerException 426 * If {@code array} was {@code null}. 427 */ 428 @Override 429 <T> T[] toArray(T[] array); 430 431 /** 432 * Returns a string representation of this attribute. 433 * 434 * @return The string representation of this attribute. 435 */ 436 @Override 437 String toString(); 438}