| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package java.util; |
| |
| |
| /** |
| * {@code Collection} is the root of the collection hierarchy. It defines operations on |
| * data collections and the behavior that they will have in all implementations |
| * of {@code Collection}s. |
| * |
| * All direct or indirect implementations of {@code Collection} should implement at |
| * least two constructors. One with no parameters which creates an empty |
| * collection and one with a parameter of type {@code Collection}. This second |
| * constructor can be used to create a collection of different type as the |
| * initial collection but with the same elements. Implementations of {@code Collection} |
| * cannot be forced to implement these two constructors but at least all |
| * implementations under {@code java.util} do. |
| * |
| * Methods that change the content of a collection throw an |
| * {@code UnsupportedOperationException} if the underlying collection does not |
| * support that operation, though it's not mandatory to throw such an {@code Exception} |
| * in cases where the requested operation would not change the collection. In |
| * these cases it's up to the implementation whether it throws an |
| * {@code UnsupportedOperationException} or not. |
| * |
| * Methods marked with (optional) can throw an |
| * {@code UnsupportedOperationException} if the underlying collection doesn't |
| * support that method. |
| */ |
| public interface Collection<E> extends Iterable<E> { |
| |
| /** |
| * Attempts to add {@code object} to the contents of this |
| * {@code Collection} (optional). |
| * |
| * After this method finishes successfully it is guaranteed that the object |
| * is contained in the collection. |
| * |
| * If the collection was modified it returns {@code true}, {@code false} if |
| * no changes were made. |
| * |
| * An implementation of {@code Collection} may narrow the set of accepted |
| * objects, but it has to specify this in the documentation. If the object |
| * to be added does not meet this restriction, then an |
| * {@code IllegalArgumentException} is thrown. |
| * |
| * If a collection does not yet contain an object that is to be added and |
| * adding the object fails, this method <i>must</i> throw an appropriate |
| * unchecked Exception. Returning false is not permitted in this case |
| * because it would violate the postcondition that the element will be part |
| * of the collection after this method finishes. |
| * |
| * @param object |
| * the object to add. |
| * @return {@code true} if this {@code Collection} is |
| * modified, {@code false} otherwise. |
| * |
| * @throws UnsupportedOperationException |
| * if adding to this {@code Collection} is not supported. |
| * @throws ClassCastException |
| * if the class of the object is inappropriate for this |
| * collection. |
| * @throws IllegalArgumentException |
| * if the object cannot be added to this {@code Collection}. |
| * @throws NullPointerException |
| * if null elements cannot be added to the {@code Collection}. |
| */ |
| public boolean add(E object); |
| |
| /** |
| * Attempts to add all of the objects contained in {@code Collection} |
| * to the contents of this {@code Collection} (optional). If the passed {@code Collection} |
| * is changed during the process of adding elements to this {@code Collection}, the |
| * behavior is not defined. |
| * |
| * @param collection |
| * the {@code Collection} of objects. |
| * @return {@code true} if this {@code Collection} is modified, {@code false} |
| * otherwise. |
| * @throws UnsupportedOperationException |
| * if adding to this {@code Collection} is not supported. |
| * @throws ClassCastException |
| * if the class of an object is inappropriate for this |
| * {@code Collection}. |
| * @throws IllegalArgumentException |
| * if an object cannot be added to this {@code Collection}. |
| * @throws NullPointerException |
| * if {@code collection} is {@code null}, or if it |
| * contains {@code null} elements and this {@code Collection} does |
| * not support such elements. |
| */ |
| public boolean addAll(Collection<? extends E> collection); |
| |
| /** |
| * Removes all elements from this {@code Collection}, leaving it empty (optional). |
| * |
| * @throws UnsupportedOperationException |
| * if removing from this {@code Collection} is not supported. |
| * |
| * @see #isEmpty |
| * @see #size |
| */ |
| public void clear(); |
| |
| /** |
| * Tests whether this {@code Collection} contains the specified object. Returns |
| * {@code true} if and only if at least one element {@code elem} in this |
| * {@code Collection} meets following requirement: |
| * {@code (object==null ? elem==null : object.equals(elem))}. |
| * |
| * @param object |
| * the object to search for. |
| * @return {@code true} if object is an element of this {@code Collection}, |
| * {@code false} otherwise. |
| * @throws ClassCastException |
| * if the object to look for isn't of the correct |
| * type. |
| * @throws NullPointerException |
| * if the object to look for is {@code null} and this |
| * {@code Collection} doesn't support {@code null} elements. |
| */ |
| public boolean contains(Object object); |
| |
| /** |
| * Tests whether this {@code Collection} contains all objects contained in the |
| * specified {@code Collection}. If an element {@code elem} is contained several |
| * times in the specified {@code Collection}, the method returns {@code true} even |
| * if {@code elem} is contained only once in this {@code Collection}. |
| * |
| * @param collection |
| * the collection of objects. |
| * @return {@code true} if all objects in the specified {@code Collection} are |
| * elements of this {@code Collection}, {@code false} otherwise. |
| * @throws ClassCastException |
| * if one or more elements of {@code collection} isn't of the |
| * correct type. |
| * @throws NullPointerException |
| * if {@code collection} contains at least one {@code null} |
| * element and this {@code Collection} doesn't support {@code null} |
| * elements. |
| * @throws NullPointerException |
| * if {@code collection} is {@code null}. |
| */ |
| public boolean containsAll(Collection<?> collection); |
| |
| /** |
| * Compares the argument to the receiver, and returns true if they represent |
| * the <em>same</em> object using a class specific comparison. |
| * |
| * @param object |
| * the object to compare with this object. |
| * @return {@code true} if the object is the same as this object and |
| * {@code false} if it is different from this object. |
| * @see #hashCode |
| */ |
| public boolean equals(Object object); |
| |
| /** |
| * Returns an integer hash code for the receiver. Objects which are equal |
| * return the same value for this method. |
| * |
| * @return the receiver's hash. |
| * |
| * @see #equals |
| */ |
| public int hashCode(); |
| |
| /** |
| * Returns if this {@code Collection} contains no elements. |
| * |
| * @return {@code true} if this {@code Collection} has no elements, {@code false} |
| * otherwise. |
| * |
| * @see #size |
| */ |
| public boolean isEmpty(); |
| |
| /** |
| * Returns an instance of {@link Iterator} that may be used to access the |
| * objects contained by this {@code Collection}. The order in which the elements are |
| * returned by the iterator is not defined. Only if the instance of the |
| * {@code Collection} has a defined order the elements are returned in that order. |
| * |
| * @return an iterator for accessing the {@code Collection} contents. |
| */ |
| public Iterator<E> iterator(); |
| |
| /** |
| * Removes one instance of the specified object from this {@code Collection} if one |
| * is contained (optional). The element {@code elem} that is removed |
| * complies with {@code (object==null ? elem==null : object.equals(elem)}. |
| * |
| * @param object |
| * the object to remove. |
| * @return {@code true} if this {@code Collection} is modified, {@code false} |
| * otherwise. |
| * @throws UnsupportedOperationException |
| * if removing from this {@code Collection} is not supported. |
| * @throws ClassCastException |
| * if the object passed is not of the correct type. |
| * @throws NullPointerException |
| * if {@code object} is {@code null} and this {@code Collection} |
| * doesn't support {@code null} elements. |
| */ |
| public boolean remove(Object object); |
| |
| /** |
| * Removes all occurrences in this {@code Collection} of each object in the |
| * specified {@code Collection} (optional). After this method returns none of the |
| * elements in the passed {@code Collection} can be found in this {@code Collection} |
| * anymore. |
| * |
| * @param collection |
| * the collection of objects to remove. |
| * @return {@code true} if this {@code Collection} is modified, {@code false} |
| * otherwise. |
| * |
| * @throws UnsupportedOperationException |
| * if removing from this {@code Collection} is not supported. |
| * @throws ClassCastException |
| * if one or more elements of {@code collection} |
| * isn't of the correct type. |
| * @throws NullPointerException |
| * if {@code collection} contains at least one |
| * {@code null} element and this {@code Collection} doesn't support |
| * {@code null} elements. |
| * @throws NullPointerException |
| * if {@code collection} is {@code null}. |
| */ |
| public boolean removeAll(Collection<?> collection); |
| |
| /** |
| * Removes all objects from this {@code Collection} that are not also found in the |
| * {@code Collection} passed (optional). After this method returns this {@code Collection} |
| * will only contain elements that also can be found in the {@code Collection} |
| * passed to this method. |
| * |
| * @param collection |
| * the collection of objects to retain. |
| * @return {@code true} if this {@code Collection} is modified, {@code false} |
| * otherwise. |
| * @throws UnsupportedOperationException |
| * if removing from this {@code Collection} is not supported. |
| * @throws ClassCastException |
| * if one or more elements of {@code collection} |
| * isn't of the correct type. |
| * @throws NullPointerException |
| * if {@code collection} contains at least one |
| * {@code null} element and this {@code Collection} doesn't support |
| * {@code null} elements. |
| * @throws NullPointerException |
| * if {@code collection} is {@code null}. |
| */ |
| public boolean retainAll(Collection<?> collection); |
| |
| /** |
| * Returns a count of how many objects this {@code Collection} contains. |
| * |
| * @return how many objects this {@code Collection} contains, or Integer.MAX_VALUE |
| * if there are more than Integer.MAX_VALUE elements in this |
| * {@code Collection}. |
| */ |
| public int size(); |
| |
| /** |
| * Returns a new array containing all elements contained in this {@code Collection}. |
| * |
| * If the implementation has ordered elements it will return the element |
| * array in the same order as an iterator would return them. |
| * |
| * The array returned does not reflect any changes of the {@code Collection}. A new |
| * array is created even if the underlying data structure is already an |
| * array. |
| * |
| * @return an array of the elements from this {@code Collection}. |
| */ |
| public Object[] toArray(); |
| |
| /** |
| * Returns an array containing all elements contained in this {@code Collection}. If |
| * the specified array is large enough to hold the elements, the specified |
| * array is used, otherwise an array of the same type is created. If the |
| * specified array is used and is larger than this {@code Collection}, the array |
| * element following the {@code Collection} elements is set to null. |
| * |
| * If the implementation has ordered elements it will return the element |
| * array in the same order as an iterator would return them. |
| * |
| * {@code toArray(new Object[0])} behaves exactly the same way as |
| * {@code toArray()} does. |
| * |
| * @param array |
| * the array. |
| * @return an array of the elements from this {@code Collection}. |
| * |
| * @throws ArrayStoreException |
| * if the type of an element in this {@code Collection} cannot be |
| * stored in the type of the specified array. |
| */ |
| public <T> T[] toArray(T[] array); |
| } |
