[集合类]源码解析6(Queue接口、AbstractQueue抽象类、Deque接口)

上一篇：[集合类]源码解析5(ArrayList类、Vector类和Stack类)

1. Queue接口

Queue接口主要定义了队列的基本方法，下面我们分析注释，了解其实现、使用规则。

/**
 * 设计用于在处理之前保留元素的集合。 除了基本的Collection操作之外，队列还提供额外的插入，提取和检查操作。 
 * 这些方法中的每一种都有两种形式：如果操作失败，则抛出一个异常，
 * 另一种形式返回一个特殊值（ null或false ，具体取决于操作）。 
 * 插入操作的后一种形式专门设计用于容量限制的Queue实现; 在大多数实现中，插入操作不能失败。 
 *
 * 队列通常（但不一定）是以FIFO（先进先出）方式排序元素。 
 * 例外情况包括优先级队列（根据提供的比较器对元素进行排序）和LIFO队列(或堆栈)(后进先出)。
 * 无论使用什么顺序，队列的头都是通过调用remove()或poll()删除的元素。 
 * 在一个FIFO队列，所有新元素插入到队列的尾部。其他类型的队列可能使用不同的布局规则。
 * 每个Queue实现必须指定其排序属性。
 *
 * offer方法插入一个元素，如果失败返回false。这与Collection.add方法失败只能通过抛出异常不同。
 * offer方法设计在故障情况下是正常的，而不是发生异常，例如在固定容量（或“有界”）队列中。 
 * 
 * remove()和poll()方法删除并返回队列的头。从队列中删除哪个元素是队列排序策略的一个功能，它与实现不同。
 * remove()和poll()方法在队列为空时的行为不同：remove()方法抛出异常，而poll()方法返回null 。 
 * 
 * element()和peek()方法返回队列的头元素，但不删除。
 * 
 * Queue接口没有定义在并发编程中是常见的阻塞队列方法。
 * 这些方法（等待元素添加或有空间可用）在BlockingQueue接口中定义，该接口扩展了此接口。
 * 
 * Queue实现通常不允许插入null元素，尽管一些实现（例如LinkedList）允许插入null。
 * 即使在允许它的实现中，null也不应该插入到Queue中，
 * 因为null也被poll方法用作特殊的返回值，表明队列不包含元素。
 *
 * Queue实现通常不定义基于元素的equals方法和hashCode方法，而是从类别Object继承基于标识的版本，
 * 因为对于具有相同元素但不同排序属性的队列，基于元素的等式并不总是定义良好。
 */
public interface Queue<E> extends Collection<E> {
    /**
     * 插入指定元素到队列中，如果不会违反容量限制，在成功后返回true
     * 如果没有空间可用，抛出IllegalStateException异常
     * @param e the element to add
     * @return {@code true} (as specified by {@link Collection#add})
     * @throws IllegalStateException 由于容量限制，元素不能被添加
     * @throws ClassCastException 如果指定元素的类阻止将其添加到此队列中
     * @throws NullPointerException 如果指定的元素为空，并且此队列不允许添加空元素
     * @throws IllegalArgumentException 如果此元素的某些属性阻止将其添加到此队列中
     */
    boolean add(E e);

    /**
     * 插入指定元素到队列中，如果不会违反容量限制
     * 当使用容量受限的队列时，此方法通常比add方法更可取，后者插入元素失败抛出异常。
     * @param e the element to add
     * @return 如果元素被添加到此队列，则为true，否则为false
     * @throws ClassCastException 如果指定元素的类阻止将其添加到此队列中
     * @throws NullPointerException 如果指定的元素为空，并且此队列不允许添加空元素
     * @throws IllegalArgumentException 如果此元素的某些属性阻止将其添加到此队列中
     */
    boolean offer(E e);

    /**
     * 返回并删除队列的头元素。这个方法和poll方法不同的地方仅在于如果队列为空的话，remove方法会抛出异常。
     * @throws NoSuchElementException 如果队列为空
     */
    E remove();

    /**
     * 返回并删除队列的头元素，如果队列为空，返回null。
     */
    E poll();

