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}