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