    /**
     * 返回队列头元素，但是不删除他。这个方法和peek方法的唯一区别是，当队列为空时，element方法会抛出异常。
     * @throws NoSuchElementException 如果队列为空
     */
    E element();

    /**
     * 返回队列的头元素，但不删除他，如果队列为空的话，返回null。
     */
    E peek();
}

2. AbstractQueue 抽象类

/**
 * 该类提供一些队列操作的框架实现。
 * 当基本实现不允许空元素时，该类中的实现是适当的。
 * add方法、remove方法和element方法分别基于offer方法、poll方法、peek方法
 * 但是通过抛出异常而不是返回false或null来表明失败
 *
 * 扩展这个类的队列实现必须最少定义一个不允许插入null元素的offer方法，以及peek、poll、size、itertor方法。
 * 通常还会重写其他方法。如果不能满足这些需求，可以考虑子类化AbstractCollection
 */
public abstract class AbstractQueue<E>
    extends AbstractCollection<E>
    implements Queue<E> {

    /**
     * 给子类使用的构造器
     */
    protected AbstractQueue() {
    }

    /**
     * 如果offer成功，返回true，否则抛出IllegalStateException异常
     */
    public boolean add(E e) {
      	// 基于offer方法
        if (offer(e))
            return true;
        else
            throw new IllegalStateException("Queue full");
    }

    /**
     * 返回poll的结果，除非队列为空
     */
    public E remove() {
      	// 基于poll方法
        E x = poll();
        if (x != null)
            return x;
        else
            throw new NoSuchElementException();
    }

    /**
     * 返回peek的结果，除非队列为空
     */
    public E element() {
      	// 基于peek方法
        E x = peek();
        if (x != null)
            return x;
        else
            throw new NoSuchElementException();
    }

    /**
     * 删除队列中所有元素，重复调用poll方法，直到其返回null
     */
    public void clear() {
        while (poll() != null)
            ;
    }

    /**
     * 将指定集合中的所有元素添加到此队列。
     * 试图将所有队列添加到自身会导致IllegalArgumentException。
     * 此外，如果在操作进行过程中修改了指定的集合，则此操作的行为是未定义的。
     *
     * 此实现遍历指定的集合，并依次将迭代器返回的每个元素添加到此队列。
     * 在尝试添加元素(特别是包含null元素)时遇到的运行时异常可能会导致在抛出异常时成功添加了一部分元素。 
     *
     * @param c 包含要添加到队列中的元素
     * @return 如果此队列因调用而更改，返回true
     * @throws ClassCastException 如果指定集合的元素的类阻止将其添加到此队列中
     * @throws NullPointerException 如果指定的集合包含空元素，且此队列不允许空元素，或者指定的集合为空
     * @throws IllegalArgumentException 如果指定集合的元素的某些属性阻止将其添加到此队列，或者指定的集合是此队列
     * @throws IllegalStateException 如果由于插入限制，此时不能添加所有元素
     */
    public boolean addAll(Collection<? extends E> c) {
        if (c == null)
            throw new NullPointerException();
        if (c == this)
            throw new IllegalArgumentException();
        boolean modified = false;
        for (E e : c)
          	// 基于add方法
            if (add(e))
                modified = true;
        return modified;
    }
}

3. Deque 接口

/**
 * 支持在两端插入和移除元素的线性集合。deque是“double ended queue”的缩写，通常读作“deck”。
 * 大多数Deque实现对包含的元素的数量没有固定的限制，
 * 这个接口支持容量受限的deque以及没有固定大小限制的deque。
 * 
 * 这个接口定义了访问deque两端元素的方法。
 * 提供了用于插入、删除和检查元素的方法。
 * 这些方法都以两种形式存在:一种方法在操作失败时抛出异常，另一种方法返回特殊值(null或false，取决于操作)。
 * 后一种插入操作是专门为容量受限的Deque实现而设计的;在大多数实现中，插入操作不会失败。
 *
 * 以上12种方法总结如下表:
 **/

/**
 * 这个接口扩展了Queue接口。当deque用作队列时，FIFO(先进先出)行为将产生。
 * 元素添加在deque的末尾，并从开头删除。从Queue接口继承的方法与Deque方法完全等价，如下表所示:
 **/

