Deque接口源码解析

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();

}