Java Collection Framework : List

// 代码 1
public interface List<E> extends Collection<E> { ... }

     for (int i=0, i<list.size(); i++)
       list.get(i);

     for (Iterator i=list.iterator(); i.hasNext(); )
        i.next();

public class ArrayList<E> extends AbstractList<E>
        implements List<E>, RandomAccess, Cloneable, java.io.Serializable
{
    private static final long serialVersionUID = 8683452581122892189L;

    /**
     * The array buffer into which the elements of the ArrayList are stored.（ArrayList 支撑数组）
     * The capacity of the ArrayList is the length of this array buffer.（ArrayList 容量的定义）
     */
    private transient Object[] elementData;                 // 瞬时域

    /**
     * The size of the ArrayList (the number of elements it contains).（ArrayList 大小的定义）
     */
    private int size;


    /**
     * Constructs an empty list with the specified initial capacity
     */
    public ArrayList(int initialCapacity) {                     // 给定初始容量的构造函数
    super();
        if (initialCapacity < 0)
            throw new IllegalArgumentException("Illegal Capacity: "+
                                               initialCapacity);
    this.elementData = new Object[initialCapacity];           // 泛型与数组不兼容
    }

    /**
     * Constructs an empty list with an initial capacity of ten.
     */
    public ArrayList() {                // Java Collection Framework 规范：默认无参的构造函数
    this(10);
    }

    /**
     * Constructs a list containing the elements of the specified
     * collection, in the order they are returned by the collection's
     * iterator.
     */
    public ArrayList(Collection<? extends E> c) { // Java Collection Framework 规范：参数为指定容器的构造函数
    elementData = c.toArray();
    size = elementData.length;
    // c.toArray might (incorrectly) not return Object[] (see 6260652)
    if (elementData.getClass() != Object[].class)
        elementData = Arrays.copyOf(elementData, size, Object[].class);
    }

// 边界检查
private void RangeCheck(int index) {
  if (index >= size)
    throw new IndexOutOfBoundsException(
    "Index: "+index+", Size: "+size);
    }

// 调整数组容量
 public void ensureCapacity(int minCapacity) {
    modCount++;
    int oldCapacity = elementData.length;
    if (minCapacity > oldCapacity) {
        Object oldData[] = elementData;
        int newCapacity = (oldCapacity * 3)/2 + 1;
            if (newCapacity < minCapacity)
        newCapacity = minCapacity;
            // minCapacity is usually close to size, so this is a win:
            elementData = Arrays.copyOf(elementData, newCapacity);
    }
    }

Object oldData[] = elementData;   //为什么要用到oldData[]

public void trimToSize() {  
   modCount++;  
   int oldCapacity = elementData.length;  
   if (size < oldCapacity) {  
       elementData = Arrays.copyOf(elementData, size);  
   }  
}

private class Itr implements Iterator<E> {  
        int cursor;  
        int lastRet = -1;  
        int expectedModCount = ArrayList.this.modCount;  

        public boolean hasNext() {  
            return (this.cursor != ArrayList.this.size);  
        }  

        public E next() {  
            checkForComodification();  
            /** 省略此处代码 */  
        }  

        public void remove() {  
            if (this.lastRet < 0)  
                throw new IllegalStateException();  
            checkForComodification();  
            /** 省略此处代码 */  
        }  

        final void checkForComodification() {  
            if (ArrayList.this.modCount == this.expectedModCount)  
                return;  
            throw new ConcurrentModificationException();  
        }  
    }  

protected transient int modCount = 0;  

// 用指定的元素替代此列表中指定位置上的元素，并返回以前位于该位置上的元素  
public E set(int index, E element) {  
   RangeCheck(index);  

   E oldValue = (E) elementData[index];  
   elementData[index] = element;  
   return oldValue;  
}    

// 将指定的元素添加到此列表的尾部
public boolean add(E e) {  
   ensureCapacity(size + 1);   
   elementData[size++] = e;  
   return true;  
} 

// 将指定的元素插入此列表中的指定位置。  
// 如果当前位置有元素，则向右移动当前位于该位置的元素以及所有后续元素（将其索引加1）。  
public void add(int index, E element) {  
   if (index > size || index < 0)  
       throw new IndexOutOfBoundsException("Index: "+index+", Size: "+size);  
   // 如果数组长度不足，将进行扩容。  
   ensureCapacity(size+1);  // Increments modCount!!  
   // 将 elementData中从Index位置开始、长度为size-index的元素，  
   // 拷贝到从下标为index+1位置开始的新的elementData数组中。  
   // 即将当前位于该位置的元素以及所有后续元素右移一个位置。  
   System.arraycopy(elementData, index, elementData, index + 1, size - index);  
   elementData[index] = element;  
   size++;  
}    

// 按照指定collection的迭代器所返回的元素顺序，将该collection中的所有元素添加到此列表的尾部。  
public boolean addAll(Collection<? extends E> c) {  
   Object[] a = c.toArray();  
   int numNew = a.length;  
   ensureCapacity(size + numNew);  // Increments modCount  
   System.arraycopy(a, 0, elementData, size, numNew);  
   size += numNew;  
   return numNew != 0;  
}    

// 从指定的位置开始，将指定collection中的所有元素插入到此列表中。  
public boolean addAll(int index, Collection<? extends E> c) {  
   if (index > size || index < 0)  
       throw new IndexOutOfBoundsException(  
           "Index: " + index + ", Size: " + size);  

   Object[] a = c.toArray();  
   int numNew = a.length;  
   ensureCapacity(size + numNew);  // Increments modCount  

   int numMoved = size - index;  
   if (numMoved > 0)  
       System.arraycopy(elementData, index, elementData, index + numNew, numMoved);  

   System.arraycopy(a, 0, elementData, index, numNew);  
   size += numNew;  
   return numNew != 0;  
   }

 // 返回此列表中指定位置上的元素。  
 public E get(int index) {  
    RangeCheck(index);  
    return (E) elementData[index];  
  }  

// 移除此列表中指定位置上的元素
 public E remove(int index) {  
    RangeCheck(index);  

    modCount++;  
    E oldValue = (E) elementData[index];  

    int numMoved = size - index - 1;  
    if (numMoved > 0)  
        System.arraycopy(elementData, index+1, elementData, index, numMoved);  
    elementData[--size] = null; // Let gc do its work  

    return oldValue;  
 } 

// 移除此列表中 “首次” 出现的指定元素（如果存在）。这是因为 ArrayList 中允许存放重复的元素。  
 public boolean remove(Object o) {  
    // 由于ArrayList中允许存放null，因此下面通过两种情况来分别处理。  
    if (o == null) {  
        for (int index = 0; index < size; index++)  
            if (elementData[index] == null) {  
                // 类似remove(int index)，移除列表中指定位置上的元素。  
                fastRemove(index);  
                return true;  
            }  
    } else {  
        for (int index = 0; index < size; index++)  
            if (o.equals(elementData[index])) {  
                fastRemove(index);  
                return true;  
            }  
        }  
        return false;  
    } 
}

