Java Queue源码总结 Queue源码注释翻译和解析中英文对照版

版本
JDK8(JDK1.8)

Queue接口源码重点
1.Queue接口继承Collection接口，自然就拥有Collection接口的特性，且Queue还提供额外的插入、删除和检索操作。这些方法都有两种形式：

• 一种是在操作失败时抛出异常，
• 另一种是返回特殊值（取决于操作，null或false）

插入操作的后一种形式专门设计用于容量受限的Queue实现，在大多数实现中，插入操作不会失败。

2.Queue接口定义了6个方法

	抛出异常	返回特殊值
插入	add(e)	offer(e)
删除	remove()	poll()
检索	element()	peek()

3.队列通常（但不一定）以FIFO（先进先出）的方式对元素进行排序，例外情况包括优先级队列（根据提供的比较器或元素的自然顺序对元素排序）和后进先出（后进先出）队列（或堆栈）。无论使用何种顺序，通过调用remove()或poll()删除的元素总是队列的头。在FIFO队列中，所有新元素都插入到队列的尾部，其他类型的队列可能使用不同的放置规则。每个Queue实现都必须指定其排序属性

4.Queue接口没有定义阻塞队列方法，这在并发编程中很常见，这些等待要取元素出现或空间可用的方法在java.util.concurrent.BlockingQueue 接口中定义，该接口扩展了该接口。

5.代码队列实现通常不允许插入null元素， 尽管某些实现（如LinkedList）允许插入null，即使在允许它的实现中，null也不应该插入到Queue中，因为null也被poll()方法用作特殊的返回值，以指示队列不包含任何元素

Queue接口源码

package java.util;

/**
 * A collection designed for holding elements prior to processing.
 * Besides basic {@link java.util.Collection Collection} operations,
 * queues provide additional insertion, extraction, and inspection
 * operations.  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 Queue}
 * implementations; in most implementations, insert operations cannot
 * fail.
 * 设计用于在处理前保存元素的集合。除了基本的java.util.Collection，
 * 队列还提供额外的插入、删除和检索操作。这些方法都有两种形式：
 * 一种是在操作失败时抛出异常，另一种是返回特殊值（取决于操作，null或false）。
 * 插入操作的后一种形式专门设计用于容量受限的Queue实现；
 * 在大多数实现中，插入操作不会失败。
 * 
 *
 * <table BORDER CELLPADDING=3 CELLSPACING=1>
 * <caption>Summary of Queue methods</caption>
 *  <tr>
 *    <td></td>
 *    <td ALIGN=CENTER><em>Throws exception</em></td>
 *    <td ALIGN=CENTER><em>Returns special value</em></td>
 *  </tr>
 *  <tr>
 *    <td><b>Insert</b></td>
 *    <td>{@link Queue#add add(e)}</td>
 *    <td>{@link Queue#offer offer(e)}</td>
 *  </tr>
 *  <tr>
 *    <td><b>Remove</b></td>
 *    <td>{@link Queue#remove remove()}</td>
 *    <td>{@link Queue#poll poll()}</td>
 *  </tr>
 *  <tr>
 *    <td><b>Examine</b></td>
 *    <td>{@link Queue#element element()}</td>
 *    <td>{@link Queue#peek peek()}</td>
 *  </tr>
 * </table>
 * 
 * 
                        Summary of Queue methods
            Throws exception	                Returns special value
    Insert	{@link Queue#add add(e)}	        {@link Queue#offer offer(e)}
    Remove	{@link Queue#remove remove()}	    {@link Queue#poll poll()}
    Examine	{@link Queue#element element()}	    {@link Queue#peek peek()}

                            队列方法概述
            抛出异常        	                 返回特殊值
    插入	{@link Queue#add add(e)}	        {@link Queue#offer offer(e)}
    删除	{@link Queue#remove remove()}	    {@link Queue#poll poll()}
    检索	{@link Queue#element element()}	    {@link Queue#peek peek()}
 * 
 * 
 * 
 *
 * <p>Queues typically, but do not necessarily, order elements in a
 * FIFO (first-in-first-out) manner.  Among the exceptions are
 * priority queues, which order elements according to a supplied
 * comparator, or the elements' natural ordering, and LIFO queues (or
 * stacks) which order the elements LIFO (last-in-first-out).
 * 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()}.  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.
 * 队列通常（但不一定）以FIFO（先进先出）的方式对元素进行排序。
 * 例外情况包括优先级队列（根据提供的比较器或元素的自然顺序对元素排序）和
 * 后进先出（后进先出）队列（或堆栈）。
 * 无论使用何种顺序，队列的头是通过调用remove()或#poll()删除的元素。
 * 在FIFO队列中，所有新元素都插入到队列的尾部。
 * 其他类型的队列可能使用不同的放置规则。每个Queue实现都必须指定其排序属性
 * 
 *
 * <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.  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()方法尽可能插入一个元素，否则返回false。
 * 这与java.util.Collection#add Collection.add方法不同，
 * 后者只能通过抛出未经检查的异常来添加元素。
 * offer()方法是为在正常而非异常情况下使用而设计的，例如，在固定容量（或“有界”）队列中。
 *
 * <p>The {@link #remove()} and {@link #poll()} methods remove and
 * return the head of the queue.
 * Exactly which element is removed from the queue is a
 * function of the queue's ordering policy, which differs from
 * implementation to implementation. 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()方法只有在队列为空时的行为不同：
 * remove()方法引发异常，poll()方法返回null
 * 
 * 
 *
 * <p>The {@link #element()} and {@link #peek()} methods return, but do
 * not remove, the head of the queue.
 * element()和peek()方法返回但不删除队列头
 * 
 *
 * <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.
 * Queue接口没有定义阻塞队列方法，这在并发编程中很常见。
 * 这些等待元素出现或空间可用的方法在java.util.concurrent.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.
 * 代码队列实现通常不允许插入null元素，
 * 尽管某些实现（如LinkedList）不禁止插入null。
 * 即使在允许它的实现中，null也不应该插入到Queue中，
 * 因为null也被poll方法用作特殊的返回值，以指示队列不包含任何元素。
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * <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实现通常不定义方法equals和hashCode的基于元素的版本，
 * 而是从类Object继承基于标识的版本，因为对于具有相同元素但不同排序属性的队列，
 * 基于元素的相等性并不总是定义良好的。
 * 
 *
 *
 * <p>This interface is a member of the
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 * Java Collections Framework</a>.
 * 此接口是Java集合框架的成员。
 *
 * @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> the type of elements held in this collection
 */
