【java接口系列】 Queue源码分析

java interface Queue源码分析

由来

Java 8中的接口Queue是Java集合框架中的一部分，用于表示队列数据结构。队列是一种先进先出（FIFO）的数据结构，其中元素按照插入顺序排列，并且只能在队列的一端插入元素，在另一端删除元素。

Queue接口的设计和实现旨在提供一组标准的方法来操作队列。它定义了一些常见的队列操作，例如插入元素、删除元素、检查队列是否为空以及获取队列的大小等。

Queue接口继承自Collection接口，并在其基础上添加了队列特有的方法。这些方法包括：

• add(element)：向队列尾部插入指定元素。
• offer(element)：向队列尾部插入指定元素，并返回插入成功与否的结果。
• remove()：移除并返回队列头部的元素。
• poll()：移除并返回队列头部的元素，如果队列为空则返回null。
• element()：返回队列头部的元素，但不移除。
• peek()：返回队列头部的元素，如果队列为空则返回null。

Queue接口的实现类可以选择使用不同的数据结构来实现队列的功能，如LinkedList、PriorityQueue等。这取决于具体的需求和性能要求。

总之，Java 8中的Queue接口提供了一种标准化的队列数据结构定义，并提供了一组常用的方法来操作队列。它的设计和实现使得我们可以方便地使用和管理队列数据。

中文源码

/**
 * 一个用于在处理之前保存元素的集合。
 * 除了基本的 {@link java.util.Collection Collection} 操作外，
 * 队列还提供了额外的插入、提取和检查操作。每个方法都有两种形式：一种在操作失败时抛出异常，另一种返回一个特殊值（根据操作而定，可能是 {@code null} 或 {@code false}）。
 * 后一种插入操作的形式专门设计用于容量受限的 {@code Queue} 实现；在大多数实现中，插入操作不能失败。
 *
 * <table BORDER CELLPADDING=3 CELLSPACING=1>
 * <caption>Queue 方法摘要</caption>
 *  <tr>
 *    <td></td>
 *    <td ALIGN=CENTER><em>抛出异常</em></td>
 *    <td ALIGN=CENTER><em>返回特殊值</em></td>
 *  </tr>
 *  <tr>
 *    <td><b>插入</b></td>
 *    <td>{@link Queue#add add(e)}</td>
 *    <td>{@link Queue#offer offer(e)}</td>
 *  </tr>
 *  <tr>
 *    <td><b>移除</b></td>
 *    <td>{@link Queue#remove remove()}</td>
 *    <td>{@link Queue#poll poll()}</td>
 *  </tr>
 *  <tr>
 *    <td><b>查看</b></td>
 *    <td>{@link Queue#element element()}</td>
 *    <td>{@link Queue#peek peek()}</td>
 *  </tr>
 * </table>
 *
 * <p>队列通常以先进先出（FIFO）的方式对元素进行排序，但并非必须如此。
 * 例外情况包括优先级队列，它根据提供的比较器或元素的自然顺序对元素进行排序，
 * 以及后进先出（LIFO）队列（或堆栈），它按照后进先出的顺序排列元素。
 * 无论使用哪种排序方式，队列的 <em>头部</em> 是通过调用 {@link #remove()} 或 {@link #poll()} 方法将被移除的元素。
 * 在 FIFO 队列中，所有新元素都插入到队列的 <em>尾部</em>。其他类型的队列可能使用不同的放置规则。
 * 每个 {@code Queue} 实现都必须指定其排序属性。
 *
 * <p>{@link #offer offer} 方法在可能的情况下插入一个元素，否则返回 {@code false}。
 * 这与 {@link java.util.Collection#add Collection.add} 方法不同，后者只能通过抛出未检查的异常来失败地添加元素。
 * {@code offer} 方法设计用于当失败是正常情况而不是异常情况时使用，例如在固定容量（或 "有界"）队列中。
 *
 * <p>{@link #remove()} 和 {@link #poll()} 方法会移除并返回队列的头部。
 * 从队列中移除的确切元素取决于队列的排序策略，这在不同的实现中有所不同。
 * {@code remove()} 和 {@code poll()} 方法的区别仅在于当队列为空时的行为：
 * {@code remove()} 方法会抛出异常，而 {@code poll()} 方法会返回 {@code null}。
 *
 * <p>{@link #element()} 和 {@link #peek()} 方法会返回队列的头部，但不会将其移除。
 *
 * <p>{@code Queue} 接口不定义<i>阻塞队列方法</i>，这些方法在并发编程中很常见。
 * 这些方法等待元素出现或空间可用，并在 {@link java.util.concurrent.BlockingQueue} 接口中定义，该接口扩展了此接口。
 *
 * <p>{@code Queue} 实现通常不允许插入 {@code null} 元素，尽管某些实现（如 {@link LinkedList}）不禁止插入 {@code null}。
 * 即使在允许的实现中，也不应将 {@code null} 插入到 {@code Queue} 中，因为 {@code null} 也被 {@code poll} 方法用作特殊的返回值，表示队列不包含任何元素。
 *
 * <p>{@code Queue} 实现通常不定义基于元素的 {@code equals} 和 {@code hashCode} 方法版本，
 * 而是从 {@code Object} 类继承基于标识的版本，因为基于元素的相等性对于具有相同元素但不同排序属性的队列并不总是明确定义的。
 *
 * <p>此接口是<a href="{@docRoot}/../technotes/guides/collections/index.html">
 * Java Collections Framework</a> 的成员。
 *
 * @see java.util.Collection
 * @see LinkedList
 * @see PriorityQueue
 * @see java.util.concurrent.LinkedBlockingQueue
 * @see java.util.concurrent.BlockingQueue
 * @see java.util.concurrent.ArrayBlockingQueue
 * @see java.util.concurrent.LinkedBlockingQueue
 * @see java.util.concurrent.PriorityBlockingQueue
 * @since 1.5
 * @author Doug Lea
 * @param <E> 此集合中所持有元素的类型
 */
