1 /*
   2  * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27  * Written by Doug Lea with assistance from members of JCP JSR-166
  28  * Expert Group.  Adapted and released, under explicit permission,
  29  * from JDK ArrayList.java which carries the following copyright:
  30  *
  31  * Copyright 1997 by Sun Microsystems, Inc.,
  32  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  33  * All rights reserved.
  34  */
  35 
  36 package java.util.concurrent;
  37 import java.util.*;
  38 import java.util.concurrent.locks.*;
  39 import sun.misc.Unsafe;
  40 
  41 /**
  42  * A thread-safe variant of {@link java.util.ArrayList} in which all mutative
  43  * operations (<tt>add</tt>, <tt>set</tt>, and so on) are implemented by
  44  * making a fresh copy of the underlying array.
  45  *
  46  * <p> This is ordinarily too costly, but may be <em>more</em> efficient
  47  * than alternatives when traversal operations vastly outnumber
  48  * mutations, and is useful when you cannot or don't want to
  49  * synchronize traversals, yet need to preclude interference among
  50  * concurrent threads.  The "snapshot" style iterator method uses a
  51  * reference to the state of the array at the point that the iterator
  52  * was created. This array never changes during the lifetime of the
  53  * iterator, so interference is impossible and the iterator is
  54  * guaranteed not to throw <tt>ConcurrentModificationException</tt>.
  55  * The iterator will not reflect additions, removals, or changes to
  56  * the list since the iterator was created.  Element-changing
  57  * operations on iterators themselves (<tt>remove</tt>, <tt>set</tt>, and
  58  * <tt>add</tt>) are not supported. These methods throw
  59  * <tt>UnsupportedOperationException</tt>.
  60  *
  61  * <p>All elements are permitted, including <tt>null</tt>.
  62  *
  63  * <p>Memory consistency effects: As with other concurrent
  64  * collections, actions in a thread prior to placing an object into a
  65  * {@code CopyOnWriteArrayList}
  66  * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
  67  * actions subsequent to the access or removal of that element from
  68  * the {@code CopyOnWriteArrayList} in another thread.
  69  *
  70  * <p>This class is a member of the
  71  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
  72  * Java Collections Framework</a>.
  73  *
  74  * @since 1.5
  75  * @author Doug Lea
  76  * @param <E> the type of elements held in this collection
  77  */
  78 public class CopyOnWriteArrayList<E>
  79     implements List<E>, RandomAccess, Cloneable, java.io.Serializable {
  80     private static final long serialVersionUID = 8673264195747942595L;
  81 
  82     /** The lock protecting all mutators */
  83     transient final ReentrantLock lock = new ReentrantLock();
  84 
  85     /** The array, accessed only via getArray/setArray. */
  86     private volatile transient Object[] array;
  87 
  88     /**
  89      * Gets the array.  Non-private so as to also be accessible
  90      * from CopyOnWriteArraySet class.
  91      */
  92     final Object[] getArray() {
  93         return array;
  94     }
  95 
  96     /**
  97      * Sets the array.
  98      */
  99     final void setArray(Object[] a) {
 100         array = a;
 101     }
 102 
 103     /**
 104      * Creates an empty list.
 105      */
 106     public CopyOnWriteArrayList() {
 107         setArray(new Object[0]);
 108     }
 109 
 110     /**
 111      * Creates a list containing the elements of the specified
 112      * collection, in the order they are returned by the collection's
 113      * iterator.
 114      *
 115      * @param c the collection of initially held elements
 116      * @throws NullPointerException if the specified collection is null
 117      */
 118     public CopyOnWriteArrayList(Collection<? extends E> c) {
 119         Object[] elements = c.toArray();
 120         // c.toArray might (incorrectly) not return Object[] (see 6260652)
 121         if (elements.getClass() != Object[].class)
 122             elements = Arrays.copyOf(elements, elements.length, Object[].class);
 123         setArray(elements);
 124     }
 125 
 126     /**
 127      * Creates a list holding a copy of the given array.
 128      *
 129      * @param toCopyIn the array (a copy of this array is used as the
 130      *        internal array)
 131      * @throws NullPointerException if the specified array is null
 132      */
 133     public CopyOnWriteArrayList(E[] toCopyIn) {
 134         setArray(Arrays.copyOf(toCopyIn, toCopyIn.length, Object[].class));
 135     }
 136 
 137     /**
 138      * Returns the number of elements in this list.
 139      *
 140      * @return the number of elements in this list
 141      */
 142     public int size() {
 143         return getArray().length;
 144     }
 145 
 146     /**
 147      * Returns <tt>true</tt> if this list contains no elements.
 148      *
 149      * @return <tt>true</tt> if this list contains no elements
 150      */
 151     public boolean isEmpty() {
 152         return size() == 0;
 153     }
 154 
 155     /**
 156      * Test for equality, coping with nulls.
 157      */
 158     private static boolean eq(Object o1, Object o2) {
 159         return (o1 == null ? o2 == null : o1.equals(o2));
 160     }
 161 
 162     /**
 163      * static version of indexOf, to allow repeated calls without
 164      * needing to re-acquire array each time.
 165      * @param o element to search for
 166      * @param elements the array
 167      * @param index first index to search
 168      * @param fence one past last index to search
 169      * @return index of element, or -1 if absent
 170      */
 171     private static int indexOf(Object o, Object[] elements,
 172                                int index, int fence) {
 173         if (o == null) {
 174             for (int i = index; i < fence; i++)
 175                 if (elements[i] == null)
 176                     return i;
 177         } else {
 178             for (int i = index; i < fence; i++)
 179                 if (o.equals(elements[i]))
 180                     return i;
 181         }
 182         return -1;
 183     }
 184 
 185     /**
 186      * static version of lastIndexOf.
 187      * @param o element to search for
 188      * @param elements the array
 189      * @param index first index to search
 190      * @return index of element, or -1 if absent
 191      */
 192     private static int lastIndexOf(Object o, Object[] elements, int index) {
 193         if (o == null) {
 194             for (int i = index; i >= 0; i--)
 195                 if (elements[i] == null)
 196                     return i;
 197         } else {
 198             for (int i = index; i >= 0; i--)
 199                 if (o.equals(elements[i]))
 200                     return i;
 201         }
 202         return -1;
 203     }
 204 
 205     /**
 206      * Returns <tt>true</tt> if this list contains the specified element.
 207      * More formally, returns <tt>true</tt> if and only if this list contains
 208      * at least one element <tt>e</tt> such that
 209      * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
 210      *
 211      * @param o element whose presence in this list is to be tested
 212      * @return <tt>true</tt> if this list contains the specified element
 213      */
 214     public boolean contains(Object o) {
 215         Object[] elements = getArray();
 216         return indexOf(o, elements, 0, elements.length) >= 0;
 217     }
 218 
 219     /**
 220      * {@inheritDoc}
 221      */
 222     public int indexOf(Object o) {
 223         Object[] elements = getArray();
 224         return indexOf(o, elements, 0, elements.length);
 225     }
 226 
 227     /**
 228      * Returns the index of the first occurrence of the specified element in
 229      * this list, searching forwards from <tt>index</tt>, or returns -1 if
 230      * the element is not found.
 231      * More formally, returns the lowest index <tt>i</tt> such that
 232      * <tt>(i&nbsp;&gt;=&nbsp;index&nbsp;&amp;&amp;&nbsp;(e==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;e.equals(get(i))))</tt>,
 233      * or -1 if there is no such index.
 234      *
 235      * @param e element to search for
 236      * @param index index to start searching from
 237      * @return the index of the first occurrence of the element in
 238      *         this list at position <tt>index</tt> or later in the list;
 239      *         <tt>-1</tt> if the element is not found.
 240      * @throws IndexOutOfBoundsException if the specified index is negative
 241      */
 242     public int indexOf(E e, int index) {
 243         Object[] elements = getArray();
 244         return indexOf(e, elements, index, elements.length);
 245     }
 246 
 247     /**
 248      * {@inheritDoc}
 249      */
 250     public int lastIndexOf(Object o) {
 251         Object[] elements = getArray();
 252         return lastIndexOf(o, elements, elements.length - 1);
 253     }
 254 
 255     /**
 256      * Returns the index of the last occurrence of the specified element in
 257      * this list, searching backwards from <tt>index</tt>, or returns -1 if
 258      * the element is not found.
 259      * More formally, returns the highest index <tt>i</tt> such that
 260      * <tt>(i&nbsp;&lt;=&nbsp;index&nbsp;&amp;&amp;&nbsp;(e==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;e.equals(get(i))))</tt>,
 261      * or -1 if there is no such index.
 262      *
 263      * @param e element to search for
 264      * @param index index to start searching backwards from
 265      * @return the index of the last occurrence of the element at position
 266      *         less than or equal to <tt>index</tt> in this list;
 267      *         -1 if the element is not found.
 268      * @throws IndexOutOfBoundsException if the specified index is greater
 269      *         than or equal to the current size of this list
 270      */
 271     public int lastIndexOf(E e, int index) {
 272         Object[] elements = getArray();
 273         return lastIndexOf(e, elements, index);
 274     }
 275 
 276     /**
 277      * Returns a shallow copy of this list.  (The elements themselves
 278      * are not copied.)
 279      *
 280      * @return a clone of this list
 281      */
 282     public Object clone() {
 283         try {
 284             CopyOnWriteArrayList c = (CopyOnWriteArrayList)(super.clone());
 285             c.resetLock();
 286             return c;
 287         } catch (CloneNotSupportedException e) {
 288             // this shouldn't happen, since we are Cloneable
 289             throw new InternalError();
 290         }
 291     }
 292 
 293     /**
 294      * Returns an array containing all of the elements in this list
 295      * in proper sequence (from first to last element).
 296      *
 297      * <p>The returned array will be "safe" in that no references to it are
 298      * maintained by this list.  (In other words, this method must allocate
 299      * a new array).  The caller is thus free to modify the returned array.
 300      *
 301      * <p>This method acts as bridge between array-based and collection-based
 302      * APIs.
 303      *
 304      * @return an array containing all the elements in this list
 305      */
 306     public Object[] toArray() {
 307         Object[] elements = getArray();
 308         return Arrays.copyOf(elements, elements.length);
 309     }
 310 
 311     /**
 312      * Returns an array containing all of the elements in this list in
 313      * proper sequence (from first to last element); the runtime type of
 314      * the returned array is that of the specified array.  If the list fits
 315      * in the specified array, it is returned therein.  Otherwise, a new
 316      * array is allocated with the runtime type of the specified array and
 317      * the size of this list.
 318      *
 319      * <p>If this list fits in the specified array with room to spare
 320      * (i.e., the array has more elements than this list), the element in
 321      * the array immediately following the end of the list is set to
 322      * <tt>null</tt>.  (This is useful in determining the length of this
 323      * list <i>only</i> if the caller knows that this list does not contain
 324      * any null elements.)
 325      *
 326      * <p>Like the {@link #toArray()} method, this method acts as bridge between
 327      * array-based and collection-based APIs.  Further, this method allows
 328      * precise control over the runtime type of the output array, and may,
 329      * under certain circumstances, be used to save allocation costs.
 330      *
 331      * <p>Suppose <tt>x</tt> is a list known to contain only strings.
 332      * The following code can be used to dump the list into a newly
 333      * allocated array of <tt>String</tt>:
 334      *
 335      * <pre>
 336      *     String[] y = x.toArray(new String[0]);</pre>
 337      *
 338      * Note that <tt>toArray(new Object[0])</tt> is identical in function to
 339      * <tt>toArray()</tt>.
 340      *
 341      * @param a the array into which the elements of the list are to
 342      *          be stored, if it is big enough; otherwise, a new array of the
 343      *          same runtime type is allocated for this purpose.
 344      * @return an array containing all the elements in this list
 345      * @throws ArrayStoreException if the runtime type of the specified array
 346      *         is not a supertype of the runtime type of every element in
 347      *         this list
 348      * @throws NullPointerException if the specified array is null
 349      */
 350     @SuppressWarnings("unchecked")
 351     public <T> T[] toArray(T a[]) {
 352         Object[] elements = getArray();
 353         int len = elements.length;
 354         if (a.length < len)
 355             return (T[]) Arrays.copyOf(elements, len, a.getClass());
 356         else {
 357             System.arraycopy(elements, 0, a, 0, len);
 358             if (a.length > len)
 359                 a[len] = null;
 360             return a;
 361         }
 362     }
 363 
 364     // Positional Access Operations
 365 
 366     @SuppressWarnings("unchecked")
 367     private E get(Object[] a, int index) {
 368         return (E) a[index];
 369     }
 370 
 371     /**
 372      * {@inheritDoc}
 373      *
 374      * @throws IndexOutOfBoundsException {@inheritDoc}
 375      */
 376     public E get(int index) {
 377         return get(getArray(), index);
 378     }
 379 
 380     /**
 381      * Replaces the element at the specified position in this list with the
 382      * specified element.
 383      *
 384      * @throws IndexOutOfBoundsException {@inheritDoc}
 385      */
 386     public E set(int index, E element) {
 387         final ReentrantLock lock = this.lock;
 388         lock.lock();
 389         try {
 390             Object[] elements = getArray();
 391             E oldValue = get(elements, index);
 392 
 393             if (oldValue != element) {
 394                 int len = elements.length;
 395                 Object[] newElements = Arrays.copyOf(elements, len);
 396                 newElements[index] = element;
 397                 setArray(newElements);
 398             } else {
 399                 // Not quite a no-op; ensures volatile write semantics
 400                 setArray(elements);
 401             }
 402             return oldValue;
 403         } finally {
 404             lock.unlock();
 405         }
 406     }
 407 
 408     /**
 409      * Appends the specified element to the end of this list.
 410      *
 411      * @param e element to be appended to this list
 412      * @return <tt>true</tt> (as specified by {@link Collection#add})
 413      */
 414     public boolean add(E e) {
 415         final ReentrantLock lock = this.lock;
 416         lock.lock();
 417         try {
 418             Object[] elements = getArray();
 419             int len = elements.length;
 420             Object[] newElements = Arrays.copyOf(elements, len + 1);
 421             newElements[len] = e;
 422             setArray(newElements);
 423             return true;
 424         } finally {
 425             lock.unlock();
 426         }
 427     }
 428 
 429     /**
 430      * Inserts the specified element at the specified position in this
 431      * list. Shifts the element currently at that position (if any) and
 432      * any subsequent elements to the right (adds one to their indices).
 433      *
 434      * @throws IndexOutOfBoundsException {@inheritDoc}
 435      */
 436     public void add(int index, E element) {
 437         final ReentrantLock lock = this.lock;
 438         lock.lock();
 439         try {
 440             Object[] elements = getArray();
 441             int len = elements.length;
 442             if (index > len || index < 0)
 443                 throw new IndexOutOfBoundsException("Index: "+index+
 444                                                     ", Size: "+len);
 445             Object[] newElements;
 446             int numMoved = len - index;
 447             if (numMoved == 0)
 448                 newElements = Arrays.copyOf(elements, len + 1);
 449             else {
 450                 newElements = new Object[len + 1];
 451                 System.arraycopy(elements, 0, newElements, 0, index);
 452                 System.arraycopy(elements, index, newElements, index + 1,
 453                                  numMoved);
 454             }
 455             newElements[index] = element;
 456             setArray(newElements);
 457         } finally {
 458             lock.unlock();
 459         }
 460     }
 461 
 462     /**
 463      * Removes the element at the specified position in this list.
 464      * Shifts any subsequent elements to the left (subtracts one from their
 465      * indices).  Returns the element that was removed from the list.
 466      *
 467      * @throws IndexOutOfBoundsException {@inheritDoc}
 468      */
 469     public E remove(int index) {
 470         final ReentrantLock lock = this.lock;
 471         lock.lock();
 472         try {
 473             Object[] elements = getArray();
 474             int len = elements.length;
 475             E oldValue = get(elements, index);
 476             int numMoved = len - index - 1;
 477             if (numMoved == 0)
 478                 setArray(Arrays.copyOf(elements, len - 1));
 479             else {
 480                 Object[] newElements = new Object[len - 1];
 481                 System.arraycopy(elements, 0, newElements, 0, index);
 482                 System.arraycopy(elements, index + 1, newElements, index,
 483                                  numMoved);
 484                 setArray(newElements);
 485             }
 486             return oldValue;
 487         } finally {
 488             lock.unlock();
 489         }
 490     }
 491 
 492     /**
 493      * Removes the first occurrence of the specified element from this list,
 494      * if it is present.  If this list does not contain the element, it is
 495      * unchanged.  More formally, removes the element with the lowest index
 496      * <tt>i</tt> such that
 497      * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>
 498      * (if such an element exists).  Returns <tt>true</tt> if this list
 499      * contained the specified element (or equivalently, if this list
 500      * changed as a result of the call).
 501      *
 502      * @param o element to be removed from this list, if present
 503      * @return <tt>true</tt> if this list contained the specified element
 504      */
 505     public boolean remove(Object o) {
 506         final ReentrantLock lock = this.lock;
 507         lock.lock();
 508         try {
 509             Object[] elements = getArray();
 510             int len = elements.length;
 511             if (len != 0) {
 512                 // Copy while searching for element to remove
 513                 // This wins in the normal case of element being present
 514                 int newlen = len - 1;
 515                 Object[] newElements = new Object[newlen];
 516 
 517                 for (int i = 0; i < newlen; ++i) {
 518                     if (eq(o, elements[i])) {
 519                         // found one;  copy remaining and exit
 520                         for (int k = i + 1; k < len; ++k)
 521                             newElements[k-1] = elements[k];
 522                         setArray(newElements);
 523                         return true;
 524                     } else
 525                         newElements[i] = elements[i];
 526                 }
 527 
 528                 // special handling for last cell
 529                 if (eq(o, elements[newlen])) {
 530                     setArray(newElements);
 531                     return true;
 532                 }
 533             }
 534             return false;
 535         } finally {
 536             lock.unlock();
 537         }
 538     }
 539 
 540     /**
 541      * Removes from this list all of the elements whose index is between
 542      * <tt>fromIndex</tt>, inclusive, and <tt>toIndex</tt>, exclusive.
 543      * Shifts any succeeding elements to the left (reduces their index).
 544      * This call shortens the list by <tt>(toIndex - fromIndex)</tt> elements.
 545      * (If <tt>toIndex==fromIndex</tt>, this operation has no effect.)
 546      *
 547      * @param fromIndex index of first element to be removed
 548      * @param toIndex index after last element to be removed
 549      * @throws IndexOutOfBoundsException if fromIndex or toIndex out of range
 550      *         ({@code{fromIndex < 0 || toIndex > size() || toIndex < fromIndex})
 551      */
 552     private void removeRange(int fromIndex, int toIndex) {
 553         final ReentrantLock lock = this.lock;
 554         lock.lock();
 555         try {
 556             Object[] elements = getArray();
 557             int len = elements.length;
 558 
 559             if (fromIndex < 0 || toIndex > len || toIndex < fromIndex)
 560                 throw new IndexOutOfBoundsException();
 561             int newlen = len - (toIndex - fromIndex);
 562             int numMoved = len - toIndex;
 563             if (numMoved == 0)
 564                 setArray(Arrays.copyOf(elements, newlen));
 565             else {
 566                 Object[] newElements = new Object[newlen];
 567                 System.arraycopy(elements, 0, newElements, 0, fromIndex);
 568                 System.arraycopy(elements, toIndex, newElements,
 569                                  fromIndex, numMoved);
 570                 setArray(newElements);
 571             }
 572         } finally {
 573             lock.unlock();
 574         }
 575     }
 576 
 577     /**
 578      * Append the element if not present.
 579      *
 580      * @param e element to be added to this list, if absent
 581      * @return <tt>true</tt> if the element was added
 582      */
 583     public boolean addIfAbsent(E e) {
 584         final ReentrantLock lock = this.lock;
 585         lock.lock();
 586         try {
 587             // Copy while checking if already present.
 588             // This wins in the most common case where it is not present
 589             Object[] elements = getArray();
 590             int len = elements.length;
 591             Object[] newElements = new Object[len + 1];
 592             for (int i = 0; i < len; ++i) {
 593                 if (eq(e, elements[i]))
 594                     return false; // exit, throwing away copy
 595                 else
 596                     newElements[i] = elements[i];
 597             }
 598             newElements[len] = e;
 599             setArray(newElements);
 600             return true;
 601         } finally {
 602             lock.unlock();
 603         }
 604     }
 605 
 606     /**
 607      * Returns <tt>true</tt> if this list contains all of the elements of the
 608      * specified collection.
 609      *
 610      * @param c collection to be checked for containment in this list
 611      * @return <tt>true</tt> if this list contains all of the elements of the
 612      *         specified collection
 613      * @throws NullPointerException if the specified collection is null
 614      * @see #contains(Object)
 615      */
 616     public boolean containsAll(Collection<?> c) {
 617         Object[] elements = getArray();
 618         int len = elements.length;
 619         for (Object e : c) {
 620             if (indexOf(e, elements, 0, len) < 0)
 621                 return false;
 622         }
 623         return true;
 624     }
 625 
 626     /**
 627      * Removes from this list all of its elements that are contained in
 628      * the specified collection. This is a particularly expensive operation
 629      * in this class because of the need for an internal temporary array.
 630      *
 631      * @param c collection containing elements to be removed from this list
 632      * @return <tt>true</tt> if this list changed as a result of the call
 633      * @throws ClassCastException if the class of an element of this list
 634      *         is incompatible with the specified collection (optional)
 635      * @throws NullPointerException if this list contains a null element and the
 636      *         specified collection does not permit null elements (optional),
 637      *         or if the specified collection is null
 638      * @see #remove(Object)
 639      */
 640     public boolean removeAll(Collection<?> c) {
 641         final ReentrantLock lock = this.lock;
 642         lock.lock();
 643         try {
 644             Object[] elements = getArray();
 645             int len = elements.length;
 646             if (len != 0) {
 647                 // temp array holds those elements we know we want to keep
 648                 int newlen = 0;
 649                 Object[] temp = new Object[len];
 650                 for (int i = 0; i < len; ++i) {
 651                     Object element = elements[i];
 652                     if (!c.contains(element))
 653                         temp[newlen++] = element;
 654                 }
 655                 if (newlen != len) {
 656                     setArray(Arrays.copyOf(temp, newlen));
 657                     return true;
 658                 }
 659             }
 660             return false;
 661         } finally {
 662             lock.unlock();
 663         }
 664     }
 665 
 666     /**
 667      * Retains only the elements in this list that are contained in the
 668      * specified collection.  In other words, removes from this list all of
 669      * its elements that are not contained in the specified collection.
 670      *
 671      * @param c collection containing elements to be retained in this list
 672      * @return <tt>true</tt> if this list changed as a result of the call
 673      * @throws ClassCastException if the class of an element of this list
 674      *         is incompatible with the specified collection (optional)
 675      * @throws NullPointerException if this list contains a null element and the
 676      *         specified collection does not permit null elements (optional),
 677      *         or if the specified collection is null
 678      * @see #remove(Object)
 679      */
 680     public boolean retainAll(Collection<?> c) {
 681         final ReentrantLock lock = this.lock;
 682         lock.lock();
 683         try {
 684             Object[] elements = getArray();
 685             int len = elements.length;
 686             if (len != 0) {
 687                 // temp array holds those elements we know we want to keep
 688                 int newlen = 0;
 689                 Object[] temp = new Object[len];
 690                 for (int i = 0; i < len; ++i) {
 691                     Object element = elements[i];
 692                     if (c.contains(element))
 693                         temp[newlen++] = element;
 694                 }
 695                 if (newlen != len) {
 696                     setArray(Arrays.copyOf(temp, newlen));
 697                     return true;
 698                 }
 699             }
 700             return false;
 701         } finally {
 702             lock.unlock();
 703         }
 704     }
 705 
 706     /**
 707      * Appends all of the elements in the specified collection that
 708      * are not already contained in this list, to the end of
 709      * this list, in the order that they are returned by the
 710      * specified collection's iterator.
 711      *
 712      * @param c collection containing elements to be added to this list
 713      * @return the number of elements added
 714      * @throws NullPointerException if the specified collection is null
 715      * @see #addIfAbsent(Object)
 716      */
 717     public int addAllAbsent(Collection<? extends E> c) {
 718         Object[] cs = c.toArray();
 719         if (cs.length == 0)
 720             return 0;
 721         Object[] uniq = new Object[cs.length];
 722         final ReentrantLock lock = this.lock;
 723         lock.lock();
 724         try {
 725             Object[] elements = getArray();
 726             int len = elements.length;
 727             int added = 0;
 728             for (int i = 0; i < cs.length; ++i) { // scan for duplicates
 729                 Object e = cs[i];
 730                 if (indexOf(e, elements, 0, len) < 0 &&
 731                     indexOf(e, uniq, 0, added) < 0)
 732                     uniq[added++] = e;
 733             }
 734             if (added > 0) {
 735                 Object[] newElements = Arrays.copyOf(elements, len + added);
 736                 System.arraycopy(uniq, 0, newElements, len, added);
 737                 setArray(newElements);
 738             }
 739             return added;
 740         } finally {
 741             lock.unlock();
 742         }
 743     }
 744 
 745     /**
 746      * Removes all of the elements from this list.
 747      * The list will be empty after this call returns.
 748      */
 749     public void clear() {
 750         final ReentrantLock lock = this.lock;
 751         lock.lock();
 752         try {
 753             setArray(new Object[0]);
 754         } finally {
 755             lock.unlock();
 756         }
 757     }
 758 
 759     /**
 760      * Appends all of the elements in the specified collection to the end
 761      * of this list, in the order that they are returned by the specified
 762      * collection's iterator.
 763      *
 764      * @param c collection containing elements to be added to this list
 765      * @return <tt>true</tt> if this list changed as a result of the call
 766      * @throws NullPointerException if the specified collection is null
 767      * @see #add(Object)
 768      */
 769     public boolean addAll(Collection<? extends E> c) {
 770         Object[] cs = c.toArray();
 771         if (cs.length == 0)
 772             return false;
 773         final ReentrantLock lock = this.lock;
 774         lock.lock();
 775         try {
 776             Object[] elements = getArray();
 777             int len = elements.length;
 778             Object[] newElements = Arrays.copyOf(elements, len + cs.length);
 779             System.arraycopy(cs, 0, newElements, len, cs.length);
 780             setArray(newElements);
 781             return true;
 782         } finally {
 783             lock.unlock();
 784         }
 785     }
 786 
 787     /**
 788      * Inserts all of the elements in the specified collection into this
 789      * list, starting at the specified position.  Shifts the element
 790      * currently at that position (if any) and any subsequent elements to
 791      * the right (increases their indices).  The new elements will appear
 792      * in this list in the order that they are returned by the
 793      * specified collection's iterator.
 794      *
 795      * @param index index at which to insert the first element
 796      *        from the specified collection
 797      * @param c collection containing elements to be added to this list
 798      * @return <tt>true</tt> if this list changed as a result of the call
 799      * @throws IndexOutOfBoundsException {@inheritDoc}
 800      * @throws NullPointerException if the specified collection is null
 801      * @see #add(int,Object)
 802      */
 803     public boolean addAll(int index, Collection<? extends E> c) {
 804         Object[] cs = c.toArray();
 805         final ReentrantLock lock = this.lock;
 806         lock.lock();
 807         try {
 808             Object[] elements = getArray();
 809             int len = elements.length;
 810             if (index > len || index < 0)
 811                 throw new IndexOutOfBoundsException("Index: "+index+
 812                                                     ", Size: "+len);
 813             if (cs.length == 0)
 814                 return false;
 815             int numMoved = len - index;
 816             Object[] newElements;
 817             if (numMoved == 0)
 818                 newElements = Arrays.copyOf(elements, len + cs.length);
 819             else {
 820                 newElements = new Object[len + cs.length];
 821                 System.arraycopy(elements, 0, newElements, 0, index);
 822                 System.arraycopy(elements, index,
 823                                  newElements, index + cs.length,
 824                                  numMoved);
 825             }
 826             System.arraycopy(cs, 0, newElements, index, cs.length);
 827             setArray(newElements);
 828             return true;
 829         } finally {
 830             lock.unlock();
 831         }
 832     }
 833 
 834     /**
 835      * Saves the state of the list to a stream (that is, serializes it).
 836      *
 837      * @serialData The length of the array backing the list is emitted
 838      *               (int), followed by all of its elements (each an Object)
 839      *               in the proper order.
 840      * @param s the stream
 841      */
 842     private void writeObject(java.io.ObjectOutputStream s)
 843         throws java.io.IOException{
 844 
 845         s.defaultWriteObject();
 846 
 847         Object[] elements = getArray();
 848         // Write out array length
 849         s.writeInt(elements.length);
 850 
 851         // Write out all elements in the proper order.
 852         for (Object element : elements)
 853             s.writeObject(element);
 854     }
 855 
 856     /**
 857      * Reconstitutes the list from a stream (that is, deserializes it).
 858      *
 859      * @param s the stream
 860      */
 861     private void readObject(java.io.ObjectInputStream s)
 862         throws java.io.IOException, ClassNotFoundException {
 863 
 864         s.defaultReadObject();
 865 
 866         // bind to new lock
 867         resetLock();
 868 
 869         // Read in array length and allocate array
 870         int len = s.readInt();
 871         Object[] elements = new Object[len];
 872 
 873         // Read in all elements in the proper order.
 874         for (int i = 0; i < len; i++)
 875             elements[i] = s.readObject();
 876         setArray(elements);
 877     }
 878 
 879     /**
 880      * Returns a string representation of this list.  The string
 881      * representation consists of the string representations of the list's
 882      * elements in the order they are returned by its iterator, enclosed in
 883      * square brackets (<tt>"[]"</tt>).  Adjacent elements are separated by
 884      * the characters <tt>", "</tt> (comma and space).  Elements are
 885      * converted to strings as by {@link String#valueOf(Object)}.
 886      *
 887      * @return a string representation of this list
 888      */
 889     public String toString() {
 890         return Arrays.toString(getArray());
 891     }
 892 
 893     /**
 894      * Compares the specified object with this list for equality.
 895      * Returns {@code true} if the specified object is the same object
 896      * as this object, or if it is also a {@link List} and the sequence
 897      * of elements returned by an {@linkplain List#iterator() iterator}
 898      * over the specified list is the same as the sequence returned by
 899      * an iterator over this list.  The two sequences are considered to
 900      * be the same if they have the same length and corresponding
 901      * elements at the same position in the sequence are <em>equal</em>.
 902      * Two elements {@code e1} and {@code e2} are considered
 903      * <em>equal</em> if {@code (e1==null ? e2==null : e1.equals(e2))}.
 904      *
 905      * @param o the object to be compared for equality with this list
 906      * @return {@code true} if the specified object is equal to this list
 907      */
 908     public boolean equals(Object o) {
 909         if (o == this)
 910             return true;
 911         if (!(o instanceof List))
 912             return false;
 913 
 914         List<?> list = (List<?>)(o);
 915         Iterator<?> it = list.iterator();
 916         Object[] elements = getArray();
 917         int len = elements.length;
 918         for (int i = 0; i < len; ++i)
 919             if (!it.hasNext() || !eq(elements[i], it.next()))
 920                 return false;
 921         if (it.hasNext())
 922             return false;
 923         return true;
 924     }
 925 
 926     /**
 927      * Returns the hash code value for this list.
 928      *
 929      * <p>This implementation uses the definition in {@link List#hashCode}.
 930      *
 931      * @return the hash code value for this list
 932      */
 933     public int hashCode() {
 934         int hashCode = 1;
 935         Object[] elements = getArray();
 936         int len = elements.length;
 937         for (int i = 0; i < len; ++i) {
 938             Object obj = elements[i];
 939             hashCode = 31*hashCode + (obj==null ? 0 : obj.hashCode());
 940         }
 941         return hashCode;
 942     }
 943 
 944     /**
 945      * Returns an iterator over the elements in this list in proper sequence.
 946      *
 947      * <p>The returned iterator provides a snapshot of the state of the list
 948      * when the iterator was constructed. No synchronization is needed while
 949      * traversing the iterator. The iterator does <em>NOT</em> support the
 950      * <tt>remove</tt> method.
 951      *
 952      * @return an iterator over the elements in this list in proper sequence
 953      */
 954     public Iterator<E> iterator() {
 955         return new COWIterator<E>(getArray(), 0);
 956     }
 957 
 958     /**
 959      * {@inheritDoc}
 960      *
 961      * <p>The returned iterator provides a snapshot of the state of the list
 962      * when the iterator was constructed. No synchronization is needed while
 963      * traversing the iterator. The iterator does <em>NOT</em> support the
 964      * <tt>remove</tt>, <tt>set</tt> or <tt>add</tt> methods.
 965      */
 966     public ListIterator<E> listIterator() {
 967         return new COWIterator<E>(getArray(), 0);
 968     }
 969 
 970     /**
 971      * {@inheritDoc}
 972      *
 973      * <p>The returned iterator provides a snapshot of the state of the list
 974      * when the iterator was constructed. No synchronization is needed while
 975      * traversing the iterator. The iterator does <em>NOT</em> support the
 976      * <tt>remove</tt>, <tt>set</tt> or <tt>add</tt> methods.
 977      *
 978      * @throws IndexOutOfBoundsException {@inheritDoc}
 979      */
 980     public ListIterator<E> listIterator(final int index) {
 981         Object[] elements = getArray();
 982         int len = elements.length;
 983         if (index<0 || index>len)
 984             throw new IndexOutOfBoundsException("Index: "+index);
 985 
 986         return new COWIterator<E>(elements, index);
 987     }
 988 
 989     private static class COWIterator<E> implements ListIterator<E> {
 990         /** Snapshot of the array */
 991         private final Object[] snapshot;
 992         /** Index of element to be returned by subsequent call to next.  */
 993         private int cursor;
 994 
 995         private COWIterator(Object[] elements, int initialCursor) {
 996             cursor = initialCursor;
 997             snapshot = elements;
 998         }
 999 
1000         public boolean hasNext() {
1001             return cursor < snapshot.length;
1002         }
1003 
1004         public boolean hasPrevious() {
1005             return cursor > 0;
1006         }
1007 
1008         @SuppressWarnings("unchecked")
1009         public E next() {
1010             if (! hasNext())
1011                 throw new NoSuchElementException();
1012             return (E) snapshot[cursor++];
1013         }
1014 
1015         @SuppressWarnings("unchecked")
1016         public E previous() {
1017             if (! hasPrevious())
1018                 throw new NoSuchElementException();
1019             return (E) snapshot[--cursor];
1020         }
1021 
1022         public int nextIndex() {
1023             return cursor;
1024         }
1025 
1026         public int previousIndex() {
1027             return cursor-1;
1028         }
1029 
1030         /**
1031          * Not supported. Always throws UnsupportedOperationException.
1032          * @throws UnsupportedOperationException always; <tt>remove</tt>
1033          *         is not supported by this iterator.
1034          */
1035         public void remove() {
1036             throw new UnsupportedOperationException();
1037         }
1038 
1039         /**
1040          * Not supported. Always throws UnsupportedOperationException.
1041          * @throws UnsupportedOperationException always; <tt>set</tt>
1042          *         is not supported by this iterator.
1043          */
1044         public void set(E e) {
1045             throw new UnsupportedOperationException();
1046         }
1047 
1048         /**
1049          * Not supported. Always throws UnsupportedOperationException.
1050          * @throws UnsupportedOperationException always; <tt>add</tt>
1051          *         is not supported by this iterator.
1052          */
1053         public void add(E e) {
1054             throw new UnsupportedOperationException();
1055         }
1056     }
1057 
1058     /**
1059      * Returns a view of the portion of this list between
1060      * <tt>fromIndex</tt>, inclusive, and <tt>toIndex</tt>, exclusive.
1061      * The returned list is backed by this list, so changes in the
1062      * returned list are reflected in this list.
1063      *
1064      * <p>The semantics of the list returned by this method become
1065      * undefined if the backing list (i.e., this list) is modified in
1066      * any way other than via the returned list.
1067      *
1068      * @param fromIndex low endpoint (inclusive) of the subList
1069      * @param toIndex high endpoint (exclusive) of the subList
1070      * @return a view of the specified range within this list
1071      * @throws IndexOutOfBoundsException {@inheritDoc}
1072      */
1073     public List<E> subList(int fromIndex, int toIndex) {
1074         final ReentrantLock lock = this.lock;
1075         lock.lock();
1076         try {
1077             Object[] elements = getArray();
1078             int len = elements.length;
1079             if (fromIndex < 0 || toIndex > len || fromIndex > toIndex)
1080                 throw new IndexOutOfBoundsException();
1081             return new COWSubList<E>(this, fromIndex, toIndex);
1082         } finally {
1083             lock.unlock();
1084         }
1085     }
1086 
1087     /**
1088      * Sublist for CopyOnWriteArrayList.
1089      * This class extends AbstractList merely for convenience, to
1090      * avoid having to define addAll, etc. This doesn't hurt, but
1091      * is wasteful.  This class does not need or use modCount
1092      * mechanics in AbstractList, but does need to check for
1093      * concurrent modification using similar mechanics.  On each
1094      * operation, the array that we expect the backing list to use
1095      * is checked and updated.  Since we do this for all of the
1096      * base operations invoked by those defined in AbstractList,
1097      * all is well.  While inefficient, this is not worth
1098      * improving.  The kinds of list operations inherited from
1099      * AbstractList are already so slow on COW sublists that
1100      * adding a bit more space/time doesn't seem even noticeable.
1101      */
1102     private static class COWSubList<E>
1103         extends AbstractList<E>
1104         implements RandomAccess
1105     {
1106         private final CopyOnWriteArrayList<E> l;
1107         private final int offset;
1108         private int size;
1109         private Object[] expectedArray;
1110 
1111         // only call this holding l's lock
1112         COWSubList(CopyOnWriteArrayList<E> list,
1113                    int fromIndex, int toIndex) {
1114             l = list;
1115             expectedArray = l.getArray();
1116             offset = fromIndex;
1117             size = toIndex - fromIndex;
1118         }
1119 
1120         // only call this holding l's lock
1121         private void checkForComodification() {
1122             if (l.getArray() != expectedArray)
1123                 throw new ConcurrentModificationException();
1124         }
1125 
1126         // only call this holding l's lock
1127         private void rangeCheck(int index) {
1128             if (index<0 || index>=size)
1129                 throw new IndexOutOfBoundsException("Index: "+index+
1130                                                     ",Size: "+size);
1131         }
1132 
1133         public E set(int index, E element) {
1134             final ReentrantLock lock = l.lock;
1135             lock.lock();
1136             try {
1137                 rangeCheck(index);
1138                 checkForComodification();
1139                 E x = l.set(index+offset, element);
1140                 expectedArray = l.getArray();
1141                 return x;
1142             } finally {
1143                 lock.unlock();
1144             }
1145         }
1146 
1147         public E get(int index) {
1148             final ReentrantLock lock = l.lock;
1149             lock.lock();
1150             try {
1151                 rangeCheck(index);
1152                 checkForComodification();
1153                 return l.get(index+offset);
1154             } finally {
1155                 lock.unlock();
1156             }
1157         }
1158 
1159         public int size() {
1160             final ReentrantLock lock = l.lock;
1161             lock.lock();
1162             try {
1163                 checkForComodification();
1164                 return size;
1165             } finally {
1166                 lock.unlock();
1167             }
1168         }
1169 
1170         public void add(int index, E element) {
1171             final ReentrantLock lock = l.lock;
1172             lock.lock();
1173             try {
1174                 checkForComodification();
1175                 if (index<0 || index>size)
1176                     throw new IndexOutOfBoundsException();
1177                 l.add(index+offset, element);
1178                 expectedArray = l.getArray();
1179                 size++;
1180             } finally {
1181                 lock.unlock();
1182             }
1183         }
1184 
1185         public void clear() {
1186             final ReentrantLock lock = l.lock;
1187             lock.lock();
1188             try {
1189                 checkForComodification();
1190                 l.removeRange(offset, offset+size);
1191                 expectedArray = l.getArray();
1192                 size = 0;
1193             } finally {
1194                 lock.unlock();
1195             }
1196         }
1197 
1198         public E remove(int index) {
1199             final ReentrantLock lock = l.lock;
1200             lock.lock();
1201             try {
1202                 rangeCheck(index);
1203                 checkForComodification();
1204                 E result = l.remove(index+offset);
1205                 expectedArray = l.getArray();
1206                 size--;
1207                 return result;
1208             } finally {
1209                 lock.unlock();
1210             }
1211         }
1212 
1213         public boolean remove(Object o) {
1214             int index = indexOf(o);
1215             if (index == -1)
1216                 return false;
1217             remove(index);
1218             return true;
1219         }
1220 
1221         public Iterator<E> iterator() {
1222             final ReentrantLock lock = l.lock;
1223             lock.lock();
1224             try {
1225                 checkForComodification();
1226                 return new COWSubListIterator<E>(l, 0, offset, size);
1227             } finally {
1228                 lock.unlock();
1229             }
1230         }
1231 
1232         public ListIterator<E> listIterator(final int index) {
1233             final ReentrantLock lock = l.lock;
1234             lock.lock();
1235             try {
1236                 checkForComodification();
1237                 if (index<0 || index>size)
1238                     throw new IndexOutOfBoundsException("Index: "+index+
1239                                                         ", Size: "+size);
1240                 return new COWSubListIterator<E>(l, index, offset, size);
1241             } finally {
1242                 lock.unlock();
1243             }
1244         }
1245 
1246         public List<E> subList(int fromIndex, int toIndex) {
1247             final ReentrantLock lock = l.lock;
1248             lock.lock();
1249             try {
1250                 checkForComodification();
1251                 if (fromIndex<0 || toIndex>size)
1252                     throw new IndexOutOfBoundsException();
1253                 return new COWSubList<E>(l, fromIndex + offset,
1254                                          toIndex + offset);
1255             } finally {
1256                 lock.unlock();
1257             }
1258         }
1259 
1260     }
1261 
1262 
1263     private static class COWSubListIterator<E> implements ListIterator<E> {
1264         private final ListIterator<E> i;
1265         private final int index;
1266         private final int offset;
1267         private final int size;
1268 
1269         COWSubListIterator(List<E> l, int index, int offset,
1270                            int size) {
1271             this.index = index;
1272             this.offset = offset;
1273             this.size = size;
1274             i = l.listIterator(index+offset);
1275         }
1276 
1277         public boolean hasNext() {
1278             return nextIndex() < size;
1279         }
1280 
1281         public E next() {
1282             if (hasNext())
1283                 return i.next();
1284             else
1285                 throw new NoSuchElementException();
1286         }
1287 
1288         public boolean hasPrevious() {
1289             return previousIndex() >= 0;
1290         }
1291 
1292         public E previous() {
1293             if (hasPrevious())
1294                 return i.previous();
1295             else
1296                 throw new NoSuchElementException();
1297         }
1298 
1299         public int nextIndex() {
1300             return i.nextIndex() - offset;
1301         }
1302 
1303         public int previousIndex() {
1304             return i.previousIndex() - offset;
1305         }
1306 
1307         public void remove() {
1308             throw new UnsupportedOperationException();
1309         }
1310 
1311         public void set(E e) {
1312             throw new UnsupportedOperationException();
1313         }
1314 
1315         public void add(E e) {
1316             throw new UnsupportedOperationException();
1317         }
1318     }
1319 
1320     // Support for resetting lock while deserializing
1321     private void resetLock() {
1322         UNSAFE.putObjectVolatile(this, lockOffset, new ReentrantLock());
1323     }
1324     private static final sun.misc.Unsafe UNSAFE;
1325     private static final long lockOffset;
1326     static {
1327         try {
1328             UNSAFE = sun.misc.Unsafe.getUnsafe();
1329             Class k = CopyOnWriteArrayList.class;
1330             lockOffset = UNSAFE.objectFieldOffset
1331                 (k.getDeclaredField("lock"));
1332         } catch (Exception e) {
1333             throw new Error(e);
1334         }
1335     }
1336 }