JDK1.8源码笔记(13) List&Queue&Deque

List

前言

An ordered collection.
一个有序的集合。List是实现Collection的。

The user of this interface has precise control over where in the list each element is inserted.
List的一个重要特点就是可以精确控制每一个element的插入位置。

The user can access elements by their integer index (position in the list), and search for elements in the list.
使用者可以通过下标访问element，并且在list中搜索element。

Unlike sets, lists typically allow duplicate elements.
和set不同，list通常允许重复element。

and they typically allow multiple null elements if they allow null elements at all.
同样的，如果允许null值，也允许null值的重复。

It is not inconceivable that someone might wish to implement a list that prohibits duplicates, by throwing runtime exceptions when the user attempts to insert them, but we expect this usage to be rare.
如果有人希望实现一个通过抛出异常来禁止插入重复值的list，这并非不可能，但我们不推荐。

* The <tt>List</tt> interface places additional stipulations, beyond those
* specified in the <tt>Collection</tt> interface, on the contracts of the
* <tt>iterator</tt>, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt>, and
* <tt>hashCode</tt> methods.  Declarations for other inherited methods are
* also included here for convenience.<p>
List在Collection上施加了一定的限制。

* Thus, iterating over the elements in a list is typically
* preferable to indexing through it if the caller does not know the
* implementation.
如果调用者不清楚具体实现的话，使用iterator遍历element通常也被认为是不错的方法。

* The <tt>List</tt> interface provides a special iterator, called a
* <tt>ListIterator</tt>, that allows element insertion and replacement, and
* bidirectional access in addition to the normal operations that the
* <tt>Iterator</tt> interface provides.  A method is provided to obtain a
* list iterator that starts at a specified position in the list.<p>
List提供一个特殊的iterator称为ListIterator，前面已经详细论述过。

* The <tt>List</tt> interface provides two methods to search for a specified
* object.  From a performance standpoint, these methods should be used with
* caution.  In many implementations they will perform costly linear
* searches.<p>
List提供了两个方法去搜索指定的对象。从性能角度上来说应该谨慎选择。

* The <tt>List</tt> interface provides two methods to efficiently insert and
* remove multiple elements at an arbitrary point in the list.<p>
List提供两个方法在特定位置高效地插入和删除多个element。

* Note: While it is permissible for lists to contain themselves as elements,
* extreme caution is advised: the <tt>equals</tt> and <tt>hashCode</tt>
* methods are no longer well defined on such a list.
如果把List本身作为element的话，要注意到equals和hashCode。

继承类&实现接口

继承Collection接口。 注意，接口和接口之间使用得也是extend。而且接口压根不能使用implements关键字。

成员变量&成员方法

List接口内首先有一干在Collection中已经定义的方法，如size、isEmpty、contains、iterator、toArray、equals和hashCode等。还有一些Collection中没有定义的方法。

E get(int index);
根据数组下标返回element。

E set(int index, E element);
修改指定下标处的元素。

void add(int index, E element);
* Inserts the specified element at the specified position in this list
* (optional operation).  Shifts the element currently at that position
* (if any) and any subsequent elements to the right (adds one to their
* indices).
把一个元素插入在指定的下标处(可选操作)。把当前的已经后面的所有都shift right。

E remove(int index);
* Removes the element at the specified position in this list (optional
* operation).  Shifts any subsequent elements to the left (subtracts one
* from their indices).  Returns the element that was removed from the
* list.
删除当前下标的元素，再把当前的和所有后续的element左移。

int indexOf(Object o);
和String类似，String也有类似的方法。

int lastIndexOf(Object o);

ListIterator<E> listIterator();
Returns a list iterator over the elements in this list (in proper sequence).
ListIterator<E> listIterator(int index);
....., starting at the specified position in the list.

List<E> subList(int fromIndex, int toIndex);

Queue

前言

A collection designed for holding elements prior to processing.
这句定义让我刷新了对Queue的认识。

* Besides basic {@link java.util.Collection Collection} operations,
* queues provide additional insertion, extraction, and inspection
* operations.
Queue也是基于Collection的，增加了很多定制服务。

Queues typically, but do not necessarily, order elements in a FIFO (first-in-first-out) manner.
通常来说Queue以FIFO的方式提供数据。

