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 manage storage for elements they contain. By contrast, <i>view
112 * collections</i> themselves do not store elements, but instead they rely on a
113 * backing collection to store the actual elements. Operations that are not handled
114 * by the view collection itself are delegated to the backing collection. Examples of
115 * view collections include the wrapper collections returned by methods such as
116 * {@link Collections#checkedCollection Collections.checkedCollection},
117 * {@link Collections#synchronizedCollection Collections.synchronizedCollection}, and
118 * {@link Collections#unmodifiableCollection Collections.unmodifiableCollection}.
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 List.subList},
122 * {@link NavigableSet#subSet NavigableSet.subSet}, or
123 * {@link Map#entrySet Map.entrySet}.
124 * Any changes made to the backing collection are visible in the view collection.
125 * Correspondingly, any changes made to the view collection — if changes
126 * are permitted — are written through to the backing collection.
127 * Although they technically aren't collections, instances of
128 * {@link Iterator} and {@link ListIterator} can also allow modifications
129 * to be written through to the backing collection, and in some cases,
130 * modifications to the backing collection will be visible to the Iterator
131 * during iteration.
132 *
133 * <p><a id="unmodifiable"><b>Unmodifiable collections.</b></a>
134 * Certain methods of this interface are considered "destructive" and are called
135 * "mutator" methods in that they modify the group of objects contained within
136 * the collection on which they operate. They can be specified to throw
137 * {@code UnsupportedOperationException} if this collection implementation
138 * does not support the operation. Such methods should (but are not required
139 * to) throw an {@code UnsupportedOperationException} if the invocation would
140 * have no effect on the collection. For example, consider a collection that
141 * does not support the {@link #add add} operation. What will happen if the
142 * {@link #addAll addAll} method is invoked on this collection, with an empty
143 * collection as the argument? The addition of zero elements has no effect,
144 * so it is permissible for this collection simply to do nothing and not to throw
145 * an exception. However, it is recommended that such cases throw an exception
146 * unconditionally, as throwing only in certain cases can lead to
147 * programming errors.
148 *
149 * <p>An <i>unmodifiable collection</i> is a collection, all of whose
150 * mutator methods (as defined above) are specified to throw
151 * {@code UnsupportedOperationException}. Such a collection thus cannot be
152 * modified by calling any methods on it. For a collection to be properly
153 * unmodifiable, any view collections derived from it must also be unmodifiable.
154 * For example, if a List is unmodifiable, the List returned by
155 * {@link List#subList List.subList} is also unmodifiable.
156 *
157 * <p>An unmodifiable collection is not necessarily immutable. If the
158 * contained elements are mutable, the entire collection is clearly
159 * mutable, even though it might be unmodifiable. For example, consider
160 * two unmodifiable lists containing mutable elements. The result of calling
161 * {@code list1.equals(list2)} might differ from one call to the next if
162 * the elements had been mutated, even though both lists are unmodifiable.
163 * However, if an unmodifiable collection contains all immutable elements,
164 * it can be considered effectively immutable.
165 *
166 * <p><a id="unmodview"><b>Unmodifiable view collections.</b></a>
167 * An unmodifiable view is a collection that is unmodifiable and that is
168 * a view onto a backing collection. Mutator methods throw
169 * {@code UnsupportedOperationException}, as described above, while
170 * reading and querying methods are delegated to the backing collection.
171 * The effect is to provide read-only access to the backing collection.
172 * This is useful for a component to provide users with read access to
173 * an internal collection, while preventing them from modifying such
174 * collections unexpectedly. Examples of unmodifiable view collections
175 * are those returned by the
176 * {@link Collections#unmodifiableCollection Collections.unmodifiableCollection},
177 * {@link Collections#unmodifiableList Collections.unmodifiableList}, and
178 * related methods.
179 *
180 * <p>Note that changes to the backing collection might still be possible,
181 * and if they occur, they are visible through the unmodifiable view. Thus,
182 * an unmodifiable view collection is not necessarily immutable. However,
183 * if the backing collection of an unmodifiable view is effectively immutable,
184 * or if the only reference to the backing collection is through an
185 * unmodifiable view, the view can be considered effectively immutable.
186 *
187 * <p>This interface is a member of the
188 * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
189 * Java Collections Framework</a>.
190 *
191 * @implSpec
192 * The default method implementations (inherited or otherwise) do not apply any
193 * synchronization protocol. If a {@code Collection} implementation has a
194 * specific synchronization protocol, then it must override default
195 * implementations to apply that protocol.
196 *
197 * @param <E> the type of elements in this collection
198 *
199 * @author Josh Bloch
200 * @author Neal Gafter
201 * @see Set
202 * @see List
203 * @see Map
204 * @see SortedSet
205 * @see SortedMap
206 * @see HashSet
|