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}