/**
 * Deques也可以作为后进先出的堆栈。这个接口应该优先用于遗留Stack类。
 * 当deque用作堆栈时，元素从deque的开头被推入和弹出。
 * 如下表所示，堆栈方法与Deque方法完全等价:
 **/

/**
 * 注意，当deque被用作队列或堆栈时，peek方法也同样有效;在这两种情况下，元素都是从deque的开头抽取的。
 *
 * 这个接口提供了两种方法来删除内部元素，removeFirstOccurrence和removeLastOccurrence。
 * 
 * 与List接口不同，此接口不支持对元素的索引访问。
 *
 * 虽然并不严格要求Deque实现禁止插入空元素，但强烈建议这样做。
 * 强烈建议使用任何允许空元素的Deque实现的用户不要使用其插入空值的能力。
 * 这是因为null被各种方法用作特殊的返回值，以表明deque是空的。
 *
 * Deque实现通常不定义equals和hashCode方法的基于元素的版本，而是从类对象继承基于身份的版本。
 *
 * 该接口是Java集合框架的成员。
 */
public interface Deque<E> extends Queue<E> {
    /**
     * 如果不违反容量限制，则在deque的头部插入指定的元素。
     * 如果当前没有空间可用，抛出IllegalStateException异常。
     * 当使用容量受限的deque时，通常最好使用方法offerFirst。
     * @param e 要插入的元素
     * @throws IllegalStateException 如果由于容量限制，此时不能添加元素
     * @throws ClassCastException 如果指定元素的类阻止它被添加到此deque
     * @throws NullPointerException 如果指定的元素为空，并且deque不允许空元素
     * @throws IllegalArgumentException 如果指定元素的某些属性阻止将其添加到此deque中
     */
    void addFirst(E e);

    /**
     * 如果不违反容量限制，则在deque的尾部插入指定的元素。
     * 如果当前没有空间可用，抛出IllegalStateException异常。
     * 当使用容量受限的deque时，通常最好使用方法offerLast。
     *
     * 这个方法等同于add方法。
     *
     * @param e 要插入的元素
     * @throws IllegalStateException 如果由于容量限制，此时不能添加元素
     * @throws ClassCastException 如果指定元素的类阻止它被添加到此deque
     * @throws NullPointerException 如果指定的元素为空，并且deque不允许空元素
     * @throws IllegalArgumentException 如果指定元素的某些属性阻止将其添加到此deque中
     */
    void addLast(E e);

    /**
     * 如果不违反容量限制，则在deque的头部插入指定的元素。
     * 当使用容量受限的deque时，此方法通常比addFirst方法更好，后者可能无法插入元素，而只是抛出一个异常。
     *
     * @param e 要插入的元素
     * @throws IllegalStateException 如果由于容量限制，此时不能添加元素
     * @throws ClassCastException 如果指定元素的类阻止它被添加到此deque
     * @throws NullPointerException 如果指定的元素为空，并且deque不允许空元素
     * @throws IllegalArgumentException 如果指定元素的某些属性阻止将其添加到此deque中
     */
    boolean offerFirst(E e);

    /**
     * 如果不违反容量限制，则在deque的尾部插入指定的元素。
     * 当使用容量受限的deque时，此方法通常比addLast方法更好，后者可能无法插入元素，而只是抛出一个异常。
     *
     * @param e 要插入的元素
     * @throws IllegalStateException 如果由于容量限制，此时不能添加元素
     * @throws ClassCastException 如果指定元素的类阻止它被添加到此deque
     * @throws NullPointerException 如果指定的元素为空，并且deque不允许空元素
     * @throws IllegalArgumentException 如果指定元素的某些属性阻止将其添加到此deque中
     */
    boolean offerLast(E e);

    /**
     * 返回并且移出队列的第一个元素。这个方法不同于pollFirst只在于，当队列为空，本方法抛出异常。
     * @throws NoSuchElementException 如果队列为空
     */
    E removeFirst();

    /**
     * 返回并且移出队列的最后一个元素。这个方法不同于pollLast只在于，当队列为空，本方法抛出异常。
     * @throws NoSuchElementException 如果队列为空
     */
    E removeLast();