public interface Queue<E> extends Collection<E> {
    /**
     * 如果可以立即在不违反容量限制的情况下将指定的元素插入到此队列中，
     * 则将其插入此队列，如果当前没有可用空间，则抛出 {@code IllegalStateException}。
     *
     * @param e 要添加的元素
     * @return {@code true}（根据 {@link Collection#add} 指定）
     * @throws IllegalStateException 如果由于容量限制而无法在此时添加元素
     * @throws ClassCastException 如果指定元素的类阻止将其添加到此队列中
     * @throws NullPointerException 如果指定元素为 null 并且此队列不允许 null 元素
     * @throws IllegalArgumentException 如果此元素的某些属性阻止将其添加到此队列中
     */
    boolean add(E e);

    /**
     * 如果可能的话，立即将指定元素插入此队列，而不违反容量限制。
     * 当使用容量受限的队列时，该方法通常优于 {@link #add} 方法，后者只能通过抛出异常来插入元素失败。
     *
     * @param e 要添加的元素
     * @return 如果元素已成功添加到此队列，则为 {@code true}，否则为 {@code false}
     * @throws ClassCastException 如果指定元素的类阻止将其添加到此队列中
     * @throws NullPointerException 如果指定元素为 null 并且此队列不允许 null 元素
     * @throws IllegalArgumentException 如果此元素的某些属性阻止将其添加到此队列中
     */
    boolean offer(E e);

    /**
     * 检索并删除此队列的头部。此方法与 {@link #poll poll} 方法的区别仅在于当此队列为空时会抛出异常。
     *
     * @return 此队列的头部
     * @throws NoSuchElementException 如果此队列为空
     */
    E remove();

    /**
     * 检索并删除此队列的头部，如果此队列为空，则返回 {@code null}。
     *
     * @return 此队列的头部，如果此队列为空，则为 {@code null}
     */
    E poll();

    /**
     * 检索但不删除此队列的头部。此方法与 {@link #peek peek} 方法的区别仅在于当此队列为空时会抛出异常。
     *
     * @return 此队列的头部
     * @throws NoSuchElementException 如果此队列为空
     */
    E element();

    /**
     * 检索但不删除此队列的头部，如果此队列为空，则返回 {@code null}。
     *
     * @return 此队列的头部，如果此队列为空，则为 {@code null}
     */
    E peek();
}