【Java原理系列】 AbstractQueue源码分析

Java AbstractQueue源码分析

由来

Java 8中的AbstractQueue是一个抽象类，它实现了Queue接口。AbstractQueue提供了一些通用的方法和模板代码，以便更方便地实现自定义的队列数据结构。

AbstractQueue的设计初衷是为了帮助开发人员实现自己的队列类型，而无需从头开始编写所有必要的方法。它提供了一些通用的方法，如add、offer、remove、poll、element和peek，这些方法分别对应了Queue接口中定义的方法。

AbstractQueue实现了大部分Queue接口的方法，只有少数几个需要具体子类来实现。例如，实现者需要提供自己的迭代器实现，并且需要通过实现offer()和poll()方法来添加和删除元素。

AbstractQueue的存在使得开发人员能够更轻松地创建自己的队列实现，而无需关心底层数据结构的细节。它提供了一个基础框架，可以用于实现各种不同类型的队列，如优先级队列、阻塞队列等。

总之，Java 8中的AbstractQueue提供了一个可重用的队列实现的框架，使得开发人员能够更容易地创建自己的队列数据结构，并实现队列操作的常规行为。

中文源码

/**
 * 这个类提供了一些{@link Queue}操作的骨架实现。当基本实现不允许插入<tt>null</tt>元素时，该类中的实现是合适的。
 * 方法{@link #add add}、{@link #remove remove}和{@link #element element}基于{@link #offer offer}、{@link #poll poll}和{@link #peek peek}，
 * 但是抛出异常而不是通过<tt>false</tt>或<tt>null</tt>返回来表示失败。
 *
 * <p>扩展此类的<tt>Queue</tt>实现必须最低限度地定义一个{@link Queue#offer}方法，该方法不允许插入<tt>null</tt>元素，
 * 同时还要定义{@link Queue#peek}、{@link Queue#poll}、{@link Collection#size}和{@link Collection#iterator}方法。
 * 通常，还会覆盖其他方法。如果无法满足这些要求，请考虑继承{@link AbstractCollection}。
 *
 * <p>该类是
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 * Java集合框架</a>的成员。
 *
 * @since 1.5
 * @author Doug Lea
 * @param <E> 集合中保存的元素类型
 */
public abstract class AbstractQueue<E>
    extends AbstractCollection<E>
    implements Queue<E> {

    /**
     * 供子类使用的构造函数。
     */
    protected AbstractQueue() {
    }

    /**
     * 如果可以立即在不违反容量限制的情况下将指定元素插入到此队列中，则将该元素插入到此队列中，并在成功时返回<tt>true</tt>，如果当前没有可用空间，则抛出<tt>IllegalStateException</tt>。
     *
     * <p>此实现如果<tt>offer</tt>成功，则返回<tt>true</tt>，否则抛出<tt>IllegalStateException</tt>。
     *
     * @param e 要添加的元素
     * @return <tt>true</tt>（与{@link Collection#add}规定）
     * @throws IllegalStateException 如果由于容量限制，此时无法添加元素
     * @throws ClassCastException 如果指定元素的类阻止其被添加到此队列中
     * @throws NullPointerException 如果指定元素为null且此队列不允许null元素
     * @throws IllegalArgumentException 如果指定元素的某个属性阻止其被添加到此队列中
     */
    public boolean add(E e) {
        if (offer(e))
            return true;
        else
            throw new IllegalStateException("队列已满");
    }

    /**
     * 检索并删除此队列的头部。如果此队列为空，则此方法与{@link #poll poll}不同之处在于它抛出异常。
     *
     * <p>此实现返回<tt>poll</tt>的结果，除非队列为空。
     *
     * @return 此队列的头部
     * @throws NoSuchElementException 如果此队列为空
     */
    public E remove() {
        E x = poll();
        if (x != null)
            return x;
        else
            throw new NoSuchElementException();
    }

    /**
     * 检索但不删除此队列的头部。如果此队列为空，则此方法与{@link #peek peek}不同之处在于它抛出异常。
     *
     * <p>此实现返回<tt>peek</tt>的结果，除非队列为空。
     *
     * @return 此队列的头部
     * @throws NoSuchElementException 如果此队列为空
     */
    public E element() {
        E x = peek();
        if (x != null)
            return x;
        else
            throw new NoSuchElementException();
    }

    /**
     * 从此队列中移除所有元素。调用此方法后，队列将变为空。
     *
     * <p>此实现重复调用{@link #poll poll}，直到返回<tt>null</tt>为止。
     */
    public void clear() {
        while (poll() != null)
            ;
    }

    /**
     * 将指定集合中的所有元素添加到此队列中。尝试将队列本身添加到自身的addAll会导致<tt>IllegalArgumentException</tt>。
     * 此外，如果在操作进行过程中修改了指定的集合，则此操作的行为是不确定的。
     *
     * <p>此实现遍历指定的集合，并依次将迭代器返回的每个元素添加到此队列中。
     * 在尝试添加元素时遇到运行时异常（包括特别是<tt>null</tt>元素）可能导致在抛出相关异常时只有一些元素已成功添加。
     *
     * @param c 包含要添加到此队列中的元素的集合
     * @return 如果调用导致此队列发生更改，则返回<tt>true</tt>
     * @throws ClassCastException 如果指定集合中的某个元素的类阻止其被添加到此队列中
     * @throws NullPointerException 如果指定集合包含null元素且此队列不允许null元素，
     *         或者如果指定集合为null
     * @throws IllegalArgumentException 如果指定集合中某个元素的某个属性阻止其被添加到此队列中，
     *         或者如果指定集合就是此队列
     * @throws IllegalStateException 如果由于插入限制，此时无法添加所有元素
     * @see #add(Object)
     */
    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)
            if (add(e))
                modified = true;
        return modified;
    }

}