private void fastRemove(int index) {  
         modCount++;  
         int numMoved = size - index - 1;  
         if (numMoved > 0)  
             System.arraycopy(elementData, index+1, elementData, index,  
                              numMoved);  
         elementData[--size] = null; // Let gc do its work  
 }

public static <T> T[] copyOf(T[] original, int newLength) {  
    return (T[]) copyOf(original, newLength, original.getClass());  
}

 /**
     * @param original 源数组
     * @param newLength 目标数组的长度
     * @param newType 目标数组的类型
     */
public static <T,U> T[] copyOf(U[] original, int newLength, Class<? extends T[]> newType) {  
    T[] copy = ((Object)newType == (Object)Object[].class)  
        ? (T[]) new Object[newLength]  
        : (T[]) Array.newInstance(newType.getComponentType(), newLength);  
    System.arraycopy(original, 0, copy, 0,  
                     Math.min(original.length, newLength));  
    return copy;
}

   List list = Collections.synchronizedList(new LinkedList(...));

public class LinkedList<E>
    extends AbstractSequentialList<E>
    implements List<E>, Deque<E>, Cloneable, java.io.Serializable

private static class Entry<E> {
    E element;
    Entry<E> next;
    Entry<E> previous;

    Entry(E element, Entry<E> next, Entry<E> previous) {
        this.element = element;
        this.next = next;
        this.previous = previous;
   }
}

