1. /*
  2. * @(#)AbstractSequentialList.java 1.33 04/02/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.util;
  8. /**
  9. * This class provides a skeletal implementation of the <tt>List</tt>
  10. * interface to minimize the effort required to implement this interface
  11. * backed by a "sequential access" data store (such as a linked list). For
  12. * random access data (such as an array), <tt>AbstractList</tt> should be used
  13. * in preference to this class.<p>
  14. *
  15. * This class is the opposite of the <tt>AbstractList</tt> class in the sense
  16. * that it implements the "random access" methods (<tt>get(int index)</tt>,
  17. * <tt>set(int index, Object element)</tt>, <tt>set(int index, Object
  18. * element)</tt>, <tt>add(int index, Object element)</tt> and <tt>remove(int
  19. * index)</tt>) on top of the list's list iterator, instead of the other way
  20. * around.<p>
  21. *
  22. * To implement a list the programmer needs only to extend this class and
  23. * provide implementations for the <tt>listIterator</tt> and <tt>size</tt>
  24. * methods. For an unmodifiable list, the programmer need only implement the
  25. * list iterator's <tt>hasNext</tt>, <tt>next</tt>, <tt>hasPrevious</tt>,
  26. * <tt>previous</tt> and <tt>index</tt> methods.<p>
  27. *
  28. * For a modifiable list the programmer should additionally implement the list
  29. * iterator's <tt>set</tt> method. For a variable-size list the programmer
  30. * should additionally implement the list iterator's <tt>remove</tt> and
  31. * <tt>add</tt> methods.<p>
  32. *
  33. * The programmer should generally provide a void (no argument) and collection
  34. * constructor, as per the recommendation in the <tt>Collection</tt> interface
  35. * specification.<p>
  36. *
  37. * This class is a member of the
  38. * <a href="{@docRoot}/../guide/collections/index.html">
  39. * Java Collections Framework</a>.
  40. *
  41. * @author Josh Bloch
  42. * @author Neal Gafter
  43. * @version 1.33, 02/19/04
  44. * @see Collection
  45. * @see List
  46. * @see AbstractList
  47. * @see AbstractCollection
  48. * @since 1.2
  49. */
  50. public abstract class AbstractSequentialList<E> extends AbstractList<E> {
  51. /**
  52. * Sole constructor. (For invocation by subclass constructors, typically
  53. * implicit.)
  54. */
  55. protected AbstractSequentialList() {
  56. }
  57. /**
  58. * Returns the element at the specified position in this list. <p>
  59. *
  60. * This implementation first gets a list iterator pointing to the indexed
  61. * element (with <tt>listIterator(index)</tt>). Then, it gets the element
  62. * using <tt>ListIterator.next</tt> and returns it.
  63. * @param index index of element to return.
  64. *
  65. * @return the element at the specified position in this list.
  66. * @throws IndexOutOfBoundsException if the specified index is out of
  67. * range (<tt>index < 0 || index >= size()</tt>).
  68. */
  69. public E get(int index) {
  70. ListIterator<E> e = listIterator(index);
  71. try {
  72. return(e.next());
  73. } catch(NoSuchElementException exc) {
  74. throw(new IndexOutOfBoundsException("Index: "+index));
  75. }
  76. }
  77. /**
  78. * Replaces the element at the specified position in this list with the
  79. * specified element. <p>
  80. *
  81. * This implementation first gets a list iterator pointing to the
  82. * indexed element (with <tt>listIterator(index)</tt>). Then, it gets
  83. * the current element using <tt>ListIterator.next</tt> and replaces it
  84. * with <tt>ListIterator.set</tt>.<p>
  85. *
  86. * Note that this implementation will throw an
  87. * UnsupportedOperationException if list iterator does not implement
  88. * the set operation.
  89. *
  90. * @param index index of element to replace.
  91. * @param element element to be stored at the specified position.
  92. * @return the element previously at the specified position.
  93. * @throws UnsupportedOperationException set is not supported
  94. * by this list.
  95. * @throws NullPointerException this list does not permit null
  96. * elements and one of the elements of <code>c</code> is null.
  97. * @throws ClassCastException class of the specified element
  98. * prevents it from being added to this list.
  99. * @throws IllegalArgumentException some aspect of the specified
  100. * element prevents it from being added to this list.
  101. * @throws IndexOutOfBoundsException index out of range
  102. * <tt>(index < 0 || index >= size()</tt>).
  103. * @throws IllegalArgumentException fromIndex > toIndex.
  104. */
  105. public E set(int index, E element) {
  106. ListIterator<E> e = listIterator(index);
  107. try {
  108. E oldVal = e.next();
  109. e.set(element);
  110. return oldVal;
  111. } catch(NoSuchElementException exc) {
  112. throw(new IndexOutOfBoundsException("Index: "+index));
  113. }
  114. }
  115. /**
  116. * Inserts the specified element at the specified position in this list.
  117. * Shifts the element currently at that position (if any) and any
  118. * subsequent elements to the right (adds one to their indices).<p>
  119. *
  120. * This implementation first gets a list iterator pointing to the
  121. * indexed element (with <tt>listIterator(index)</tt>). Then, it inserts
  122. * the specified element with <tt>ListIterator.add</tt>.<p>
  123. *
  124. * Note that this implementation will throw an
  125. * <tt>UnsupportedOperationException</tt> if list iterator does not
  126. * implement the <tt>add</tt> operation.
  127. *
  128. * @param index index at which the specified element is to be inserted.
  129. * @param element element to be inserted.
  130. * @throws UnsupportedOperationException if the <tt>add</tt> operation is
  131. * not supported by this list.
  132. * @throws NullPointerException this list does not permit <tt>null</tt>
  133. * elements and one of the elements of <code>c</code> is
  134. * <tt>null</tt>.
  135. * @throws ClassCastException if the class of the specified element
  136. * prevents it from being added to this list.
  137. * @throws IllegalArgumentException if some aspect of the specified
  138. * element prevents it from being added to this list.
  139. * @throws IndexOutOfBoundsException if the specified index is out of
  140. * range (<tt>index < 0 || index > size()</tt>).
  141. */
  142. public void add(int index, E element) {
  143. ListIterator<E> e = listIterator(index);
  144. e.add(element);
  145. }
  146. /**
  147. * Removes the element at the specified position in this list. Shifts any
  148. * subsequent elements to the left (subtracts one from their indices).<p>
  149. *
  150. * This implementation first gets a list iterator pointing to the
  151. * indexed element (with <tt>listIterator(index)</tt>). Then, it removes
  152. * the element with <tt>ListIterator.remove</tt>.<p>
  153. *
  154. * Note that this implementation will throw an
  155. * <tt>UnsupportedOperationException</tt> if list iterator does not
  156. * implement the <tt>remove</tt> operation.
  157. *
  158. * @param index index of the element to be removed from the List.
  159. * @return the element that was removed from the list.
  160. * @throws UnsupportedOperationException if the <tt>remove</tt> operation
  161. * is not supported by this list.
  162. * @throws IndexOutOfBoundsException if the specified index is out of
  163. * range (index < 0 || index >= size()).
  164. */
  165. public E remove(int index) {
  166. ListIterator<E> e = listIterator(index);
  167. E outCast;
  168. try {
  169. outCast = e.next();
  170. } catch(NoSuchElementException exc) {
  171. throw(new IndexOutOfBoundsException("Index: "+index));
  172. }
  173. e.remove();
  174. return(outCast);
  175. }
  176. // Bulk Operations
  177. /**
  178. * Inserts all of the elements in the specified collection into this
  179. * list at the specified position. Shifts the element currently at that
  180. * position (if any) and any subsequent elements to the right (increases
  181. * their indices). The new elements will appear in the list in the order
  182. * that they are returned by the specified collection's iterator. The
  183. * behavior of this operation is unspecified if the specified collection
  184. * is modified while the operation is in progress. (Note that this will
  185. * occur if the specified collection is this list, and it's nonempty.)
  186. * Optional operation.<p>
  187. *
  188. * This implementation gets an iterator over the specified collection and
  189. * a list iterator over this list pointing to the indexed element (with
  190. * <tt>listIterator(index)</tt>). Then, it iterates over the specified
  191. * collection, inserting the elements obtained from the iterator into this
  192. * list, one at a time, using <tt>ListIterator.add</tt> followed by
  193. * <tt>ListIterator.next</tt> (to skip over the added element).<p>
  194. *
  195. * Note that this implementation will throw an
  196. * <tt>UnsupportedOperationException</tt> if the list iterator returned by
  197. * the <tt>listIterator</tt> method does not implement the <tt>add</tt>
  198. * operation.
  199. *
  200. * @return <tt>true</tt> if this list changed as a result of the call.
  201. * @param index index at which to insert first element from the specified
  202. * collection.
  203. * @param c elements to be inserted into this list.
  204. * @throws UnsupportedOperationException if the <tt>addAll</tt> operation
  205. * is not supported by this list.
  206. * @throws NullPointerException this list does not permit <tt>null</tt>
  207. * elements and one of the elements of the specified collection
  208. * is <tt>null</tt>.
  209. * @throws ClassCastException if the class of the specified element
  210. * prevents it from being added to this list.
  211. * @throws IllegalArgumentException if some aspect of the specified
  212. * element prevents it from being added to this list.
  213. * @throws IndexOutOfBoundsException if the specified index is out of
  214. * range (<tt>index < 0 || index > size()</tt>).
  215. * @throws NullPointerException if the specified collection is null.
  216. */
  217. public boolean addAll(int index, Collection<? extends E> c) {
  218. boolean modified = false;
  219. ListIterator<E> e1 = listIterator(index);
  220. Iterator<? extends E> e2 = c.iterator();
  221. while (e2.hasNext()) {
  222. e1.add(e2.next());
  223. modified = true;
  224. }
  225. return modified;
  226. }
  227. // Iterators
  228. /**
  229. * Returns an iterator over the elements in this list (in proper
  230. * sequence).<p>
  231. *
  232. * This implementation merely returns a list iterator over the list.
  233. *
  234. * @return an iterator over the elements in this list (in proper sequence).
  235. */
  236. public Iterator<E> iterator() {
  237. return listIterator();
  238. }
  239. /**
  240. * Returns a list iterator over the elements in this list (in proper
  241. * sequence).
  242. *
  243. * @param index index of first element to be returned from the list
  244. * iterator (by a call to the <code>next</code> method)
  245. * @return a list iterator over the elements in this list (in proper
  246. * sequence).
  247. */
  248. public abstract ListIterator<E> listIterator(int index);
  249. }