GNU Classpath (0.20) | |
Frames | No Frames |
1: /* Collection.java -- Interface that represents a collection of objects 2: Copyright (C) 1998, 2001, 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: * @see List 71: * @see Set 72: * @see Map 73: * @see SortedSet 74: * @see SortedMap 75: * @see HashSet 76: * @see TreeSet 77: * @see ArrayList 78: * @see LinkedList 79: * @see Vector 80: * @see Collections 81: * @see Arrays 82: * @see AbstractCollection 83: * @since 1.2 84: * @status updated to 1.4 85: */ 86: public interface Collection 87: { 88: /** 89: * Add an element to this collection. 90: * 91: * @param o the object to add. 92: * @return true if the collection was modified as a result of this action. 93: * @throws UnsupportedOperationException if this collection does not 94: * support the add operation. 95: * @throws ClassCastException if o cannot be added to this collection due 96: * to its type. 97: * @throws NullPointerException if o is null and this collection doesn't 98: * support the addition of null values. 99: * @throws IllegalArgumentException if o cannot be added to this 100: * collection for some other reason. 101: */ 102: boolean add(Object o); 103: 104: /** 105: * Add the contents of a given collection to this collection. 106: * 107: * @param c the collection to add. 108: * @return true if the collection was modified as a result of this action. 109: * @throws UnsupportedOperationException if this collection does not 110: * support the addAll operation. 111: * @throws ClassCastException if some element of c cannot be added to this 112: * collection due to its type. 113: * @throws NullPointerException if some element of c is null and this 114: * collection does not support the addition of null values. 115: * @throws NullPointerException if c itself is null. 116: * @throws IllegalArgumentException if some element of c cannot be added 117: * to this collection for some other reason. 118: */ 119: boolean addAll(Collection c); 120: 121: /** 122: * Clear the collection, such that a subsequent call to isEmpty() would 123: * return true. 124: * 125: * @throws UnsupportedOperationException if this collection does not 126: * support the clear operation. 127: */ 128: void clear(); 129: 130: /** 131: * Test whether this collection contains a given object as one of its 132: * elements. 133: * 134: * @param o the element to look for. 135: * @return true if this collection contains at least one element e such that 136: * <code>o == null ? e == null : o.equals(e)</code>. 137: * @throws ClassCastException if the type of o is not a valid type for this 138: * collection. 139: * @throws NullPointerException if o is null and this collection doesn't 140: * support null values. 141: */ 142: boolean contains(Object o); 143: 144: /** 145: * Test whether this collection contains every element in a given collection. 146: * 147: * @param c the collection to test for. 148: * @return true if for every element o in c, contains(o) would return true. 149: * @throws ClassCastException if the type of any element in c is not a valid 150: * type for this collection. 151: * @throws NullPointerException if some element of c is null and this 152: * collection does not support null values. 153: * @throws NullPointerException if c itself is null. 154: */ 155: boolean containsAll(Collection c); 156: 157: /** 158: * Test whether this collection is equal to some object. The Collection 159: * interface does not explicitly require any behaviour from this method, and 160: * it may be left to the default implementation provided by Object. The Set 161: * and List interfaces do, however, require specific behaviour from this 162: * method. 163: * <p> 164: * If an implementation of Collection, which is not also an implementation of 165: * Set or List, should choose to implement this method, it should take care 166: * to obey the contract of the equals method of Object. In particular, care 167: * should be taken to return false when o is a Set or a List, in order to 168: * preserve the symmetry of the relation. 169: * 170: * @param o the object to compare to this collection. 171: * @return true if the o is equal to this collection. 172: */ 173: boolean equals(Object o); 174: 175: /** 176: * Obtain a hash code for this collection. The Collection interface does not 177: * explicitly require any behaviour from this method, and it may be left to 178: * the default implementation provided by Object. The Set and List interfaces 179: * do, however, require specific behaviour from this method. 180: * <p> 181: * If an implementation of Collection, which is not also an implementation of 182: * Set or List, should choose to implement this method, it should take care 183: * to obey the contract of the hashCode method of Object. Note that this 184: * method renders it impossible to correctly implement both Set and List, as 185: * the required implementations are mutually exclusive. 186: * 187: * @return a hash code for this collection. 188: */ 189: int hashCode(); 190: 191: /** 192: * Test whether this collection is empty, that is, if size() == 0. 193: * 194: * @return true if this collection contains no elements. 195: */ 196: boolean isEmpty(); 197: 198: /** 199: * Obtain an Iterator over this collection. 200: * 201: * @return an Iterator over the elements of this collection, in any order. 202: */ 203: Iterator iterator(); 204: 205: /** 206: * Remove a single occurrence of an object from this collection. That is, 207: * remove an element e, if one exists, such that <code>o == null ? e == null 208: * : o.equals(e)</code>. 209: * 210: * @param o the object to remove. 211: * @return true if the collection changed as a result of this call, that is, 212: * if the collection contained at least one occurrence of o. 213: * @throws UnsupportedOperationException if this collection does not 214: * support the remove operation. 215: * @throws ClassCastException if the type of o is not a valid type 216: * for this collection. 217: * @throws NullPointerException if o is null and the collection doesn't 218: * support null values. 219: */ 220: boolean remove(Object o); 221: 222: /** 223: * Remove all elements of a given collection from this collection. That is, 224: * remove every element e such that c.contains(e). 225: * 226: * @param c The collection of objects to be removed. 227: * @return true if this collection was modified as a result of this call. 228: * @throws UnsupportedOperationException if this collection does not 229: * support the removeAll operation. 230: * @throws ClassCastException if the type of any element in c is not a valid 231: * type for this collection. 232: * @throws NullPointerException if some element of c is null and this 233: * collection does not support removing null values. 234: * @throws NullPointerException if c itself is null. 235: */ 236: boolean removeAll(Collection c); 237: 238: /** 239: * Remove all elements of this collection that are not contained in a given 240: * collection. That is, remove every element e such that !c.contains(e). 241: * 242: * @param c The collection of objects to be retained. 243: * @return true if this collection was modified as a result of this call. 244: * @throws UnsupportedOperationException if this collection does not 245: * support the retainAll operation. 246: * @throws ClassCastException if the type of any element in c is not a valid 247: * type for this collection. 248: * @throws NullPointerException if some element of c is null and this 249: * collection does not support retaining null values. 250: * @throws NullPointerException if c itself is null. 251: */ 252: boolean retainAll(Collection c); 253: 254: /** 255: * Get the number of elements in this collection. 256: * 257: * @return the number of elements in the collection. 258: */ 259: int size(); 260: 261: /** 262: * Copy the current contents of this collection into an array. 263: * 264: * @return an array of type Object[] and length equal to the size of this 265: * collection, containing the elements currently in this collection, in 266: * any order. 267: */ 268: Object[] toArray(); 269: 270: /** 271: * Copy the current contents of this collection into an array. If the array 272: * passed as an argument has length less than the size of this collection, an 273: * array of the same run-time type as a, and length equal to the size of this 274: * collection, is allocated using Reflection. Otherwise, a itself is used. 275: * The elements of this collection are copied into it, and if there is space 276: * in the array, the following element is set to null. The resultant array is 277: * returned. 278: * Note: The fact that the following element is set to null is only useful 279: * if it is known that this collection does not contain any null elements. 280: * 281: * @param a the array to copy this collection into. 282: * @return an array containing the elements currently in this collection, in 283: * any order. 284: * @throws ArrayStoreException if the type of any element of the 285: * collection is not a subtype of the element type of a. 286: */ 287: Object[] toArray(Object[] a); 288: }
GNU Classpath (0.20) |