* Whatever the ordering used, the <em>head</em> of the queue is that
* element which would be removed by a call to {@link #remove() } or
* {@link #poll()}.
无论使用哪种顺序，当调用remove或poll方法时，queue的第一个element会被移除。

* In a FIFO queue, all new elements are inserted at
* the <em>tail</em> of the queue. Other kinds of queues may use
* different placement rules.  Every {@code Queue} implementation
* must specify its ordering properties.

* <p>The {@link #offer offer} method inserts an element if possible,
* otherwise returning {@code false}.  This differs from the {@link
* java.util.Collection#add Collection.add} method, which can fail to
* add an element only by throwing an unchecked exception.
Queue特化了一个新的添加数据的方法叫做offer，和Collection中默认的add方法不同的是，offer失败的时候会返回false，而add会抛出异常。

* The
* {@code offer} method is designed for use when failure is a normal,
* rather than exceptional occurrence, for example, in fixed-capacity
* (or &quot;bounded&quot;) queues.
二者在使用场景上有一定的区别，offer往往是用在那种failure是因为先天的限制而非一些错误的操作，比如说限长的队列。

* The {@code remove()} and
* {@code poll()} methods differ only in their behavior when the
* queue is empty: the {@code remove()} method throws an exception,
* while the {@code poll()} method returns {@code null}.
remove和poll的方法唯一的不同在于队列为空的时候，remove会抛出异常，poll会返回null。
需要注意的是，这个remove并非Collection定义中的remove，这个remove的返回值是E而非boolean。

* <p>The {@code Queue} interface does not define the <i>blocking queue
* methods</i>, which are common in concurrent programming.  These methods,
* which wait for elements to appear or for space to become available, are
* defined in the {@link java.util.concurrent.BlockingQueue} interface, which
* extends this interface.
有个超屌的多线程队列BlockingQueue，快去用！

* <p>{@code Queue} implementations generally do not allow insertion
* of {@code null} elements, although some implementations, such as
* {@link LinkedList}, do not prohibit insertion of {@code null}.
* Even in the implementations that permit it, {@code null} should
* not be inserted into a {@code Queue}, as {@code null} is also
* used as a special return value by the {@code poll} method to
* indicate that the queue contains no elements.
不要往Queue里放null，因为队列为空poll返回也是null，那不就尴尬了。

* <p>{@code Queue} implementations generally do not define
* element-based versions of methods {@code equals} and
* {@code hashCode} but instead inherit the identity based versions
* from class {@code Object}, because element-based equality is not
* always well-defined for queues with the same elements but different
* ordering properties.
Queue的实现通常不定义基于element版本的equals和hashCode方法。

继承类&实现接口

继承Collection接口。

成员变量&成员方法

boolean add(E e);
boolean offer(E e);
在Queue中添加一个element。add以抛出异常表示失败，offer以返回false表示失败。

E remove();
E poll();
把Queue的head返回并删除。remove以抛出异常表示失败，poll以返回null表示Queue已空。

E element();
E peek();
把Queue的head返回但是不删除。element以抛出异常表示失败，peek以返回null表示已空。

Deque

前言

* A linear collection that supports element insertion and removal at
* both ends.  The name <i>deque</i> is short for "double ended queue"
* and is usually pronounced "deck".  Most {@code Deque}
* implementations place no fixed limits on the number of elements
* they may contain, but this interface supports capacity-restricted
* deques as well as those with no fixed size limit.
一个支持可以从两头添加和删除element的collection。全称"double ended queue"，读作deck。
既可以定义容量确定的也可以定义容量不确定的Queue。

* <p>This interface defines methods to access the elements at both
* ends of the deque.  Methods are provided to insert, remove, and
* examine the element.  Each of these methods exists in two forms:
* one throws an exception if the operation fails, the other returns a
* special value (either {@code null} or {@code false}, depending on
* the operation).  The latter form of the insert operation is
* designed specifically for use with capacity-restricted
* {@code Deque} implementations; in most implementations, insert
* operations cannot fail.
每一种方法都有两种失败处理方式，一种以抛出异常表示，一种返回特殊值(比如null或false)。

When a deque is used as a queue, FIFO (First-In-First-Out) behavior results.
Deques can also be used as LIFO (Last-In-First-Out) stacks.
Deque可以被当成Queue用，也可以被当作Stack用。

Java中是定义了Stack的，但是Stack继承自Vector，意味着Stack是线程安全的，在单线程的情况下会造成性能的损失，所以可以使用Deque模拟Stack。

继承类&实现接口

继承Queue，而Queue继承Collection，相当于间接继承Collection。

成员变量&成员方法

void addFirst(E e);
boolean offerFirst(E e);

void addLast(E e);
boolean offerLast(E e);
上面是两组分别从头和尾向Deque中加入element的方法。
add表示以抛出异常的方式表示失败，offer表示以返回false的方式表示失败。

E removeFirst();
E pollFirst();

E removeLast();
E pollLast();
上面是两组分别从头和尾从Deque中取出并删除element的方法。
remove表示以抛出异常的方式表示失败，poll表示以返回false的方式表示失败。

E getFirst();
E peekFirst();

E getLast();
E peekLast();
上面是两组分别从头和尾从Deque中取出不删除element的方法。
get表示以抛出异常的方式表示失败，peek表示以返回false的方式表示失败。

boolean removeFirstOccurrence(Object o);
boolean removeLastOccurrence(Object o);
这两组方法的功能如其名，判断标准是同为null或equals为真。

另外毕竟继承自Queue，还是可以使用Queue的方式操作Deque的。
boolean add(E e); 相当于addLast
boolean offer(E e); 相当于offerLast
E remove(); 相当于removeFirst
E poll(); 相当于pollFirst
E element(); 相当于getFirst
E peek(); 相当于peekFirst

前言中提到了可以当作Stack来使用，所以还定义了Stack的方法。
void push(E e); 相当于addFirst
E pop(); 相当于removeFirst
可以看到Stack并不是从Last端操作Deque的，可能是为了和Queue进行区分。

Iterator<E> descendingIterator();
这个是和Collection中定义iterator方法想呼应，用来反向迭代。