| Frames | No Frames |
1: /* Collection.java -- Interface that represents a collection of objects 2: Copyright (C) 1998, 2001, 2004, 2005 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.util; 40: 41: /** 42: * Interface that represents a collection of objects. This interface is the 43: * root of the collection hierarchy, and does not provide any guarantees about 44: * the order of its elements or whether or not duplicate elements are 45: * permitted. 46: * <p> 47: * All methods of this interface that are defined to modify the collection are 48: * defined as <dfn>optional</dfn>. An optional operation may throw an 49: * UnsupportedOperationException if the data backing this collection does not 50: * support such a modification. This may mean that the data structure is 51: * immutable, or that it is read-only but may change ("unmodifiable"), or 52: * that it is modifiable but of fixed size (such as an array), or any number 53: * of other combinations. 54: * <p> 55: * A class that wishes to implement this interface should consider subclassing 56: * AbstractCollection, which provides basic implementations of most of the 57: * methods of this interface. Classes that are prepared to make guarantees 58: * about ordering or about absence of duplicate elements should consider 59: * implementing List or Set respectively, both of which are subinterfaces of 60: * Collection. 61: * <p> 62: * A general-purpose implementation of the Collection interface should in most 63: * cases provide at least two constructors: One which takes no arguments and 64: * creates an empty collection, and one which takes a Collection as an argument 65: * and returns a collection containing the same elements (that is, creates a 66: * copy of the argument using its own implementation). 67: * 68: * @author Original author unknown 69: * @author Eric Blake (ebb9@email.byu.edu) 70: * @author Tom Tromey (tromey@redhat.com) 71: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 72: * @see List 73: * @see Set 74: * @see Map 75: * @see SortedSet 76: * @see SortedMap 77: * @see HashSet 78: * @see TreeSet 79: * @see ArrayList 80: * @see LinkedList 81: * @see Vector 82: * @see Collections 83: * @see Arrays 84: * @see AbstractCollection 85: * @since 1.2 86: * @status updated to 1.4 87: */ 88: public interface Collection<E> extends Iterable<E> 89: { 90: /** 91: * Add an element to this collection. 92: * 93: * @param o the object to add. 94: * @return true if the collection was modified as a result of this action. 95: * @throws UnsupportedOperationException if this collection does not 96: * support the add operation. 97: * @throws ClassCastException if o cannot be added to this collection due 98: * to its type. 99: * @throws NullPointerException if o is null and this collection doesn't 100: * support the addition of null values. 101: * @throws IllegalArgumentException if o cannot be added to this 102: * collection for some other reason. 103: */ 104: boolean add(E o); 105: 106: /** 107: * Add the contents of a given collection to this collection. 108: * 109: * @param c the collection to add. 110: * @return true if the collection was modified as a result of this action. 111: * @throws UnsupportedOperationException if this collection does not 112: * support the addAll operation. 113: * @throws ClassCastException if some element of c cannot be added to this 114: * collection due to its type. 115: * @throws NullPointerException if some element of c is null and this 116: * collection does not support the addition of null values. 117: * @throws NullPointerException if c itself is null. 118: * @throws IllegalArgumentException if some element of c cannot be added 119: * to this collection for some other reason. 120: */ 121: boolean addAll(Collection<? extends E> c); 122: 123: /** 124: * Clear the collection, such that a subsequent call to isEmpty() would 125: * return true. 126: * 127: * @throws UnsupportedOperationException if this collection does not 128: * support the clear operation. 129: */ 130: void clear(); 131: 132: /** 133: * Test whether this collection contains a given object as one of its 134: * elements. 135: * 136: * @param o the element to look for. 137: * @return true if this collection contains at least one element e such that 138: * <code>o == null ? e == null : o.equals(e)</code>. 139: * @throws ClassCastException if the type of o is not a valid type for this 140: * collection. 141: * @throws NullPointerException if o is null and this collection doesn't 142: * support null values. 143: */ 144: boolean contains(Object o); 145: 146: /** 147: * Test whether this collection contains every element in a given collection. 148: * 149: * @param c the collection to test for. 150: * @return true if for every element o in c, contains(o) would return true. 151: * @throws ClassCastException if the type of any element in c is not a valid 152: * type for this collection. 153: * @throws NullPointerException if some element of c is null and this 154: * collection does not support null values. 155: * @throws NullPointerException if c itself is null. 156: */ 157: boolean containsAll(Collection<?> c); 158: 159: /** 160: * Test whether this collection is equal to some object. The Collection 161: * interface does not explicitly require any behaviour from this method, and 162: * it may be left to the default implementation provided by Object. The Set 163: * and List interfaces do, however, require specific behaviour from this 164: * method. 165: * <p> 166: * If an implementation of Collection, which is not also an implementation of 167: * Set or List, should choose to implement this method, it should take care 168: * to obey the contract of the equals method of Object. In particular, care 169: * should be taken to return false when o is a Set or a List, in order to 170: * preserve the symmetry of the relation. 171: * 172: * @param o the object to compare to this collection. 173: * @return true if the o is equal to this collection. 174: */ 175: boolean equals(Object o); 176: 177: /** 178: * Obtain a hash code for this collection. The Collection interface does not 179: * explicitly require any behaviour from this method, and it may be left to 180: * the default implementation provided by Object. The Set and List interfaces 181: * do, however, require specific behaviour from this method. 182: * <p> 183: * If an implementation of Collection, which is not also an implementation of 184: * Set or List, should choose to implement this method, it should take care 185: * to obey the contract of the hashCode method of Object. Note that this 186: * method renders it impossible to correctly implement both Set and List, as 187: * the required implementations are mutually exclusive. 188: * 189: * @return a hash code for this collection. 190: */ 191: int hashCode(); 192: 193: /** 194: * Test whether this collection is empty, that is, if size() == 0. 195: * 196: * @return true if this collection contains no elements. 197: */ 198: boolean isEmpty(); 199: 200: /** 201: * Obtain an Iterator over this collection. 202: * 203: * @return an Iterator over the elements of this collection, in any order. 204: */ 205: Iterator<E> iterator(); 206: 207: /** 208: * Remove a single occurrence of an object from this collection. That is, 209: * remove an element e, if one exists, such that <code>o == null ? e == null 210: * : o.equals(e)</code>. 211: * 212: * @param o the object to remove. 213: * @return true if the collection changed as a result of this call, that is, 214: * if the collection contained at least one occurrence of o. 215: * @throws UnsupportedOperationException if this collection does not 216: * support the remove operation. 217: * @throws ClassCastException if the type of o is not a valid type 218: * for this collection. 219: * @throws NullPointerException if o is null and the collection doesn't 220: * support null values. 221: */ 222: boolean remove(Object o); 223: 224: /** 225: * Remove all elements of a given collection from this collection. That is, 226: * remove every element e such that c.contains(e). 227: * 228: * @param c The collection of objects to be removed. 229: * @return true if this collection was modified as a result of this call. 230: * @throws UnsupportedOperationException if this collection does not 231: * support the removeAll operation. 232: * @throws ClassCastException if the type of any element in c is not a valid 233: * type for this collection. 234: * @throws NullPointerException if some element of c is null and this 235: * collection does not support removing null values. 236: * @throws NullPointerException if c itself is null. 237: */ 238: boolean removeAll(Collection<?> c); 239: 240: /** 241: * Remove all elements of this collection that are not contained in a given 242: * collection. That is, remove every element e such that !c.contains(e). 243: * 244: * @param c The collection of objects to be retained. 245: * @return true if this collection was modified as a result of this call. 246: * @throws UnsupportedOperationException if this collection does not 247: * support the retainAll operation. 248: * @throws ClassCastException if the type of any element in c is not a valid 249: * type for this collection. 250: * @throws NullPointerException if some element of c is null and this 251: * collection does not support retaining null values. 252: * @throws NullPointerException if c itself is null. 253: */ 254: boolean retainAll(Collection<?> c); 255: 256: /** 257: * Get the number of elements in this collection. 258: * 259: * @return the number of elements in the collection. 260: */ 261: int size(); 262: 263: /** 264: * Copy the current contents of this collection into an array. 265: * 266: * @return an array of type Object[] and length equal to the size of this 267: * collection, containing the elements currently in this collection, in 268: * any order. 269: */ 270: Object[] toArray(); 271: 272: /** 273: * Copy the current contents of this collection into an array. If the array 274: * passed as an argument has length less than the size of this collection, an 275: * array of the same run-time type as a, and length equal to the size of this 276: * collection, is allocated using Reflection. Otherwise, a itself is used. 277: * The elements of this collection are copied into it, and if there is space 278: * in the array, the following element is set to null. The resultant array is 279: * returned. 280: * Note: The fact that the following element is set to null is only useful 281: * if it is known that this collection does not contain any null elements. 282: * 283: * @param a the array to copy this collection into. 284: * @return an array containing the elements currently in this collection, in 285: * any order. 286: * @throws ArrayStoreException if the type of any element of the 287: * collection is not a subtype of the element type of a. 288: */ 289: <T> T[] toArray(T[] a); 290: }