[ViewVC] Diff of: jsr166/jsr166/src/main/java/util/Vector.java

Comparing jsr166/src/main/java/util/Vector.java (file contents):
Revision 1.7 by jsr166, Mon Dec 5 02:56:59 2005 UTC vs.
Revision 1.15 by jsr166, Sun Jun 25 19:58:14 2006 UTC

#	Line 6 \| Line 6
6		*/
7
8		package java.util;
9	–	import java.util.*; // for javadoc (till 6280605 is fixed)
9
10		/**
11	<	* The <code>Vector</code> class implements a growable array of
11	>	* The {@code Vector} class implements a growable array of
12		* objects. Like an array, it contains components that can be
13		* accessed using an integer index. However, the size of a
14	<	* <code>Vector</code> can grow or shrink as needed to accommodate
15	<	* adding and removing items after the <code>Vector</code> has been created.<p>
14	>	* {@code Vector} can grow or shrink as needed to accommodate
15	>	* adding and removing items after the {@code Vector} has been created.
16		*
17	<	* Each vector tries to optimize storage management by maintaining a
18	<	* <code>capacity</code> and a <code>capacityIncrement</code>. The
19	<	* <code>capacity</code> is always at least as large as the vector
17	>	* <p>Each vector tries to optimize storage management by maintaining a
18	>	* {@code capacity} and a {@code capacityIncrement}. The
19	>	* {@code capacity} is always at least as large as the vector
20		* size; it is usually larger because as components are added to the
21		* vector, the vector's storage increases in chunks the size of
22	<	* <code>capacityIncrement</code>. An application can increase the
22	>	* {@code capacityIncrement}. An application can increase the
23		* capacity of a vector before inserting a large number of
24	<	* components; this reduces the amount of incremental reallocation. <p>
24	>	* components; this reduces the amount of incremental reallocation.
25		*
26	<	* As of the Java 2 platform v1.2, this class has been retrofitted to
28	<	* implement List, so that it becomes a part of Java's collection framework.
29	<	* Unlike the new collection implementations, Vector is synchronized.<p>
30	<	*
31	<	* The Iterators returned by Vector's iterator and listIterator
26	>	* <p>The Iterators returned by Vector's iterator and listIterator
27		* methods are <em>fail-fast</em>: if the Vector is structurally modified
28		* at any time after the Iterator is created, in any way except through the
29		* Iterator's own remove or add methods, the Iterator will throw a
#	Line 41 \| Line 36 \| *import java.util.; // for javadoc (till**
36		* <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
37		* as it is, generally speaking, impossible to make any hard guarantees in the
38		* presence of unsynchronized concurrent modification. Fail-fast iterators
39	<	* throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
39	>	* throw {@code ConcurrentModificationException} on a best-effort basis.
40		* Therefore, it would be wrong to write a program that depended on this
41		* exception for its correctness: <i>the fail-fast behavior of iterators
42	<	* should be used only to detect bugs.</i><p>
42	>	* should be used only to detect bugs.</i>
43		*
44	<	* This class is a member of the
45	<	* <a href="{@docRoot}/../guide/collections/index.html">
46	<	* Java Collections Framework</a>.
44	>	* <p>As of the Java 2 platform v1.2, this class was retrofitted to
45	>	* implement the {@link List} interface, making it a member of the
46	>	* <a href="{@docRoot}/../technotes/guides/collections/index.html"> Java
47	>	* Collections Framework</a>. Unlike the new collection
48	>	* implementations, {@code Vector} is synchronized.
49		*
50		* @author Lee Boynton
51		* @author Jonathan Payne
#	Line 66 \| Line 63 \| public class Vector<E>
63		/**
64		* The array buffer into which the components of the vector are
65		* stored. The capacity of the vector is the length of this array buffer,
66	<	* and is at least large enough to contain all the vector's elements.<p>
66	>	* and is at least large enough to contain all the vector's elements.
67		*
68	<	* Any array elements following the last element in the Vector are null.
68	>	* <p>Any array elements following the last element in the Vector are null.
69		*
70		* @serial
71		*/
72		protected Object[] elementData;
73
74		/**
75	<	* The number of valid components in this <tt>Vector</tt> object.
76	<	* Components <tt>elementData[0]</tt> through
77	<	* <tt>elementData[elementCount-1]</tt> are the actual items.
75	>	* The number of valid components in this {@code Vector} object.
76	>	* Components {@code elementData[0]} through
77	>	* {@code elementData[elementCount-1]} are the actual items.
78		*
79		* @serial
80		*/
#	Line 103 \| Line 100 \| public class Vector<E>
100		* @param initialCapacity the initial capacity of the vector
101		* @param capacityIncrement the amount by which the capacity is
102		* increased when the vector overflows
103	<	* @exception IllegalArgumentException if the specified initial capacity
104	<	* is negative
103	>	* @throws IllegalArgumentException if the specified initial capacity
104	>	* is negative
105		*/
106		public Vector(int initialCapacity, int capacityIncrement) {
107		super();
#	Line 120 \| Line 117 \| public class Vector<E>
117		* with its capacity increment equal to zero.
118		*
119		* @param initialCapacity the initial capacity of the vector
120	<	* @exception IllegalArgumentException if the specified initial capacity
121	<	* is negative
120	>	* @throws IllegalArgumentException if the specified initial capacity
121	>	* is negative
122		*/
123		public Vector(int initialCapacity) {
124		this(initialCapacity, 0);
#	Line 129 \| Line 126 \| public class Vector<E>
126
127		/**
128		* Constructs an empty vector so that its internal data array
129	<	* has size <tt>10</tt> and its standard capacity increment is
129	>	* has size {@code 10} and its standard capacity increment is
130		* zero.
131		*/
132		public Vector() {
#	Line 156 \| Line 153 \| public class Vector<E>
153
154		/**
155		* Copies the components of this vector into the specified array.
156	<	* The item at index <tt>k</tt> in this vector is copied into
157	<	* component <tt>k</tt> of <tt>anArray</tt>.
156	>	* The item at index {@code k} in this vector is copied into
157	>	* component {@code k} of {@code anArray}.
158		*
159		* @param anArray the array into which the components get copied
160		* @throws NullPointerException if the given array is null
#	Line 175 \| Line 172 \| public class Vector<E>
172		* Trims the capacity of this vector to be the vector's current
173		* size. If the capacity of this vector is larger than its current
174		* size, then the capacity is changed to equal the size by replacing
175	<	* its internal data array, kept in the field <tt>elementData</tt>,
175	>	* its internal data array, kept in the field {@code elementData},
176		* with a smaller one. An application can use this operation to
177		* minimize the storage of a vector.
178		*/
#	Line 193 \| Line 190 \| public class Vector<E>
190		* the minimum capacity argument.
191		*
192		* <p>If the current capacity of this vector is less than
193	<	* <tt>minCapacity</tt>, then its capacity is increased by replacing its
194	<	* internal data array, kept in the field <tt>elementData</tt>, with a
193	>	* {@code minCapacity}, then its capacity is increased by replacing its
194	>	* internal data array, kept in the field {@code elementData}, with a
195		* larger one. The size of the new data array will be the old size plus
196	<	* <tt>capacityIncrement</tt>, unless the value of
197	<	* <tt>capacityIncrement</tt> is less than or equal to zero, in which case
196	>	* {@code capacityIncrement}, unless the value of
197	>	* {@code capacityIncrement} is less than or equal to zero, in which case
198		* the new capacity will be twice the old capacity; but if this new size
199	<	* is still smaller than <tt>minCapacity</tt>, then the new capacity will
200	<	* be <tt>minCapacity</tt>.
199	>	* is still smaller than {@code minCapacity}, then the new capacity will
200	>	* be {@code minCapacity}.
201		*
202		* @param minCapacity the desired minimum capacity
203		*/
#	Line 215 \| Line 212 \| public class Vector<E>
212		* method for ensuring capacity without incurring the cost of an
213		* extra synchronization.
214		*
215	<	* @see java.util.Vector#ensureCapacity(int)
215	>	* @see #ensureCapacity(int)
216		*/
217		private void ensureCapacityHelper(int minCapacity) {
218		int oldCapacity = elementData.length;
#	Line 232 \| Line 229 \| public class Vector<E>
229
230		/**
231		* Sets the size of this vector. If the new size is greater than the
232	<	* current size, new <code>null</code> items are added to the end of
232	>	* current size, new {@code null} items are added to the end of
233		* the vector. If the new size is less than the current size, all
234	<	* components at index <code>newSize</code> and greater are discarded.
234	>	* components at index {@code newSize} and greater are discarded.
235		*
236		* @param newSize the new size of this vector
237		* @throws ArrayIndexOutOfBoundsException if new size is negative
#	Line 255 \| Line 252 \| public class Vector<E>
252		* Returns the current capacity of this vector.
253		*
254		* @return the current capacity (the length of its internal
255	<	* data array, kept in the field <tt>elementData</tt>
255	>	* data array, kept in the field {@code elementData}
256		* of this vector)
257		*/
258		public synchronized int capacity() {
#	Line 274 \| Line 271 \| public class Vector<E>
271		/**
272		* Tests if this vector has no components.
273		*
274	<	* @return <code>true</code> if and only if this vector has
274	>	* @return {@code true} if and only if this vector has
275		* no components, that is, its size is zero;
276	<	* <code>false</code> otherwise.
276	>	* {@code false} otherwise.
277		*/
278		public synchronized boolean isEmpty() {
279		return elementCount == 0;
#	Line 284 \| Line 281 \| public class Vector<E>
281
282		/**
283		* Returns an enumeration of the components of this vector. The
284	<	* returned <tt>Enumeration</tt> object will generate all items in
285	<	* this vector. The first item generated is the item at index <tt>0</tt>,
286	<	* then the item at index <tt>1</tt>, and so on.
284	>	* returned {@code Enumeration} object will generate all items in
285	>	* this vector. The first item generated is the item at index {@code 0},
286	>	* then the item at index {@code 1}, and so on.
287		*
288		* @return an enumeration of the components of this vector
292	–	* @see Enumeration
289		* @see Iterator
290		*/
291		public Enumeration<E> elements() {
#	Line 312 \| Line 308 \| public class Vector<E>
308		}
309
310		/**
311	<	* Returns <tt>true</tt> if this vector contains the specified element.
312	<	* More formally, returns <tt>true</tt> if and only if this vector
313	<	* contains at least one element <tt>e</tt> such that
311	>	* Returns {@code true} if this vector contains the specified element.
312	>	* More formally, returns {@code true} if and only if this vector
313	>	* contains at least one element {@code e} such that
314		* <tt>(o==null ? e==null : o.equals(e))</tt>.
315		*
316		* @param o element whose presence in this vector is to be tested
317	<	* @return <tt>true</tt> if this vector contains the specified element
317	>	* @return {@code true} if this vector contains the specified element
318		*/
319		public boolean contains(Object o) {
320		return indexOf(o, 0) >= 0;
#	Line 327 \| Line 323 \| public class Vector<E>
323		/**
324		* Returns the index of the first occurrence of the specified element
325		* in this vector, or -1 if this vector does not contain the element.
326	<	* More formally, returns the lowest index <tt>i</tt> such that
326	>	* More formally, returns the lowest index {@code i} such that
327		* <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
328		* or -1 if there is no such index.
329		*
#	Line 341 \| Line 337 \| public class Vector<E>
337
338		/**
339		* Returns the index of the first occurrence of the specified element in
340	<	* this vector, searching forwards from <tt>index</tt>, or returns -1 if
340	>	* this vector, searching forwards from {@code index}, or returns -1 if
341		* the element is not found.
342	<	* More formally, returns the lowest index <tt>i</tt> such that
342	>	* More formally, returns the lowest index {@code i} such that
343		* <tt>(i >= index && (o==null ? get(i)==null : o.equals(get(i))))</tt>,
344		* or -1 if there is no such index.
345		*
346		* @param o element to search for
347		* @param index index to start searching from
348		* @return the index of the first occurrence of the element in
349	<	* this vector at position <tt>index</tt> or later in the vector;
350	<	* <tt>-1</tt> if the element is not found.
349	>	* this vector at position {@code index} or later in the vector;
350	>	* {@code -1} if the element is not found.
351		* @throws IndexOutOfBoundsException if the specified index is negative
352		* @see Object#equals(Object)
353		*/
#	Line 371 \| Line 367 \| public class Vector<E>
367		/**
368		* Returns the index of the last occurrence of the specified element
369		* in this vector, or -1 if this vector does not contain the element.
370	<	* More formally, returns the highest index <tt>i</tt> such that
370	>	* More formally, returns the highest index {@code i} such that
371		* <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
372		* or -1 if there is no such index.
373		*
#	Line 385 \| Line 381 \| public class Vector<E>
381
382		/**
383		* Returns the index of the last occurrence of the specified element in
384	<	* this vector, searching backwards from <tt>index</tt>, or returns -1 if
384	>	* this vector, searching backwards from {@code index}, or returns -1 if
385		* the element is not found.
386	<	* More formally, returns the highest index <tt>i</tt> such that
386	>	* More formally, returns the highest index {@code i} such that
387		* <tt>(i <= index && (o==null ? get(i)==null : o.equals(get(i))))</tt>,
388		* or -1 if there is no such index.
389		*
390		* @param o element to search for
391		* @param index index to start searching backwards from
392		* @return the index of the last occurrence of the element at position
393	<	* less than or equal to <tt>index</tt> in this vector;
393	>	* less than or equal to {@code index} in this vector;
394		* -1 if the element is not found.
395		* @throws IndexOutOfBoundsException if the specified index is greater
396		* than or equal to the current size of this vector
#	Line 416 \| Line 412 \| public class Vector<E>
412		}
413
414		/**
415	<	* Returns the component at the specified index.<p>
415	>	* Returns the component at the specified index.
416		*
417	<	* This method is identical in functionality to the get method
418	<	* (which is part of the List interface).
417	>	* <p>This method is identical in functionality to the {@link #get(int)}
418	>	* method (which is part of the {@link List} interface).
419		*
420		* @param index an index into this vector
421		* @return the component at the specified index
422	<	* @exception ArrayIndexOutOfBoundsException if the <tt>index</tt>
423	<	* is negative or not less than the current size of this
428	<	* <tt>Vector</tt> object.
429	<	* @see #get(int)
430	<	* @see List
422	>	* @throws ArrayIndexOutOfBoundsException if the index is out of range
423	>	* ({@code index < 0 \|\| index >= size()})
424		*/
425		public synchronized E elementAt(int index) {
426		if (index >= elementCount) {
#	Line 438 \| Line 431 \| public class Vector<E>
431		}
432
433		/**
434	<	* Returns the first component (the item at index <tt>0</tt>) of
434	>	* Returns the first component (the item at index {@code 0}) of
435		* this vector.
436		*
437		* @return the first component of this vector
438	<	* @exception NoSuchElementException if this vector has no components
438	>	* @throws NoSuchElementException if this vector has no components
439		*/
440		public synchronized E firstElement() {
441		if (elementCount == 0) {
#	Line 456 \| Line 449 \| public class Vector<E>
449		*
450		* @return the last component of the vector, i.e., the component at index
451		* <code>size() - 1</code>.
452	<	* @exception NoSuchElementException if this vector is empty
452	>	* @throws NoSuchElementException if this vector is empty
453		*/
454		public synchronized E lastElement() {
455		if (elementCount == 0) {
#	Line 466 \| Line 459 \| public class Vector<E>
459		}
460
461		/**
462	<	* Sets the component at the specified <code>index</code> of this
462	>	* Sets the component at the specified {@code index} of this
463		* vector to be the specified object. The previous component at that
464		* position is discarded.<p>
465		*
466	<	* The index must be a value greater than or equal to <code>0</code>
466	>	* The index must be a value greater than or equal to {@code 0}
467		* and less than the current size of the vector. <p>
468		*
469		* This method is identical in functionality to the set method
#	Line 481 \| Line 474 \| public class Vector<E>
474		*
475		* @param obj what the component is to be set to
476		* @param index the specified index
477	<	* @exception ArrayIndexOutOfBoundsException if the index was invalid
477	>	* @throws ArrayIndexOutOfBoundsException if the index was invalid
478		* @see #size()
479		* @see List
480		* @see #set(int, java.lang.Object)
#	Line 497 \| Line 490 \| public class Vector<E>
490		/**
491		* Deletes the component at the specified index. Each component in
492		* this vector with an index greater or equal to the specified
493	<	* <code>index</code> is shifted downward to have an index one
493	>	* {@code index} is shifted downward to have an index one
494		* smaller than the value it had previously. The size of this vector
495	<	* is decreased by <tt>1</tt>.<p>
495	>	* is decreased by {@code 1}.
496		*
497	<	* The index must be a value greater than or equal to <code>0</code>
498	<	* and less than the current size of the vector. <p>
497	>	* <p>The index must be a value greater than or equal to {@code 0}
498	>	* and less than the current size of the vector.
499		*
500	<	* This method is identical in functionality to the remove method
500	>	* <p>This method is identical in functionality to the remove method
501		* (which is part of the List interface). Note that the remove method
502		* returns the old value that was stored at the specified position.
503		*
#	Line 533 \| Line 526 \| public class Vector<E>
526
527		/**
528		* Inserts the specified object as a component in this vector at the
529	<	* specified <code>index</code>. Each component in this vector with
530	<	* an index greater or equal to the specified <code>index</code> is
529	>	* specified {@code index}. Each component in this vector with
530	>	* an index greater or equal to the specified {@code index} is
531		* shifted upward to have an index one greater than the value it had
532	<	* previously. <p>
532	>	* previously.
533		*
534	<	* The index must be a value greater than or equal to <code>0</code>
534	>	* <p>The index must be a value greater than or equal to {@code 0}
535		* and less than or equal to the current size of the vector. (If the
536		* index is equal to the current size of the vector, the new element
537	<	* is appended to the Vector.)<p>
537	>	* is appended to the Vector.)
538		*
539	<	* This method is identical in functionality to the add(Object, int) method
539	>	* <p>This method is identical in functionality to the add(Object, int) method
540		* (which is part of the List interface). Note that the add method reverses
541		* the order of the parameters, to more closely match array usage.
542		*
#	Line 595 \| Line 588 \| public class Vector<E>
588		* method (which is part of the List interface).
589		*
590		* @param obj the component to be removed
591	<	* @return <code>true</code> if the argument was a component of this
592	<	* vector; <code>false</code> otherwise.
591	>	* @return {@code true} if the argument was a component of this
592	>	* vector; {@code false} otherwise.
593		* @see List#remove(Object)
594		* @see List
595		*/
#	Line 631 \| Line 624 \| public class Vector<E>
624		/**
625		* Returns a clone of this vector. The copy will contain a
626		* reference to a clone of the internal data array, not a reference
627	<	* to the original internal data array of this <tt>Vector</tt> object.
627	>	* to the original internal data array of this {@code Vector} object.
628		*
629		* @return a clone of this vector
630		*/
#	Line 734 \| Line 727 \| public class Vector<E>
727		* Appends the specified element to the end of this Vector.
728		*
729		* @param e element to be appended to this Vector
730	<	* @return <tt>true</tt> (as specified by {@link Collection#add})
730	>	* @return {@code true} (as specified by {@link Collection#add})
731		* @since 1.2
732		*/
733		public synchronized boolean add(E e) {
#	Line 748 \| Line 741 \| public class Vector<E>
741		* Removes the first occurrence of the specified element in this Vector
742		* If the Vector does not contain the element, it is unchanged. More
743		* formally, removes the element with the lowest index i such that
744	<	* <code>(o==null ? get(i)==null : o.equals(get(i)))</code> (if such
744	>	* {@code (o==null ? get(i)==null : o.equals(get(i)))} (if such
745		* an element exists).
746		*
747		* @param o element to be removed from this Vector, if present
#	Line 835 \| Line 828 \| public class Vector<E>
828		* specified Collection is this Vector, and this Vector is nonempty.)
829		*
830		* @param c elements to be inserted into this Vector
831	<	* @return <tt>true</tt> if this Vector changed as a result of the call
831	>	* @return {@code true} if this Vector changed as a result of the call
832		* @throws NullPointerException if the specified collection is null
833		* @since 1.2
834		*/
#	Line 898 \| Line 891 \| public class Vector<E>
891		* @param index index at which to insert the first element from the
892		* specified collection
893		* @param c elements to be inserted into this Vector
894	<	* @return <tt>true</tt> if this Vector changed as a result of the call
894	>	* @return {@code true} if this Vector changed as a result of the call
895		* @exception ArrayIndexOutOfBoundsException index out of range (index
896		* < 0 \|\| index > size())
897		* @throws NullPointerException if the specified collection is null
#	Line 927 \| Line 920 \| public class Vector<E>
920		* Compares the specified Object with this Vector for equality. Returns
921		* true if and only if the specified Object is also a List, both Lists
922		* have the same size, and all corresponding pairs of elements in the two
923	<	* Lists are <em>equal</em>. (Two elements <code>e1</code> and
924	<	* <code>e2</code> are <em>equal</em> if <code>(e1==null ? e2==null :
925	<	* e1.equals(e2))</code>.) In other words, two Lists are defined to be
923	>	* Lists are <em>equal</em>. (Two elements {@code e1} and
924	>	* {@code e2} are <em>equal</em> if {@code (e1==null ? e2==null :
925	>	* e1.equals(e2))}.) In other words, two Lists are defined to be
926		* equal if they contain the same elements in the same order.
927		*
928		* @param o the Object to be compared for equality with this Vector
#	Line 955 \| Line 948 \| public class Vector<E>
948		}
949
950		/**
958	–	* Returns a view of the portion of this List between fromIndex,
959	–	* inclusive, and toIndex, exclusive. (If fromIndex and toIndex are
960	–	* equal, the returned List is empty.) The returned List is backed by this
961	–	* List, so changes in the returned List are reflected in this List, and
962	–	* vice-versa. The returned List supports all of the optional List
963	–	* operations supported by this List.<p>
964	–	*
965	–	* This method eliminates the need for explicit range operations (of
966	–	* the sort that commonly exist for arrays). Any operation that expects
967	–	* a List can be used as a range operation by operating on a subList view
968	–	* instead of a whole List. For example, the following idiom
969	–	* removes a range of elements from a List:
970	–	* <pre>
971	–	* list.subList(from, to).clear();
972	–	* </pre>
973	–	* Similar idioms may be constructed for indexOf and lastIndexOf,
974	–	* and all of the algorithms in the Collections class can be applied to
975	–	* a subList.<p>
976	–	*
977	–	* The semantics of the List returned by this method become undefined if
978	–	* the backing list (i.e., this List) is <i>structurally modified</i> in
979	–	* any way other than via the returned List. (Structural modifications are
980	–	* those that change the size of the List, or otherwise perturb it in such
981	–	* a fashion that iterations in progress may yield incorrect results.)
982	–	*
983	–	* @param fromIndex low endpoint (inclusive) of the subList
984	–	* @param toIndex high endpoint (exclusive) of the subList
985	–	* @return a view of the specified range within this List
986	–	* @throws IndexOutOfBoundsException endpoint index value out of range
987	–	* <code>(fromIndex < 0 \|\| toIndex > size)</code>
988	–	* @throws IllegalArgumentException endpoint indices out of order
989	–	* <code>(fromIndex > toIndex)</code>
990	–	*/
991	–	public synchronized List<E> subList(int fromIndex, int toIndex) {
992	–	return Collections.synchronizedList(super.subList(fromIndex, toIndex),
993	–	this);
994	–	}
995	–
996	–	/**
951		* Removes from this List all of the elements whose index is between
952		* fromIndex, inclusive and toIndex, exclusive. Shifts any succeeding
953		* elements to the left (reduces their index).
954	<	* This call shortens the ArrayList by (toIndex - fromIndex) elements. (If
954	>	* This call shortens the Vector by (toIndex - fromIndex) elements. (If
955		* toIndex==fromIndex, this operation has no effect.)
956		*
957		* @param fromIndex index of first element to be removed
#	Line 1016 \| Line 970 \| public class Vector<E>
970		}
971
972		/**
973	<	* Save the state of the <tt>Vector</tt> instance to a stream (that
973	>	* Save the state of the {@code Vector} instance to a stream (that
974		* is, serialize it). This method is present merely for synchronization.
975		* It just calls the default writeObject method.
976		*/
#	Line 1029 \| Line 983 \| public class Vector<E>
983		/**
984		* Returns a list-iterator of the elements in this list (in proper
985		* sequence), starting at the specified position in the list.
986	<	* Obeys the general contract of <tt>List.listIterator(int)</tt>.<p>
986	>	* Obeys the general contract of {@link List#listIterator(int)}.
987		*
988	<	* The list-iterator is <i>fail-fast</i>: if the list is structurally
988	>	* <p>The list-iterator is <i>fail-fast</i>: if the list is structurally
989		* modified at any time after the Iterator is created, in any way except
990	<	* through the list-iterator's own <tt>remove</tt> or <tt>add</tt>
990	>	* through the list-iterator's own {@code remove} or {@code add}
991		* methods, the list-iterator will throw a
992	<	* <tt>ConcurrentModificationException</tt>. Thus, in the face of
992	>	* {@code ConcurrentModificationException}. Thus, in the face of
993		* concurrent modification, the iterator fails quickly and cleanly, rather
994		* than risking arbitrary, non-deterministic behavior at an undetermined
995		* time in the future.
996		*
997		* @param index index of the first element to be returned from the
998	<	* list-iterator (by a call to <tt>next</tt>)
999	<	* @return a ListIterator of the elements in this list (in proper
998	>	* list-iterator (by a call to {@link ListIterator#next})
999	>	* @return a list-iterator of the elements in this list (in proper
1000		* sequence), starting at the specified position in the list
1001		* @throws IndexOutOfBoundsException {@inheritDoc}
1048	–	* @see List#listIterator(int)
1002		*/
1003		public synchronized ListIterator<E> listIterator(int index) {
1004		if (index < 0 \|\| index > elementCount)
1005		throw new IndexOutOfBoundsException("Index: "+index);
1006	<	return new VectorIterator(index);
1006	>	return new VectorIterator(index, elementCount);
1007		}
1008
1009		/**
1010		* {@inheritDoc}
1011		*/
1012		public synchronized ListIterator<E> listIterator() {
1013	<	return new VectorIterator(0);
1013	>	return new VectorIterator(0, elementCount);
1014		}
1015
1016		/**
#	Line 1066 \| Line 1019 \| public class Vector<E>
1019		* @return an iterator over the elements in this list in proper sequence
1020		*/
1021		public synchronized Iterator<E> iterator() {
1022	<	return new VectorIterator(0);
1022	>	return new VectorIterator(0, elementCount);
1023	>	}
1024	>
1025	>	/**
1026	>	* Helper method to access array elements under synchronization by
1027	>	* iterators. The caller performs index check with respect to
1028	>	* expected bounds, so errors accessing the element are reported
1029	>	* as ConcurrentModificationExceptions.
1030	>	*/
1031	>	final synchronized Object iteratorGet(int index, int expectedModCount) {
1032	>	if (modCount == expectedModCount) {
1033	>	try {
1034	>	return elementData[index];
1035	>	} catch(IndexOutOfBoundsException fallThrough) {
1036	>	}
1037	>	}
1038	>	throw new ConcurrentModificationException();
1039		}
1040
1041		/**
1042	<	* A streamlined version of AbstractList.ListItr.
1042	>	* Streamlined specialization of AbstractList version of iterator.
1043	>	* Locally perfroms bounds checks, but relies on outer Vector
1044	>	* to access elements under synchronization.
1045		*/
1046		private final class VectorIterator implements ListIterator<E> {
1047	<	int cursor; // current position
1048	<	int lastRet; // index of last returned element
1049	<	int expectedModCount; // to check for CME
1050	<
1051	<	VectorIterator(int index) {
1052	<	cursor = index;
1053	<	expectedModCount = modCount;
1054	<	lastRet = -1;
1047	>	int cursor; // Index of next element to return;
1048	>	int fence; // Upper bound on cursor (cache of size())
1049	>	int lastRet; // Index of last element, or -1 if no such
1050	>	int expectedModCount; // To check for CME
1051	>
1052	>	VectorIterator(int index, int fence) {
1053	>	this.cursor = index;
1054	>	this.fence = fence;
1055	>	this.lastRet = -1;
1056	>	this.expectedModCount = Vector.this.modCount;
1057		}
1058
1059		public boolean hasNext() {
1060	<	// Racy but within spec, since modifications are checked
1088	<	// within or after synchronization in next/previous
1089	<	return cursor != elementCount;
1060	>	return cursor < fence;
1061		}
1062
1063		public boolean hasPrevious() {
1064	<	return cursor != 0;
1064	>	return cursor > 0;
1065		}
1066
1067		public int nextIndex() {
#	Line 1102 \| Line 1073 \| public class Vector<E>
1073		}
1074
1075		public E next() {
1076	<	try {
1077	<	int i = cursor;
1107	<	E next = get(i);
1108	<	lastRet = i;
1109	<	cursor = i + 1;
1110	<	return next;
1111	<	} catch (IndexOutOfBoundsException ex) {
1076	>	int i = cursor;
1077	>	if (i >= fence)
1078		throw new NoSuchElementException();
1079	<	} finally {
1080	<	if (expectedModCount != modCount)
1081	<	throw new ConcurrentModificationException();
1082	<	}
1079	>	Object next = Vector.this.iteratorGet(i, expectedModCount);
1080	>	lastRet = i;
1081	>	cursor = i + 1;
1082	>	return (E)next;
1083		}
1084
1085	<	public E previous() {
1086	<	try {
1087	<	int i = cursor - 1;
1122	<	E prev = get(i);
1123	<	lastRet = i;
1124	<	cursor = i;
1125	<	return prev;
1126	<	} catch (IndexOutOfBoundsException ex) {
1085	>	public E previous() {
1086	>	int i = cursor - 1;
1087	>	if (i < 0)
1088		throw new NoSuchElementException();
1089	<	} finally {
1090	<	if (expectedModCount != modCount)
1091	<	throw new ConcurrentModificationException();
1092	<	}
1089	>	Object prev = Vector.this.iteratorGet(i, expectedModCount);
1090	>	lastRet = i;
1091	>	cursor = i;
1092	>	return (E)prev;
1093		}
1094
1095	<	public void remove() {
1096	<	if (lastRet == -1)
1095	>	public void set(E e) {
1096	>	if (lastRet < 0)
1097		throw new IllegalStateException();
1098	<	if (expectedModCount != modCount)
1099	<	throw new ConcurrentModificationException();
1100	<	try {
1101	<	Vector.this.remove(lastRet);
1102	<	if (lastRet < cursor)
1142	<	cursor--;
1143	<	lastRet = -1;
1144	<	expectedModCount = modCount;
1098	>	if (Vector.this.modCount != expectedModCount)
1099	>	throw new ConcurrentModificationException();
1100	>	try {
1101	>	Vector.this.set(lastRet, e);
1102	>	expectedModCount = Vector.this.modCount;
1103		} catch (IndexOutOfBoundsException ex) {
1104		throw new ConcurrentModificationException();
1105		}
1106		}
1107
1108	<	public void set(E e) {
1109	<	if (lastRet == -1)
1108	>	public void remove() {
1109	>	int i = lastRet;
1110	>	if (i < 0)
1111		throw new IllegalStateException();
1112	<	if (expectedModCount != modCount)
1112	>	if (Vector.this.modCount != expectedModCount)
1113		throw new ConcurrentModificationException();
1114	<	try {
1115	<	Vector.this.set(lastRet, e);
1116	<	expectedModCount = modCount;
1114	>	try {
1115	>	Vector.this.remove(i);
1116	>	if (i < cursor)
1117	>	cursor--;
1118	>	lastRet = -1;
1119	>	fence = Vector.this.size();
1120	>	expectedModCount = Vector.this.modCount;
1121		} catch (IndexOutOfBoundsException ex) {
1122		throw new ConcurrentModificationException();
1123		}
1124		}
1125
1126		public void add(E e) {
1127	<	if (expectedModCount != modCount)
1127	>	if (Vector.this.modCount != expectedModCount)
1128		throw new ConcurrentModificationException();
1129		try {
1130		int i = cursor;
1131	<	Vector.this.add(i, e);
1131	>	Vector.this.add(i, e);
1132		cursor = i + 1;
1133	<	lastRet = -1;
1134	<	expectedModCount = modCount;
1133	>	lastRet = -1;
1134	>	fence = Vector.this.size();
1135	>	expectedModCount = Vector.this.modCount;
1136		} catch (IndexOutOfBoundsException ex) {
1137		throw new ConcurrentModificationException();
1138		}
1139		}
1140		}
1141	+
1142	+	/**
1143	+	* Returns a view of the portion of this List between fromIndex,
1144	+	* inclusive, and toIndex, exclusive. (If fromIndex and toIndex are
1145	+	* equal, the returned List is empty.) The returned List is backed by this
1146	+	* List, so changes in the returned List are reflected in this List, and
1147	+	* vice-versa. The returned List supports all of the optional List
1148	+	* operations supported by this List.<p>
1149	+	*
1150	+	* This method eliminates the need for explicit range operations (of
1151	+	* the sort that commonly exist for arrays). Any operation that expects
1152	+	* a List can be used as a range operation by operating on a subList view
1153	+	* instead of a whole List. For example, the following idiom
1154	+	* removes a range of elements from a List:
1155	+	* <pre>
1156	+	* list.subList(from, to).clear();
1157	+	* </pre>
1158	+	* Similar idioms may be constructed for indexOf and lastIndexOf,
1159	+	* and all of the algorithms in the Collections class can be applied to
1160	+	* a subList.<p>
1161	+	*
1162	+	* The semantics of the List returned by this method become undefined if
1163	+	* the backing list (i.e., this List) is <i>structurally modified</i> in
1164	+	* any way other than via the returned List. (Structural modifications are
1165	+	* those that change the size of the List, or otherwise perturb it in such
1166	+	* a fashion that iterations in progress may yield incorrect results.)
1167	+	*
1168	+	* @param fromIndex low endpoint (inclusive) of the subList
1169	+	* @param toIndex high endpoint (exclusive) of the subList
1170	+	* @return a view of the specified range within this List
1171	+	* @throws IndexOutOfBoundsException endpoint index value out of range
1172	+	* <code>(fromIndex < 0 \|\| toIndex > size)</code>
1173	+	* @throws IllegalArgumentException endpoint indices out of order
1174	+	* <code>(fromIndex > toIndex)</code>
1175	+	*/
1176	+	public synchronized List<E> subList(int fromIndex, int toIndex) {
1177	+	return new VectorSubList(this, this, fromIndex, fromIndex, toIndex);
1178	+	}
1179	+
1180	+	/**
1181	+	* This class specializes the AbstractList version of SubList to
1182	+	* avoid the double-indirection penalty that would arise using a
1183	+	* synchronized wrapper, as well as to avoid some unnecessary
1184	+	* checks in sublist iterators.
1185	+	*/
1186	+	private static final class VectorSubList<E> extends AbstractList<E> implements RandomAccess {
1187	+	final Vector<E> base; // base list
1188	+	final AbstractList<E> parent; // Creating list
1189	+	final int baseOffset; // index wrt Vector
1190	+	final int parentOffset; // index wrt parent
1191	+	int length; // length of sublist
1192	+
1193	+	VectorSubList(Vector<E> base, AbstractList<E> parent, int baseOffset,
1194	+	int fromIndex, int toIndex) {
1195	+	if (fromIndex < 0)
1196	+	throw new IndexOutOfBoundsException("fromIndex = " + fromIndex);
1197	+	if (toIndex > parent.size())
1198	+	throw new IndexOutOfBoundsException("toIndex = " + toIndex);
1199	+	if (fromIndex > toIndex)
1200	+	throw new IllegalArgumentException("fromIndex(" + fromIndex +
1201	+	") > toIndex(" + toIndex + ")");
1202	+
1203	+	this.base = base;
1204	+	this.parent = parent;
1205	+	this.baseOffset = baseOffset;
1206	+	this.parentOffset = fromIndex;
1207	+	this.length = toIndex - fromIndex;
1208	+	modCount = base.modCount;
1209	+	}
1210	+
1211	+	/**
1212	+	* Returns an IndexOutOfBoundsException with nicer message
1213	+	*/
1214	+	private IndexOutOfBoundsException indexError(int index) {
1215	+	return new IndexOutOfBoundsException("Index: " + index +
1216	+	", Size: " + length);
1217	+	}
1218	+
1219	+	public E set(int index, E element) {
1220	+	synchronized(base) {
1221	+	if (index < 0 \|\| index >= length)
1222	+	throw indexError(index);
1223	+	if (base.modCount != modCount)
1224	+	throw new ConcurrentModificationException();
1225	+	return base.set(index + baseOffset, element);
1226	+	}
1227	+	}
1228	+
1229	+	public E get(int index) {
1230	+	synchronized(base) {
1231	+	if (index < 0 \|\| index >= length)
1232	+	throw indexError(index);
1233	+	if (base.modCount != modCount)
1234	+	throw new ConcurrentModificationException();
1235	+	return base.get(index + baseOffset);
1236	+	}
1237	+	}
1238	+
1239	+	public int size() {
1240	+	synchronized(base) {
1241	+	if (base.modCount != modCount)
1242	+	throw new ConcurrentModificationException();
1243	+	return length;
1244	+	}
1245	+	}
1246	+
1247	+	public void add(int index, E element) {
1248	+	synchronized(base) {
1249	+	if (index < 0 \|\| index > length)
1250	+	throw indexError(index);
1251	+	if (base.modCount != modCount)
1252	+	throw new ConcurrentModificationException();
1253	+	parent.add(index + parentOffset, element);
1254	+	length++;
1255	+	modCount = base.modCount;
1256	+	}
1257	+	}
1258	+
1259	+	public E remove(int index) {
1260	+	synchronized(base) {
1261	+	if (index < 0 \|\| index >= length)
1262	+	throw indexError(index);
1263	+	if (base.modCount != modCount)
1264	+	throw new ConcurrentModificationException();
1265	+	E result = parent.remove(index + parentOffset);
1266	+	length--;
1267	+	modCount = base.modCount;
1268	+	return result;
1269	+	}
1270	+	}
1271	+
1272	+	protected void removeRange(int fromIndex, int toIndex) {
1273	+	synchronized(base) {
1274	+	if (base.modCount != modCount)
1275	+	throw new ConcurrentModificationException();
1276	+	parent.removeRange(fromIndex + parentOffset,
1277	+	toIndex + parentOffset);
1278	+	length -= (toIndex-fromIndex);
1279	+	modCount = base.modCount;
1280	+	}
1281	+	}
1282	+
1283	+	public boolean addAll(Collection<? extends E> c) {
1284	+	return addAll(length, c);
1285	+	}
1286	+
1287	+	public boolean addAll(int index, Collection<? extends E> c) {
1288	+	synchronized(base) {
1289	+	if (index < 0 \|\| index > length)
1290	+	throw indexError(index);
1291	+	int cSize = c.size();
1292	+	if (cSize==0)
1293	+	return false;
1294	+
1295	+	if (base.modCount != modCount)
1296	+	throw new ConcurrentModificationException();
1297	+	parent.addAll(parentOffset + index, c);
1298	+	modCount = base.modCount;
1299	+	length += cSize;
1300	+	return true;
1301	+	}
1302	+	}
1303	+
1304	+	public boolean equals(Object o) {
1305	+	synchronized(base) {return super.equals(o);}
1306	+	}
1307	+
1308	+	public int hashCode() {
1309	+	synchronized(base) {return super.hashCode();}
1310	+	}
1311	+
1312	+	public int indexOf(Object o) {
1313	+	synchronized(base) {return super.indexOf(o);}
1314	+	}
1315	+
1316	+	public int lastIndexOf(Object o) {
1317	+	synchronized(base) {return super.lastIndexOf(o);}
1318	+	}
1319	+
1320	+	public List<E> subList(int fromIndex, int toIndex) {
1321	+	return new VectorSubList(base, this, fromIndex + baseOffset,
1322	+	fromIndex, toIndex);
1323	+	}
1324	+
1325	+	public Iterator<E> iterator() {
1326	+	synchronized(base) {
1327	+	return new VectorSubListIterator(this, 0);
1328	+	}
1329	+	}
1330	+
1331	+	public synchronized ListIterator<E> listIterator() {
1332	+	synchronized(base) {
1333	+	return new VectorSubListIterator(this, 0);
1334	+	}
1335	+	}
1336	+
1337	+	public ListIterator<E> listIterator(int index) {
1338	+	synchronized(base) {
1339	+	if (index < 0 \|\| index > length)
1340	+	throw indexError(index);
1341	+	return new VectorSubListIterator(this, index);
1342	+	}
1343	+	}
1344	+
1345	+	/**
1346	+	* Same idea as VectorIterator, except routing structural
1347	+	* change operations through the sublist.
1348	+	*/
1349	+	private static final class VectorSubListIterator<E> implements ListIterator<E> {
1350	+	final Vector<E> base; // base list
1351	+	final VectorSubList<E> outer; // Sublist creating this iteraor
1352	+	final int offset; // cursor offset wrt base
1353	+	int cursor; // Current index
1354	+	int fence; // Upper bound on cursor
1355	+	int lastRet; // Index of returned element, or -1
1356	+	int expectedModCount; // Expected modCount of base Vector
1357	+
1358	+	VectorSubListIterator(VectorSubList<E> list, int index) {
1359	+	this.lastRet = -1;
1360	+	this.cursor = index;
1361	+	this.outer = list;
1362	+	this.offset = list.baseOffset;
1363	+	this.fence = list.length;
1364	+	this.base = list.base;
1365	+	this.expectedModCount = base.modCount;
1366	+	}
1367	+
1368	+	public boolean hasNext() {
1369	+	return cursor < fence;
1370	+	}
1371	+
1372	+	public boolean hasPrevious() {
1373	+	return cursor > 0;
1374	+	}
1375	+
1376	+	public int nextIndex() {
1377	+	return cursor;
1378	+	}
1379	+
1380	+	public int previousIndex() {
1381	+	return cursor - 1;
1382	+	}
1383	+
1384	+	public E next() {
1385	+	int i = cursor;
1386	+	if (cursor >= fence)
1387	+	throw new NoSuchElementException();
1388	+	Object next = base.iteratorGet(i + offset, expectedModCount);
1389	+	lastRet = i;
1390	+	cursor = i + 1;
1391	+	return (E)next;
1392	+	}
1393	+
1394	+	public E previous() {
1395	+	int i = cursor - 1;
1396	+	if (i < 0)
1397	+	throw new NoSuchElementException();
1398	+	Object prev = base.iteratorGet(i + offset, expectedModCount);
1399	+	lastRet = i;
1400	+	cursor = i;
1401	+	return (E)prev;
1402	+	}
1403	+
1404	+	public void set(E e) {
1405	+	if (lastRet < 0)
1406	+	throw new IllegalStateException();
1407	+	if (base.modCount != expectedModCount)
1408	+	throw new ConcurrentModificationException();
1409	+	try {
1410	+	outer.set(lastRet, e);
1411	+	expectedModCount = base.modCount;
1412	+	} catch (IndexOutOfBoundsException ex) {
1413	+	throw new ConcurrentModificationException();
1414	+	}
1415	+	}
1416	+
1417	+	public void remove() {
1418	+	int i = lastRet;
1419	+	if (i < 0)
1420	+	throw new IllegalStateException();
1421	+	if (base.modCount != expectedModCount)
1422	+	throw new ConcurrentModificationException();
1423	+	try {
1424	+	outer.remove(i);
1425	+	if (i < cursor)
1426	+	cursor--;
1427	+	lastRet = -1;
1428	+	fence = outer.length;
1429	+	expectedModCount = base.modCount;
1430	+	} catch (IndexOutOfBoundsException ex) {
1431	+	throw new ConcurrentModificationException();
1432	+	}
1433	+	}
1434	+
1435	+	public void add(E e) {
1436	+	if (base.modCount != expectedModCount)
1437	+	throw new ConcurrentModificationException();
1438	+	try {
1439	+	int i = cursor;
1440	+	outer.add(i, e);
1441	+	cursor = i + 1;
1442	+	lastRet = -1;
1443	+	fence = outer.length;
1444	+	expectedModCount = base.modCount;
1445	+	} catch (IndexOutOfBoundsException ex) {
1446	+	throw new ConcurrentModificationException();
1447	+	}
1448	+	}
1449	+	}
1450	+	}
1451		}
1452	+
1453	+
1454	+

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing jsr166/src/main/java/util/Vector.java (file contents): Revision 1.7 by jsr166, Mon Dec 5 02:56:59 2005 UTC vs. Revision 1.15 by jsr166, Sun Jun 25 19:58:14 2006 UTC

Diff Legend

Comparing jsr166/src/main/java/util/Vector.java (file contents):
Revision 1.7 by jsr166, Mon Dec 5 02:56:59 2005 UTC vs.
Revision 1.15 by jsr166, Sun Jun 25 19:58:14 2006 UTC