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