public class LinkedList<E>
    extends AbstractSequentialList<E>
    implements List<E>, Deque<E>, Cloneable, java.io.Serializable
{
    private transient Entry<E> header = new Entry<E>(null, null, null);
    private transient int size = 0;

    /**
     * Constructs an empty list.
     */
    public LinkedList() {
        header.next = header.previous = header;
    }

    /**
     * Constructs a list containing the elements of the specified
     * collection, in the order they are returned by the collection's
     * iterator.
     *
     * @param  c the collection whose elements are to be placed into this list
     * @throws NullPointerException if the specified collection is null
     */
    public LinkedList(Collection<? extends E> c) {
    this();
    addAll(c);
    }

// 将元素(E)添加到LinkedList中
     public boolean add(E e) {
         // 将节点(节点数据是e)添加到表头(header)之前。
         // 即，将节点添加到双向链表的末端。
         addBefore(e, header);
         return true;
     }

     public void add(int index, E element) {
         addBefore(element, (index==size ? header : entry(index)));
     }

    private Entry<E> addBefore(E e, Entry<E> entry) {
         Entry<E> newEntry = new Entry<E>(e, entry, entry.previous);
         newEntry.previous.next = newEntry;
         newEntry.next.previous = newEntry;
         size++;
         modCount++;
         return newEntry;
    }

private E remove(Entry<E> e) {
    if (e == header)
        throw new NoSuchElementException();
    // 保留将被移除的节点e的内容
    E result = e.element;
   // 将前一节点的next引用赋值为e的下一节点
    e.previous.next = e.next;
   // 将e的下一节点的previous赋值为e的上一节点
    e.next.previous = e.previous;
   // 上面两条语句的执行已经导致了无法在链表中访问到e节点，而下面解除了e节点对前后节点的引用
   e.next = e.previous = null;
  // 将被移除的节点的内容设为null
  e.element = null;
  // 修改size大小
  size--;
  modCount++;
  // 返回移除节点e的内容
  return result;
}

    public E get(int index) {
        try {
            return listIterator(index).next();
        } catch (NoSuchElementException exc) {
            throw new IndexOutOfBoundsException("Index: "+index);
        }
    }

private class ListItr implements ListIterator<E> {
    // 最近一次返回的节点，也是当前持有的节点
    private Entry<E> lastReturned = header;
    // 对下一个元素的引用
    private Entry<E> next;
    // 下一个节点的index
    private int nextIndex;
    private int expectedModCount = modCount;

    // 构造方法，接收一个index参数，返回一个ListItr对象
    ListItr(int index) {
        // 如果index小于0或大于size，抛出IndexOutOfBoundsException异常
        if (index < 0 || index > size)
        throw new IndexOutOfBoundsException("Index: "+index+
                            ", Size: "+size);
        // 判断遍历方向
        if (index < (size >> 1)) {    // 相当于除法，但比除法效率高
        // next赋值为第一个节点
        next = header.next;
        // 获取指定位置的节点
        for (nextIndex=0; nextIndex<index; nextIndex++)
            next = next.next;
        } else {
// else中的处理和if块中的处理一致，只是遍历方向不同
        next = header;
        for (nextIndex=size; nextIndex>index; nextIndex--)
            next = next.previous;
       }
   }
    // 根据nextIndex是否等于size判断时候还有下一个节点（也可以理解为是否遍历完了LinkedList）
    public boolean hasNext() {
        return nextIndex != size;
   }
    // 获取下一个元素
    public E next() {
       checkForComodification();
        // 如果nextIndex==size,则已经遍历完链表，即没有下一个节点了（实际上是有的，因为是循环链表，任何一个节点都会有上一个和下一个节点，这里的没有下一个节点只是说所有节点都已经遍历完了）
        if (nextIndex == size)
        throw new NoSuchElementException();
        // 设置最近一次返回的节点为next节点
        lastReturned = next;
        // 将next“向后移动一位”
        next = next.next;
        // index计数加1
        nextIndex++;
        // 返回lastReturned的元素
        return lastReturned.element;
   }

    public boolean hasPrevious() {
        return nextIndex != 0;
   }
    // 返回上一个节点，和next()方法相似
    public E previous() {
        if (nextIndex == 0)
        throw new NoSuchElementException();

        lastReturned = next = next.previous;
        nextIndex--;
       checkForComodification();
        return lastReturned.element;
   }

    public int nextIndex() {
        return nextIndex;
   }

    public int previousIndex() {
        return nextIndex-1;
   }
    // 移除当前Iterator持有的节点
    public void remove() {
           checkForComodification();
            Entry<E> lastNext = lastReturned.next;
            try {
                LinkedList.this.remove(lastReturned);
            } catch (NoSuchElementException e) {
                throw new IllegalStateException();
           }
        if (next==lastReturned)
                next = lastNext;
            else
        nextIndex--;
        lastReturned = header;
        expectedModCount++;
   }
    // 修改当前节点的内容
    public void set(E e) {
        if (lastReturned == header)
        throw new IllegalStateException();
       checkForComodification();
        lastReturned.element = e;
   }
    // 在当前持有节点后面插入新节点
    public void add(E e) {
       checkForComodification();
        // 将最近一次返回节点修改为header
        lastReturned = header;
       addBefore(e, next);
        nextIndex++;
        expectedModCount++;
   }
    // 判断expectedModCount和modCount是否一致，以确保通过ListItr的修改操作正确的反映在LinkedList中
    final void checkForComodification() {
        if (modCount != expectedModCount)
        throw new ConcurrentModificationException();
   }
}