1 |
/* Collection.java -- Interface that represents a collection of objects |
/* Collection.java -- Interface that represents a collection of objects |
2 |
Copyright (C) 1998 Free Software Foundation, Inc. |
Copyright (C) 1998, 2001 Free Software Foundation, Inc. |
3 |
|
|
4 |
This file is part of GNU Classpath. |
This file is part of GNU Classpath. |
5 |
|
|
25 |
executable file might be covered by the GNU General Public License. */ |
executable file might be covered by the GNU General Public License. */ |
26 |
|
|
27 |
|
|
|
// TO DO: |
|
|
// ~ Maybe some more @see clauses would be helpful. |
|
|
|
|
28 |
package java.util; |
package java.util; |
29 |
|
|
30 |
/** |
/** |
54 |
* and returns a collection containing the same elements (that is, creates a |
* and returns a collection containing the same elements (that is, creates a |
55 |
* copy of the argument using its own implementation). |
* copy of the argument using its own implementation). |
56 |
* |
* |
57 |
* @see java.util.List |
* @author Original author unknown |
58 |
* @see java.util.Set |
* @author Eric Blake <ebb9@email.byu.edu> |
59 |
* @see java.util.AbstractCollection |
* @see List |
60 |
|
* @see Set |
61 |
|
* @see Map |
62 |
|
* @see SortedSet |
63 |
|
* @see SortedMap |
64 |
|
* @see HashSet |
65 |
|
* @see TreeSet |
66 |
|
* @see ArrayList |
67 |
|
* @see LinkedList |
68 |
|
* @see Vector |
69 |
|
* @see Collections |
70 |
|
* @see Arrays |
71 |
|
* @see AbstractCollection |
72 |
|
* @since 1.2 |
73 |
|
* @status updated to 1.4 |
74 |
*/ |
*/ |
75 |
public interface Collection |
public interface Collection |
76 |
{ |
{ |
78 |
* Add an element to this collection. |
* Add an element to this collection. |
79 |
* |
* |
80 |
* @param o the object to add. |
* @param o the object to add. |
81 |
* @returns true if the collection was modified as a result of this action. |
* @return true if the collection was modified as a result of this action. |
82 |
* @exception UnsupportedOperationException if this collection does not |
* @throws UnsupportedOperationException if this collection does not |
83 |
* support the add operation. |
* support the add operation. |
84 |
* @exception ClassCastException if o cannot be added to this collection due |
* @throws ClassCastException if o cannot be added to this collection due |
85 |
* to its type. |
* to its type. |
86 |
* @exception IllegalArgumentException if o cannot be added to this |
* @throws IllegalArgumentException if o cannot be added to this |
87 |
* collection for some other reason. |
* collection for some other reason. |
88 |
*/ |
*/ |
89 |
boolean add(Object o); |
boolean add(Object o); |
92 |
* Add the contents of a given collection to this collection. |
* Add the contents of a given collection to this collection. |
93 |
* |
* |
94 |
* @param c the collection to add. |
* @param c the collection to add. |
95 |
* @returns true if the collection was modified as a result of this action. |
* @return true if the collection was modified as a result of this action. |
96 |
* @exception UnsupportedOperationException if this collection does not |
* @throws UnsupportedOperationException if this collection does not |
97 |
* support the addAll operation. |
* support the addAll operation. |
98 |
* @exception ClassCastException if some element of c cannot be added to this |
* @throws ClassCastException if some element of c cannot be added to this |
99 |
* collection due to its type. |
* collection due to its type. |
100 |
* @exception IllegalArgumentException if some element of c cannot be added |
* @throws IllegalArgumentException if some element of c cannot be added |
101 |
* to this collection for some other reason. |
* to this collection for some other reason. |
102 |
*/ |
*/ |
103 |
boolean addAll(Collection c); |
boolean addAll(Collection c); |
106 |
* Clear the collection, such that a subsequent call to isEmpty() would |
* Clear the collection, such that a subsequent call to isEmpty() would |
107 |
* return true. |
* return true. |
108 |
* |
* |
109 |
* @exception UnsupportedOperationException if this collection does not |
* @throws UnsupportedOperationException if this collection does not |
110 |
* support the clear operation. |
* support the clear operation. |
111 |
*/ |
*/ |
112 |
void clear(); |
void clear(); |
116 |
* elements. |
* elements. |
117 |
* |
* |
118 |
* @param o the element to look for. |
* @param o the element to look for. |
119 |
* @returns true if this collection contains at least one element e such that |
* @return true if this collection contains at least one element e such that |
120 |
* <code>o == null ? e == null : o.equals(e)</code>. |
* <code>o == null ? e == null : o.equals(e)</code>. |
121 |
*/ |
*/ |
122 |
boolean contains(Object o); |
boolean contains(Object o); |
125 |
* Test whether this collection contains every element in a given collection. |
* Test whether this collection contains every element in a given collection. |
126 |
* |
* |
127 |
* @param c the collection to test for. |
* @param c the collection to test for. |
128 |
* @returns true if for every element o in c, contains(o) would return true. |
* @return true if for every element o in c, contains(o) would return true. |
129 |
*/ |
*/ |
130 |
boolean containsAll(Collection c); |
boolean containsAll(Collection c); |
131 |
|
|
143 |
* preserve the symmetry of the relation. |
* preserve the symmetry of the relation. |
144 |
* |
* |
145 |
* @param o the object to compare to this collection. |
* @param o the object to compare to this collection. |
146 |
* @returns true if the o is equal to this collection. |
* @return true if the o is equal to this collection. |
147 |
*/ |
*/ |
148 |
boolean equals(Object o); |
boolean equals(Object o); |
149 |
|
|
159 |
* method renders it impossible to correctly implement both Set and List, as |
* method renders it impossible to correctly implement both Set and List, as |
160 |
* the required implementations are mutually exclusive. |
* the required implementations are mutually exclusive. |
161 |
* |
* |
162 |
* @returns a hash code for this collection. |
* @return a hash code for this collection. |
163 |
*/ |
*/ |
164 |
int hashCode(); |
int hashCode(); |
165 |
|
|
166 |
/** |
/** |
167 |
* Test whether this collection is empty, that is, if size() == 0. |
* Test whether this collection is empty, that is, if size() == 0. |
168 |
* |
* |
169 |
* @returns true if this collection contains no elements. |
* @return true if this collection contains no elements. |
170 |
*/ |
*/ |
171 |
boolean isEmpty(); |
boolean isEmpty(); |
172 |
|
|
173 |
/** |
/** |
174 |
* Obtain an Iterator over this collection. |
* Obtain an Iterator over this collection. |
175 |
* |
* |
176 |
* @returns an Iterator over the elements of this collection, in any order. |
* @return an Iterator over the elements of this collection, in any order. |
177 |
*/ |
*/ |
178 |
Iterator iterator(); |
Iterator iterator(); |
179 |
|
|
183 |
* : o.equals(e)</code>. |
* : o.equals(e)</code>. |
184 |
* |
* |
185 |
* @param o the object to remove. |
* @param o the object to remove. |
186 |
* @returns true if the collection changed as a result of this call, that is, |
* @return true if the collection changed as a result of this call, that is, |
187 |
* if the collection contained at least one occurrence of o. |
* if the collection contained at least one occurrence of o. |
188 |
* @exception UnsupportedOperationException if this collection does not |
* @throws UnsupportedOperationException if this collection does not |
189 |
* support the remove operation. |
* support the remove operation. |
190 |
*/ |
*/ |
191 |
boolean remove(Object o); |
boolean remove(Object o); |
194 |
* Remove all elements of a given collection from this collection. That is, |
* Remove all elements of a given collection from this collection. That is, |
195 |
* remove every element e such that c.contains(e). |
* remove every element e such that c.contains(e). |
196 |
* |
* |
197 |
* @returns true if this collection was modified as a result of this call. |
* @return true if this collection was modified as a result of this call. |
198 |
* @exception UnsupportedOperationException if this collection does not |
* @throws UnsupportedOperationException if this collection does not |
199 |
* support the removeAll operation. |
* support the removeAll operation. |
200 |
*/ |
*/ |
201 |
boolean removeAll(Collection c); |
boolean removeAll(Collection c); |
204 |
* Remove all elements of this collection that are not contained in a given |
* Remove all elements of this collection that are not contained in a given |
205 |
* collection. That is, remove every element e such that !c.contains(e). |
* collection. That is, remove every element e such that !c.contains(e). |
206 |
* |
* |
207 |
* @returns true if this collection was modified as a result of this call. |
* @return true if this collection was modified as a result of this call. |
208 |
* @exception UnsupportedOperationException if this collection does not |
* @throws UnsupportedOperationException if this collection does not |
209 |
* support the retainAll operation. |
* support the retainAll operation. |
210 |
*/ |
*/ |
211 |
boolean retainAll(Collection c); |
boolean retainAll(Collection c); |
213 |
/** |
/** |
214 |
* Get the number of elements in this collection. |
* Get the number of elements in this collection. |
215 |
* |
* |
216 |
* @returns the number of elements in the collection. |
* @return the number of elements in the collection. |
217 |
*/ |
*/ |
218 |
int size(); |
int size(); |
219 |
|
|
220 |
/** |
/** |
221 |
* Copy the current contents of this collection into an array. |
* Copy the current contents of this collection into an array. |
222 |
* |
* |
223 |
* @returns an array of type Object[] and length equal to the size of this |
* @return an array of type Object[] and length equal to the size of this |
224 |
* collection, containing the elements currently in this collection, in |
* collection, containing the elements currently in this collection, in |
225 |
* any order. |
* any order. |
226 |
*/ |
*/ |
238 |
* if it is known that this collection does not contain any null elements. |
* if it is known that this collection does not contain any null elements. |
239 |
* |
* |
240 |
* @param a the array to copy this collection into. |
* @param a the array to copy this collection into. |
241 |
* @returns an array containing the elements currently in this collection, in |
* @return an array containing the elements currently in this collection, in |
242 |
* any order. |
* any order. |
243 |
* @exception ArrayStoreException if the type of any element of the |
* @throws ArrayStoreException if the type of any element of the |
244 |
* collection is not a subtype of the element type of a. |
* collection is not a subtype of the element type of a. |
245 |
*/ |
*/ |
246 |
Object[] toArray(Object[] a); |
Object[] toArray(Object[] a); |