1/* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18package java.util; 19 20 21/** 22 * A {@code List} is a collection which maintains an ordering for its elements. Every 23 * element in the {@code List} has an index. Each element can thus be accessed by its 24 * index, with the first index being zero. Normally, {@code List}s allow duplicate 25 * elements, as compared to Sets, where elements have to be unique. 26 */ 27public interface List<E> extends Collection<E> { 28 /** 29 * Inserts the specified object into this {@code List} at the specified location. 30 * The object is inserted before the current element at the specified 31 * location. If the location is equal to the size of this {@code List}, the object 32 * is added at the end. If the location is smaller than the size of this 33 * {@code List}, then all elements beyond the specified location are moved by one 34 * position towards the end of the {@code List}. 35 * 36 * @param location 37 * the index at which to insert. 38 * @param object 39 * the object to add. 40 * @throws UnsupportedOperationException 41 * if adding to this {@code List} is not supported. 42 * @throws ClassCastException 43 * if the class of the object is inappropriate for this 44 * {@code List}. 45 * @throws IllegalArgumentException 46 * if the object cannot be added to this {@code List}. 47 * @throws IndexOutOfBoundsException 48 * if {@code location < 0 || location > size()} 49 */ 50 public void add(int location, E object); 51 52 /** 53 * Adds the specified object at the end of this {@code List}. 54 * 55 * @param object 56 * the object to add. 57 * @return always true. 58 * @throws UnsupportedOperationException 59 * if adding to this {@code List} is not supported. 60 * @throws ClassCastException 61 * if the class of the object is inappropriate for this 62 * {@code List}. 63 * @throws IllegalArgumentException 64 * if the object cannot be added to this {@code List}. 65 */ 66 public boolean add(E object); 67 68 /** 69 * Inserts the objects in the specified collection at the specified location 70 * in this {@code List}. The objects are added in the order they are returned from 71 * the collection's iterator. 72 * 73 * @param location 74 * the index at which to insert. 75 * @param collection 76 * the collection of objects to be inserted. 77 * @return true if this {@code List} has been modified through the insertion, false 78 * otherwise (i.e. if the passed collection was empty). 79 * @throws UnsupportedOperationException 80 * if adding to this {@code List} is not supported. 81 * @throws ClassCastException 82 * if the class of an object is inappropriate for this 83 * {@code List}. 84 * @throws IllegalArgumentException 85 * if an object cannot be added to this {@code List}. 86 * @throws IndexOutOfBoundsException 87 * if {@code location < 0 || location > size()} 88 */ 89 public boolean addAll(int location, Collection<? extends E> collection); 90 91 /** 92 * Adds the objects in the specified collection to the end of this {@code List}. The 93 * objects are added in the order in which they are returned from the 94 * collection's iterator. 95 * 96 * @param collection 97 * the collection of objects. 98 * @return {@code true} if this {@code List} is modified, {@code false} otherwise 99 * (i.e. if the passed collection was empty). 100 * @throws UnsupportedOperationException 101 * if adding to this {@code List} is not supported. 102 * @throws ClassCastException 103 * if the class of an object is inappropriate for this 104 * {@code List}. 105 * @throws IllegalArgumentException 106 * if an object cannot be added to this {@code List}. 107 */ 108 public boolean addAll(Collection<? extends E> collection); 109 110 /** 111 * Removes all elements from this {@code List}, leaving it empty. 112 * 113 * @throws UnsupportedOperationException 114 * if removing from this {@code List} is not supported. 115 * @see #isEmpty 116 * @see #size 117 */ 118 public void clear(); 119 120 /** 121 * Tests whether this {@code List} contains the specified object. 122 * 123 * @param object 124 * the object to search for. 125 * @return {@code true} if object is an element of this {@code List}, {@code false} 126 * otherwise 127 */ 128 public boolean contains(Object object); 129 130 /** 131 * Tests whether this {@code List} contains all objects contained in the 132 * specified collection. 133 * 134 * @param collection 135 * the collection of objects 136 * @return {@code true} if all objects in the specified collection are 137 * elements of this {@code List}, {@code false} otherwise. 138 */ 139 public boolean containsAll(Collection<?> collection); 140 141 /** 142 * Compares the given object with the {@code List}, and returns true if they 143 * represent the <em>same</em> object using a class specific comparison. For 144 * {@code List}s, this means that they contain the same elements in exactly the same 145 * order. 146 * 147 * @param object 148 * the object to compare with this object. 149 * @return boolean {@code true} if the object is the same as this object, 150 * and {@code false} if it is different from this object. 151 * @see #hashCode 152 */ 153 public boolean equals(Object object); 154 155 /** 156 * Returns the element at the specified location in this {@code List}. 157 * 158 * @param location 159 * the index of the element to return. 160 * @return the element at the specified location. 161 * @throws IndexOutOfBoundsException 162 * if {@code location < 0 || location >= size()} 163 */ 164 public E get(int location); 165 166 /** 167 * Returns the hash code for this {@code List}. It is calculated by taking each 168 * element' hashcode and its position in the {@code List} into account. 169 * 170 * @return the hash code of the {@code List}. 171 */ 172 public int hashCode(); 173 174 /** 175 * Searches this {@code List} for the specified object and returns the index of the 176 * first occurrence. 177 * 178 * @param object 179 * the object to search for. 180 * @return the index of the first occurrence of the object or -1 if the 181 * object was not found. 182 */ 183 public int indexOf(Object object); 184 185 /** 186 * Returns whether this {@code List} contains no elements. 187 * 188 * @return {@code true} if this {@code List} has no elements, {@code false} 189 * otherwise. 190 * @see #size 191 */ 192 public boolean isEmpty(); 193 194 /** 195 * Returns an iterator on the elements of this {@code List}. The elements are 196 * iterated in the same order as they occur in the {@code List}. 197 * 198 * @return an iterator on the elements of this {@code List}. 199 * @see Iterator 200 */ 201 public Iterator<E> iterator(); 202 203 /** 204 * Searches this {@code List} for the specified object and returns the index of the 205 * last occurrence. 206 * 207 * @param object 208 * the object to search for. 209 * @return the index of the last occurrence of the object, or -1 if the 210 * object was not found. 211 */ 212 public int lastIndexOf(Object object); 213 214 /** 215 * Returns a {@code List} iterator on the elements of this {@code List}. The elements are 216 * iterated in the same order that they occur in the {@code List}. 217 * 218 * @return a {@code List} iterator on the elements of this {@code List} 219 * 220 * @see ListIterator 221 */ 222 public ListIterator<E> listIterator(); 223 224 /** 225 * Returns a list iterator on the elements of this {@code List}. The elements are 226 * iterated in the same order as they occur in the {@code List}. The iteration 227 * starts at the specified location. 228 * 229 * @param location 230 * the index at which to start the iteration. 231 * @return a list iterator on the elements of this {@code List}. 232 * @throws IndexOutOfBoundsException 233 * if {@code location < 0 || location > size()} 234 * @see ListIterator 235 */ 236 public ListIterator<E> listIterator(int location); 237 238 /** 239 * Removes the object at the specified location from this {@code List}. 240 * 241 * @param location 242 * the index of the object to remove. 243 * @return the removed object. 244 * @throws UnsupportedOperationException 245 * if removing from this {@code List} is not supported. 246 * @throws IndexOutOfBoundsException 247 * if {@code location < 0 || location >= size()} 248 */ 249 public E remove(int location); 250 251 /** 252 * Removes the first occurrence of the specified object from this {@code List}. 253 * 254 * @param object 255 * the object to remove. 256 * @return true if this {@code List} was modified by this operation, false 257 * otherwise. 258 * @throws UnsupportedOperationException 259 * if removing from this {@code List} is not supported. 260 */ 261 public boolean remove(Object object); 262 263 /** 264 * Removes all occurrences in this {@code List} of each object in the specified 265 * collection. 266 * 267 * @param collection 268 * the collection of objects to remove. 269 * @return {@code true} if this {@code List} is modified, {@code false} otherwise. 270 * @throws UnsupportedOperationException 271 * if removing from this {@code List} is not supported. 272 */ 273 public boolean removeAll(Collection<?> collection); 274 275 /** 276 * Removes all objects from this {@code List} that are not contained in the 277 * specified collection. 278 * 279 * @param collection 280 * the collection of objects to retain. 281 * @return {@code true} if this {@code List} is modified, {@code false} otherwise. 282 * @throws UnsupportedOperationException 283 * if removing from this {@code List} is not supported. 284 */ 285 public boolean retainAll(Collection<?> collection); 286 287 /** 288 * Replaces the element at the specified location in this {@code List} with the 289 * specified object. This operation does not change the size of the {@code List}. 290 * 291 * @param location 292 * the index at which to put the specified object. 293 * @param object 294 * the object to insert. 295 * @return the previous element at the index. 296 * @throws UnsupportedOperationException 297 * if replacing elements in this {@code List} is not supported. 298 * @throws ClassCastException 299 * if the class of an object is inappropriate for this 300 * {@code List}. 301 * @throws IllegalArgumentException 302 * if an object cannot be added to this {@code List}. 303 * @throws IndexOutOfBoundsException 304 * if {@code location < 0 || location >= size()} 305 */ 306 public E set(int location, E object); 307 308 /** 309 * Returns the number of elements in this {@code List}. 310 * 311 * @return the number of elements in this {@code List}. 312 */ 313 public int size(); 314 315 /** 316 * Returns a {@code List} of the specified portion of this {@code List} from the given start 317 * index to the end index minus one. The returned {@code List} is backed by this 318 * {@code List} so changes to it are reflected by the other. 319 * 320 * @param start 321 * the index at which to start the sublist. 322 * @param end 323 * the index one past the end of the sublist. 324 * @return a list of a portion of this {@code List}. 325 * @throws IndexOutOfBoundsException 326 * if {@code start < 0, start > end} or {@code end > 327 * size()} 328 */ 329 public List<E> subList(int start, int end); 330 331 /** 332 * Returns an array containing all elements contained in this {@code List}. 333 * 334 * @return an array of the elements from this {@code List}. 335 */ 336 public Object[] toArray(); 337 338 /** 339 * Returns an array containing all elements contained in this {@code List}. If the 340 * specified array is large enough to hold the elements, the specified array 341 * is used, otherwise an array of the same type is created. If the specified 342 * array is used and is larger than this {@code List}, the array element following 343 * the collection elements is set to null. 344 * 345 * @param array 346 * the array. 347 * @return an array of the elements from this {@code List}. 348 * @throws ArrayStoreException 349 * if the type of an element in this {@code List} cannot be stored 350 * in the type of the specified array. 351 */ 352 public <T> T[] toArray(T[] array); 353} 354