37 * implementations of this interface: it provides implementations of more
38 * specific subinterfaces like {@code Set} and {@code List}. This interface
39 * is typically used to pass collections around and manipulate them where
40 * maximum generality is desired.
41 *
42 * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
43 * duplicate elements) should implement this interface directly.
44 *
45 * <p>All general-purpose {@code Collection} implementation classes (which
46 * typically implement {@code Collection} indirectly through one of its
47 * subinterfaces) should provide two "standard" constructors: a void (no
48 * arguments) constructor, which creates an empty collection, and a
49 * constructor with a single argument of type {@code Collection}, which
50 * creates a new collection with the same elements as its argument. In
51 * effect, the latter constructor allows the user to copy any collection,
52 * producing an equivalent collection of the desired implementation type.
53 * There is no way to enforce this convention (as interfaces cannot contain
54 * constructors) but all of the general-purpose {@code Collection}
55 * implementations in the Java platform libraries comply.
56 *
57 * <p>The "destructive" methods contained in this interface, that is, the
58 * methods that modify the collection on which they operate, are specified to
59 * throw {@code UnsupportedOperationException} if this collection does not
60 * support the operation. If this is the case, these methods may, but are not
61 * required to, throw an {@code UnsupportedOperationException} if the
62 * invocation would have no effect on the collection. For example, invoking
63 * the {@link #addAll(Collection)} method on an unmodifiable collection may,
64 * but is not required to, throw the exception if the collection to be added
65 * is empty.
66 *
67 * <p><a id="optional-restrictions">
68 * Some collection implementations have restrictions on the elements that
69 * they may contain.</a> For example, some implementations prohibit null elements,
70 * and some have restrictions on the types of their elements. Attempting to
71 * add an ineligible element throws an unchecked exception, typically
72 * {@code NullPointerException} or {@code ClassCastException}. Attempting
73 * to query the presence of an ineligible element may throw an exception,
74 * or it may simply return false; some implementations will exhibit the former
75 * behavior and some will exhibit the latter. More generally, attempting an
76 * operation on an ineligible element whose completion would not result in
77 * the insertion of an ineligible element into the collection may throw an
78 * exception or it may succeed, at the option of the implementation.
79 * Such exceptions are marked as "optional" in the specification for this
80 * interface.
81 *
82 * <p>It is up to each collection to determine its own synchronization
83 * policy. In the absence of a stronger guarantee by the
84 * implementation, undefined behavior may result from the invocation
85 * of any method on a collection that is being mutated by another
86 * thread; this includes direct invocations, passing the collection to
87 * a method that might perform invocations, and using an existing
88 * iterator to examine the collection.
89 *
94 * contains at least one element {@code e} such that
95 * {@code (o==null ? e==null : o.equals(e))}." This specification should
96 * <i>not</i> be construed to imply that invoking {@code Collection.contains}
97 * with a non-null argument {@code o} will cause {@code o.equals(e)} to be
98 * invoked for any element {@code e}. Implementations are free to implement
99 * optimizations whereby the {@code equals} invocation is avoided, for
100 * example, by first comparing the hash codes of the two elements. (The
101 * {@link Object#hashCode()} specification guarantees that two objects with
102 * unequal hash codes cannot be equal.) More generally, implementations of
103 * the various Collections Framework interfaces are free to take advantage of
104 * the specified behavior of underlying {@link Object} methods wherever the
105 * implementor deems it appropriate.
106 *
107 * <p>Some collection operations which perform recursive traversal of the
108 * collection may fail with an exception for self-referential instances where
109 * the collection directly or indirectly contains itself. This includes the
110 * {@code clone()}, {@code equals()}, {@code hashCode()} and {@code toString()}
111 * methods. Implementations may optionally handle the self-referential scenario,
112 * however most current implementations do not do so.
113 *
114 * <p>This interface is a member of the
115 * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
116 * Java Collections Framework</a>.
117 *
118 * @implSpec
119 * The default method implementations (inherited or otherwise) do not apply any
120 * synchronization protocol. If a {@code Collection} implementation has a
121 * specific synchronization protocol, then it must override default
122 * implementations to apply that protocol.
123 *
124 * @param <E> the type of elements in this collection
125 *
126 * @author Josh Bloch
127 * @author Neal Gafter
128 * @see Set
129 * @see List
130 * @see Map
131 * @see SortedSet
132 * @see SortedMap
133 * @see HashSet
|
37 * implementations of this interface: it provides implementations of more
38 * specific subinterfaces like {@code Set} and {@code List}. This interface
39 * is typically used to pass collections around and manipulate them where
40 * maximum generality is desired.
41 *
42 * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
43 * duplicate elements) should implement this interface directly.
44 *
45 * <p>All general-purpose {@code Collection} implementation classes (which
46 * typically implement {@code Collection} indirectly through one of its
47 * subinterfaces) should provide two "standard" constructors: a void (no
48 * arguments) constructor, which creates an empty collection, and a
49 * constructor with a single argument of type {@code Collection}, which
50 * creates a new collection with the same elements as its argument. In
51 * effect, the latter constructor allows the user to copy any collection,
52 * producing an equivalent collection of the desired implementation type.
53 * There is no way to enforce this convention (as interfaces cannot contain
54 * constructors) but all of the general-purpose {@code Collection}
55 * implementations in the Java platform libraries comply.
56 *
57 * <p>Certain methods are specified to be
58 * <i>optional</i>. If a collection implementation doesn't implement a
59 * particular operation, it should define the corresponding method to throw
60 * {@code UnsupportedOperationException}. Such methods are marked "optional
61 * operation" in method specifications of the collections interfaces.
62 *
63 * <p><a id="optional-restrictions"></a>Some collection implementations
64 * have restrictions on the elements that they may contain.
65 * For example, some implementations prohibit null elements,
66 * and some have restrictions on the types of their elements. Attempting to
67 * add an ineligible element throws an unchecked exception, typically
68 * {@code NullPointerException} or {@code ClassCastException}. Attempting
69 * to query the presence of an ineligible element may throw an exception,
70 * or it may simply return false; some implementations will exhibit the former
71 * behavior and some will exhibit the latter. More generally, attempting an
72 * operation on an ineligible element whose completion would not result in
73 * the insertion of an ineligible element into the collection may throw an
74 * exception or it may succeed, at the option of the implementation.
75 * Such exceptions are marked as "optional" in the specification for this
76 * interface.
77 *
78 * <p>It is up to each collection to determine its own synchronization
79 * policy. In the absence of a stronger guarantee by the
80 * implementation, undefined behavior may result from the invocation
81 * of any method on a collection that is being mutated by another
82 * thread; this includes direct invocations, passing the collection to
83 * a method that might perform invocations, and using an existing
84 * iterator to examine the collection.
85 *
90 * contains at least one element {@code e} such that
91 * {@code (o==null ? e==null : o.equals(e))}." This specification should
92 * <i>not</i> be construed to imply that invoking {@code Collection.contains}
93 * with a non-null argument {@code o} will cause {@code o.equals(e)} to be
94 * invoked for any element {@code e}. Implementations are free to implement
95 * optimizations whereby the {@code equals} invocation is avoided, for
96 * example, by first comparing the hash codes of the two elements. (The
97 * {@link Object#hashCode()} specification guarantees that two objects with
98 * unequal hash codes cannot be equal.) More generally, implementations of
99 * the various Collections Framework interfaces are free to take advantage of
100 * the specified behavior of underlying {@link Object} methods wherever the
101 * implementor deems it appropriate.
102 *
103 * <p>Some collection operations which perform recursive traversal of the
104 * collection may fail with an exception for self-referential instances where
105 * the collection directly or indirectly contains itself. This includes the
106 * {@code clone()}, {@code equals()}, {@code hashCode()} and {@code toString()}
107 * methods. Implementations may optionally handle the self-referential scenario,
108 * however most current implementations do not do so.
109 *
110 * <p><a id="view"><b>View collections.</b></a>
111 * Most collections contain elements themselves. By contrast, <i>view collections</i>
112 * themselves do not contain elements, but instead rely on a backing collection to
113 * store the actual elements. Operations that are not handled by the view
114 * collection itself are delegated to the backing collection. Examples of
115 * view collections include the wrapper collections returned by methods such as
116 * {@link unmodifiableCollection},
117 * {@link checkedCollection}, and
118 * {@link synchronizedCollection}.
119 * Other examples of view collections include collections that provide a
120 * different representation of the same elements, for example, as
121 * provided by {@link List.subList}, {@link NavigableSet.subSet}, or
122 * {@link Map.entrySet}. Any changes made to the backing collection are
123 * visible in the view collection. Correspondingly, any changes made to
124 * the view collection are written through to the backing collection.
125 * Although they technically aren't collections, instances of
126 * {@link Iterator} and {@link ListIterator} can also allow modifications
127 * to be written through to the backing collection, and in some cases,
128 * modifications to the backing collection will be visible to the Iterator
129 * during iteration.
130 *
131 * <p><a id="unmodifiable"><b>Unmodifiable collections.</b></a>
132 * Certain methods of this interface are considered "destructive" and are called
133 * "mutator" methods in that they modify the group of objects contained within
134 * the collection on which they operate. They can be specified to throw
135 * {@code UnsupportedOperationException} if this collection implementation
136 * does not support the operation. Such methods should (but are not required
137 * to) throw an {@code UnsupportedOperationException} if the invocation would
138 * have no effect on the collection. For example, invoking the
139 * {@link #addAll addAll} method on a collection that does not support
140 * the {@link #add add} operation should throw the exception if
141 * the collection passed as an argument is empty. It is recommended
142 * that such methods always throw the exception unconditionally, as
143 * throwing only in certain cases can lead to programming errors.
144 *
145 * <p>An <i>unmodifiable collection</i> is a collection, all of whose
146 * mutator methods (as defined above) are specified to throw
147 * {@code UnsupportedOperationException}. Such a collection thus cannot be
148 * modified by calling any methods on it. For a collection to be properly
149 * unmodifiable, any view collections derived from it must also be unmodifiable.
150 * For example, if a List is unmodifiable, the List returned by
151 * {@link List.subList} should also be unmodifiable.
152 *
153 * <p>An unmodifiable collection is not necessarily immutable. If the
154 * contained elements are mutable, the entire collection is clearly
155 * mutable, even though it might be unmodifiable. For example, consider
156 * two unmodifiable lists containing mutable elements. The result of calling
157 * {@code list1.equals(list2)} might differ from one call to the next if
158 * the elements had been mutated, even though both lists are unmodifiable.
159 * However, if an unmodifiable collection contains all immutable elements,
160 * it can be considered effectively immutable.
161 *
162 * <p><a id="unmodview"><b>Unmodifiable view collections.</b></a>
163 * An unmodifiable view is a collection that is unmodifiable and that is
164 * a view onto a backing collection. Mutator methods throw
165 * {@code UnsupportedOperationException}, as described above, while
166 * reading and querying methods are delegated to the backing collection.
167 * The effect is to provide read-only access to the backing collection.
168 * This is useful for a component to provide users with read access to
169 * an internal collection, while preventing them from modifying such
170 * collections unexpectedly.
171 *
172 * <p>Note that changes to the backing collection might still be possible,
173 * and if they occur, they are visible through the unmodifiable view. As
174 * above, an unmodifiable view collection is not necessarily immutable.
175 * However, if the backing collection of an unmodifiable view is effectively
176 * immutable, or if the only reference to the backing collection is through
177 * an unmodifiable view, the view can be considered effectively immutable.
178 *
179 * <p>This interface is a member of the
180 * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
181 * Java Collections Framework</a>.
182 *
183 * @implSpec
184 * The default method implementations (inherited or otherwise) do not apply any
185 * synchronization protocol. If a {@code Collection} implementation has a
186 * specific synchronization protocol, then it must override default
187 * implementations to apply that protocol.
188 *
189 * @param <E> the type of elements in this collection
190 *
191 * @author Josh Bloch
192 * @author Neal Gafter
193 * @see Set
194 * @see List
195 * @see Map
196 * @see SortedSet
197 * @see SortedMap
198 * @see HashSet
|