001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.util;
019:
020: /**
021: * Collection is the root of the collection hierarchy.
022: */
023: public interface Collection<E> extends Iterable<E> {
024:
025: /**
026: * Attempts to add <code>object</code> to the contents of this
027: * <code>Collection</code>.
028: *
029: * @param object
030: * the object to add
031: * @return <code>true</code> if this <code>Collection</code> is
032: * modified, <code>false</code> otherwise
033: *
034: * @exception UnsupportedOperationException
035: * when adding to this Collection is not supported
036: * @exception ClassCastException
037: * when the class of the object is inappropriate for this
038: * Collection
039: * @exception IllegalArgumentException
040: * when the object cannot be added to this Collection
041: */
042: public boolean add(E object);
043:
044: /**
045: * Attempts to add all of the objects contained in <code>collection</code>
046: * to the contents of this collection.
047: *
048: * @param collection
049: * the Collection of objects
050: * @return true if this Collection is modified, false otherwise
051: *
052: * @exception UnsupportedOperationException
053: * when adding to this Collection is not supported
054: * @exception ClassCastException
055: * when the class of an object is inappropriate for this
056: * Collection
057: * @exception IllegalArgumentException
058: * when an object cannot be added to this Collection
059: */
060: public boolean addAll(Collection<? extends E> collection);
061:
062: /**
063: * Removes all elements from this Collection, leaving it empty.
064: *
065: * @exception UnsupportedOperationException
066: * when removing from this Collection is not supported
067: *
068: * @see #isEmpty
069: * @see #size
070: */
071: public void clear();
072:
073: /**
074: * Searches this Collection for the specified object.
075: *
076: * @param object
077: * the object to search for
078: * @return true if object is an element of this Collection, false otherwise
079: */
080: public boolean contains(Object object);
081:
082: /**
083: * Searches this Collection for all objects in the specified Collection.
084: *
085: * @param collection
086: * the Collection of objects
087: * @return true if all objects in the specified Collection are elements of
088: * this Collection, false otherwise
089: */
090: public boolean containsAll(Collection<?> collection);
091:
092: /**
093: * Compares the argument to the receiver, and answers true if they represent
094: * the <em>same</em> object using a class specific comparison.
095: *
096: * @param object
097: * Object the object to compare with this object.
098: * @return boolean <code>true</code> if the object is the same as this
099: * object <code>false</code> if it is different from this object.
100: * @see #hashCode
101: */
102: public boolean equals(Object object);
103:
104: /**
105: * Answers an integer hash code for the receiver. Objects which are equal
106: * answer the same value for this method.
107: *
108: * @return the receiver's hash
109: *
110: * @see #equals
111: */
112: public int hashCode();
113:
114: /**
115: * Answers if this Collection has no elements, a size of zero.
116: *
117: * @return true if this Collection has no elements, false otherwise
118: *
119: * @see #size
120: */
121: public boolean isEmpty();
122:
123: /**
124: * Returns an instance of {@link Iterator} that may be used to access the
125: * objects contained by this collection.
126: *
127: * @return an iterator for accessing the collection contents
128: */
129: public Iterator<E> iterator();
130:
131: /**
132: * Removes the first occurrence of the specified object from this
133: * Collection.
134: *
135: * @param object
136: * the object to remove
137: * @return true if this Collection is modified, false otherwise
138: *
139: * @exception UnsupportedOperationException
140: * when removing from this Collection is not supported
141: */
142: public boolean remove(Object object);
143:
144: /**
145: * Removes all occurrences in this Collection of each object in the
146: * specified Collection.
147: *
148: * @param collection
149: * the Collection of objects to remove
150: * @return true if this Collection is modified, false otherwise
151: *
152: * @exception UnsupportedOperationException
153: * when removing from this Collection is not supported
154: */
155: public boolean removeAll(Collection<?> collection);
156:
157: /**
158: * Removes all objects from this Collection that are not also found in the
159: * contents of <code>collection</code>.
160: *
161: * @param collection
162: * the Collection of objects to retain
163: * @return true if this Collection is modified, false otherwise
164: *
165: * @exception UnsupportedOperationException
166: * when removing from this Collection is not supported
167: */
168: public boolean retainAll(Collection<?> collection);
169:
170: /**
171: * Returns a count of how many objects are contained by this collection.
172: *
173: * @return how many objects are contained by this collection
174: */
175: public int size();
176:
177: /**
178: * Answers a new array containing all elements contained in this Collection.
179: *
180: * @return an array of the elements from this Collection
181: */
182: public Object[] toArray();
183:
184: /**
185: * Answers an array containing all elements contained in this Collection. If
186: * the specified array is large enough to hold the elements, the specified
187: * array is used, otherwise an array of the same type is created. If the
188: * specified array is used and is larger than this Collection, the array
189: * element following the collection elements is set to null.
190: *
191: * @param array
192: * the array
193: * @return an array of the elements from this Collection
194: *
195: * @exception ArrayStoreException
196: * when the type of an element in this Collection cannot be
197: * stored in the type of the specified array
198: */
199: public <T> T[] toArray(T[] array);
200: }
|