Deque接口源码解析

Deque
双向队列
队头：可以插入可以删除
队尾：可以插入可以删除
继承Queue接口

源码如下：

package java.util;


public interface Deque<E> extends Queue<E> {
    /**
     * 队头插入元素 
     *
     * @throws 队列满了添加元素，抛出：IllegalStateException 
     * @throws 类型不兼容，抛出：ClassCastException 
     * @throws null队列不允许null，抛出：NullPointerException 
     * @throws 其他操作限制了插入元素，抛出：IllegalArgumentException 
     */
    void addFirst(E e);

    /**
     * 队列尾部插入元素
     *
     * @param e the element to 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 deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
    void addLast(E e);

    /**
     * 队列头部插入元素
     *
     * @param e the element to add
     * @return <tt>true</tt> if the element was added to this deque, else
     *         <tt>false</tt>
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
    boolean offerFirst(E e);

    /**
     * 队列尾部插入元素
     *
     * @param e the element to add
     * @return <tt>true</tt> if the element was added to this deque, else
     *         <tt>false</tt>
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
    boolean offerLast(E e);

    /**
     * 队列头部删除元素
     *
     * @return the head of this deque
     * @throws NoSuchElementException if this deque is empty
     */
    E removeFirst();

    /**
     * 队列尾部插入元素
     *
     * @return the tail of this deque
     * @throws null时候，抛出：NoSuchElementException 
     */
    E removeLast();

    /**
     * 获取队头元素，并删除该元素
     *
     * @return the head of this deque, or <tt>null</tt> if this deque is empty
     */
    E pollFirst();

    /**
     * 获取队尾元素，并删除该元素
     * @return the tail of this deque, or <tt>null</tt> if this deque is empty
     */
    E pollLast();

    /**
     * 查看队头元素
     *
     * @return the head of this deque
     * @throws NoSuchElementException if this deque is empty
     */
    E getFirst();

    /**
     * 查看队尾元素
     *
     * @return the tail of this deque
     * @throws NoSuchElementException if this deque is empty
     */
    E getLast();

    /**
     * 查看队头元素
     *
     * @return the head of this deque, or <tt>null</tt> if this deque is empty
     */
    E peekFirst();

    /**
     *查看队尾元素
     *
     * @return the tail of this deque, or <tt>null</tt> if this deque is empty
     */
    E peekLast();

    /**
     * 删除第一个当前元素
     * @param o element to be removed from this deque, if present
     * @return <tt>true</tt> if an element was removed as a result of this call
     * @throws ClassCastException if the class of the specified element
     *         is incompatible with this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     */
    boolean removeFirstOccurrence(Object o);

    /**
     * 删除最后一个当前元素
     * @param o element to be removed from this deque, if present
     * @return <tt>true</tt> if an element was removed as a result of this call
     * @throws ClassCastException if the class of the specified element
     *         is incompatible with this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     */
    boolean removeLastOccurrence(Object o);

    // *** Queue methods 队列的方法***

    /**
     * 队尾加入元素
     *
     * @param e the element to add
     * @return <tt>true</tt> (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 deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
    boolean add(E e);

    /**
     * 队尾加入元素
     *
     * <p>This method is equivalent to {@link #offerLast}.
     *
     * @param e the element to add
     * @return <tt>true</tt> if the element was added to this deque, else
     *         <tt>false</tt>
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
    boolean offer(E e);

    /**
     * 获取队头元素，并删除该元素
     *
     * @return the head of the queue represented by this deque
     * @throws NoSuchElementException if this deque is empty
     */
    E remove();

    /**
     * 获取队头元素，并删除该元素
     *
     * @return the first element of this deque, or <tt>null</tt> if
     *         this deque is empty
     */
    E poll();

    /**
     * 查看队头元素
     *
     * @return the head of the queue represented by this deque
     * @throws NoSuchElementException if this deque is empty
     */
    E element();

    /**
     * 查看队头元素
     *
     * @return the head of the queue represented by this deque, or
     *         <tt>null</tt> if this deque is empty
     */
    E peek();


    // *** Stack methods 栈方法 ***

    /**
     * 入栈
     *
     * @param e the element to push
     * @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 deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this deque
     */
    void push(E e);

    /**
     * 出栈 
     *
     * @return the element at the front of this deque (which is the top
     *         of the stack represented by this deque)
     * @throws NoSuchElementException if this deque is empty
     */
    E pop();


    // *** Collection methods 集合方法 ***

    /**
     * 删除第一个元素 
     * @param o element to be removed from this deque, if present
     * @return <tt>true</tt> if an element was removed as a result of this call
     * @throws ClassCastException if the class of the specified element
     *         is incompatible with this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     */
    boolean remove(Object o);

    /**
     * 是否包含元素 o 
     * @param o element whose presence in this deque is to be tested
     * @return <tt>true</tt> if this deque contains the specified element
     * @throws ClassCastException if the type of the specified element
     *         is incompatible with this deque
     * @throws NullPointerException if the specified element is null and this
     *         deque does not permit null elements
     */
    boolean contains(Object o);

    /**
     * 队列包含元素数量
     * @return the number of elements in this deque
     */
    public int size();

    /**
     * 获取迭代器
     * @return an iterator over the elements in this deque in proper sequence
     */
    Iterator<E> iterator();

    /**
     * 获取逆向的迭代器：尾->头迭代
     *
     * @return an iterator over the elements in this deque in reverse
     * sequence
     */
    Iterator<E> descendingIterator();

}