    /**
     * 返回并且移出队列的第一个元素，当队列为空时，返回null
     */
    E pollFirst();

    /**
     * 返回并且移出队列的最后一个元素，当队列为空时，返回null
     */
    E pollLast();

    /**
     * 返回，但不移出队列的第一个元素。这个方法不同于peekFirst方法只在于，当队列为空，本方法抛出异常。
     * @throws NoSuchElementException 如果队列为空
     */
    E getFirst();

    /**
     * 返回，但不移出队列的最后一个元素。这个方法不同于peekLast方法只在于，当队列为空，本方法抛出异常。
     * @throws NoSuchElementException 如果队列为空
     */
    E getLast();

    /**
     * 返回，但不移出队列的第一个元素。当队列为空，返回null。
     */
    E peekFirst();

    /**
     * 返回，但不移出队列的最后一个元素。当队列为空，返回null。
     */
    E peekLast();

    /**
     * 从deque中移除指定元素的第一个匹配项。如果deque不包含该元素，它将保持不变。
		 * 更正式地说，删除第一个元素o(如果存在这样的元素)。
		 * 如果这个deque包含指定的元素，则返回true(或者等价地，如果这个deque因为调用而改变)。
     *
     * @throws ClassCastException 如果指定元素的类与此deque不兼容
     * @throws NullPointerException 如果指定的元素为空，并且deque不允许空元素
     */
    boolean removeFirstOccurrence(Object o);

    /**
     * 从deque中移除指定元素的最后一个匹配项。如果deque不包含该元素，它将保持不变。
		 * 更正式地说，删除最后一个元素o(如果存在这样的元素)。
		 * 如果这个deque包含指定的元素，则返回true(或者等价地，如果这个deque因为调用而改变)。
     * @throws ClassCastException 如果指定元素的类与此deque不兼容
     * @throws NullPointerException 如果指定的元素为空，并且deque不允许空元素
     */
    boolean removeLastOccurrence(Object o);

    // *** Queue methods ***

    /**
     * 这个方法等同于addLast。
     */
    boolean add(E e);

    /**
     * 此方法等同于offerLast
     */
    boolean offer(E e);

    /**
     * 此方法等同于removeFirst
     */
    E remove();

    /**
     * 此方法等同于pollFirst
     */
    E poll();

    /**
     * 此方法等同于getFirst
     */
    E element();

    /**
     * 此方法等同于peekFirst
     */
    E peek();


    // *** Stack methods ***

    /**
     * 此方法等同于addFirst
     */
    void push(E e);

    /**
     * 此方法等同于removeFirst
     */
    E pop();


    // *** Collection methods ***

    /**
     * 从deque中移除指定元素的第一个匹配项。如果deque不包含该元素，则它将保持不变。
     * 更正式地说，删除第一个元素(如果存在这样一个元素)。
     * 如果这个deque包含指定的元素，则返回true(或者同样地，如果这个deque由于调用而改变)。
     *
     * 这个方法相当于removeFirstOccurrence(Object)方法。
     *
     * @throws ClassCastException 如果指定元素的类与此deque不兼容
     * @throws NullPointerException 如果指定的元素为空，并且deque不允许空元素
     */
    boolean remove(Object o);

    /**
     * 如果该deque包含指定的元素，则返回true。
		 * 更正式地说，当且仅当deque至少包含一个元素o时，返回true
     *
     * @param o 将被测试，是否存在在这个deque中的元素
     * @return 如果这个deque包含指定的元素，则为true
     * @throws ClassCastException 如果指定元素的类型与此deque不兼容
     * @throws NullPointerException 如果指定的元素为空，并且deque不允许空元素
     */
    boolean contains(Object o);

    /**
		 * 返回deque中的元素数量。
     */
    public int size();

    /**
     * 按适当的顺序返回deque中元素的迭代器。元素将按从第一个(head)到最后一个(tail)的顺序返回。
     */
    Iterator<E> iterator();

    /**
     * 以相反的顺序返回deque中元素的迭代器。元素将按从最后(尾)到第一个(头)的顺序返回。
     */
    Iterator<E> descendingIterator();

}

下一篇：[集合类]源码解析7(AbstractSequentialList抽象类和LinkedList类)