public interface Queue<E> extends Collection<E> {
    /**
     * Inserts the specified element into this queue if it is possible to do so
     * immediately without violating capacity restrictions, returning
     * {@code true} upon success and throwing an {@code IllegalStateException}
     * if no space is currently available. 
     * 如果可以在不违反容量限制的情况下立即将指定元素插入此队列，则在成功时返回true，
     * 如果当前没有可用空间，则抛出IllegalStateException。
     * 
     *
     * @param e the element to add
     * @return {@code true} (as specified by {@link Collection#add})
     * @throws IllegalStateException if the element cannot be added at this
     *         time due to capacity restrictions 如果由于容量限制，此时无法添加元素
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this queue 如果指定元素的类与此队列不兼容
     * @throws NullPointerException if the specified element is null and
     *         this queue does not permit null elements  如果指定的元素为null，并且此队列不允许null元素
     * @throws IllegalArgumentException if some property of this element
     *         prevents it from being added to this queue 如果此元素的某些属性阻止将其添加到此队列
     */
    boolean add(E e);

    /**
     * Inserts the specified element into this queue if it is possible to do
     * so immediately without violating capacity restrictions.
     * When using a capacity-restricted queue, this method is generally
     * preferable to {@link #add}, which can fail to insert an element only
     * by throwing an exception.
     * 如果可以在不违反容量限制的情况下立即将指定元素插入此队列中。
     * 当使用容量受限队列时，此方法通常比add()更可取，add()在插入元素失败时会抛出异常。
     * 
     * 
     *
     * @param e the element to add
     * @return {@code true} if the element was added to this queue, else
     *         {@code false} 如果元素已添加到此队列，则为true，否则为false
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this queue
     * @throws NullPointerException if the specified element is null and
     *         this queue does not permit null elements
     * @throws IllegalArgumentException if some property of this element
     *         prevents it from being added to this queue
     */
    boolean offer(E e);

    /**
     * Retrieves and removes the head of this queue.  This method differs
     * from {@link #poll poll} only in that it throws an exception if this
     * queue is empty.
     * 检索并删除此队列的头。此方法与poll()的不同之处在于，如果此队列为空，则会抛出异常。
     * 
     * 
     *
     * @return the head of this queue 这个队列的头
     * @throws NoSuchElementException if this queue is empty 如果此队列为空
     */
    E remove();

    /**
     * Retrieves and removes the head of this queue,
     * or returns {@code null} if this queue is empty.
     * 检索并删除此队列的头，如果此队列为空，则返回null。
     *
     * @return the head of this queue, or {@code null} if this queue is empty 
     * 此队列的头，如果此队列为空，则为null
     */
    E poll();

    /**
     * Retrieves, but does not remove, the head of this queue.  This method
     * differs from {@link #peek peek} only in that it throws an exception
     * if this queue is empty.
     * 检索但不删除此队列的头。此方法与peek()的不同之处在于，如果此队列为空，则会抛出异常。
     *
     * @return the head of this queue
     * @throws NoSuchElementException if this queue is empty
     */
    E element();

    /**
     * Retrieves, but does not remove, the head of this queue,
     * or returns {@code null} if this queue is empty.
     * 检索但不删除此队列的头，如果此队列为空，则返回null
     *
     * @return the head of this queue, or {@code null} if this queue is empty
     * 返回此队列的头，如果此队列为空，则为null
     */
    E peek();
}