关于java:源码学习Java-本地队列-javautilDeque

1、接口定义

反对在头尾两端插入和移除元素的线性汇合（双端队列：Double Ended Queue，Deque，读音：英[dek]|美[dɛk]）。大多数 Deque 实现对于它们可能蕴含的元素数量没有固定的限度，不过这个接口对容量设限以及没有固定容量限度的那些 Deque 实现都反对。

该接口定义了拜访 Deque 两端元素的办法，办法被提供用于 插入 、 提取 和检索 操作。这些操作方法都以两种模式存在：一种在操作失败时抛出异样，另一种是返回一个非凡值（依据操作的不同，能够是 null 或 false）。后一种模式的插入操作是专门为应用容量设限的 Deque 实现而设计的；在大多数实现中，插入操作不会失败。

这个接口继承了 Queue 接口。当应用 Deque 作为 Queue 队列时，会产生 FIFO（先进先出）行为：元素被增加到 Deque 的尾部，而后从头部移除。从 Queue 接口继承的办法准确地等同于 Deque 办法，如下表所示：

Deque 也可用作 LIFO（后进先出）Stack 堆栈。应该优先应用这个接口，而不是历史遗留的 java.util.Stack 类。当一个 Deque 被用作堆栈时，元素从该 Deque 的头部被压入和弹出。Stack 办法与 Deque 办法齐全等价，如下表所示：

请留神，当 Deque 被用作 Queue 队列或 Stack 堆栈时，peek() 办法同样无效；在这两种状况下，元素都是从 Deque 的头部提取的。

这个接口还提供了两个办法来移除外部元素，removeFirstOccurrence() 和 removeLastOccurrence()。

与 java.util.List 接口不同，该接口不反对对元素的索引拜访。

尽管 Deque 实现并不严格要求禁止插入 null 元素，但强烈建议这样做。任何容许 null 元素的 Deque 实现的使用者都强烈建议不要利用插入 null 元素的能力。这是因为 null 会被各种办法用作非凡的返回值，以表明 Deque 为空。

Deque 实现通常不定义 equals() 和 hashCode() 的基于元素版本的办法，而是从类 Object 继承基于标识版本的办法。

java.util.Deque 继承于 java.util.Queue 接口，接口继承关系如下图所示：

2、办法申明

1）void addFirst(E e);

• 在不违反容量限度的状况下立刻将指定的元素插入到该 Deque 的头部中，当应用容量设限的 Deque 时，通常最好应用 offerFirst() 办法；
• 如果此时因为容量限度（没有可用空间）而不能增加元素，则抛出 java.lang.IllegalStateException；
• 如果指定元素的类阻止将其增加到此队列中，则抛出 java.lang.ClassCastException；
• 如果指定的元素为 null 且该队列不容许 null 元素，则抛出 java.lang.NullPointerException；
• 如果此元素的某些属性阻止将其增加到此队列中，则抛出 java.lang.IllegalArgumentException。

2）void addLast(E e);

• 在不违反容量限度的状况下立刻将指定的元素插入到该 Deque 的尾部中，当应用容量设限的 Deque 时，通常最好应用 offerLast() 办法；
• 如果此时因为容量限度（没有可用空间）而不能增加元素，则抛出 java.lang.IllegalStateException；
• 如果指定元素的类阻止将其增加到此队列中，则抛出 java.lang.ClassCastException；
• 如果指定的元素为 null 且该队列不容许 null 元素，则抛出 java.lang.NullPointerException；
• 如果此元素的某些属性阻止将其增加到此队列中，则抛出 java.lang.IllegalArgumentException。

3）boolean offerFirst(E e);

• 将指定的元素插入到 Deque 的头部，除非它违反容量限度，胜利时返回 true，否则返回 false。当应用容量设限的队列时，这个办法通常比 addFirst() 更适宜应用，因为在不能增加元素时，addFirst() 办法只能抛出异样；
• 如果指定元素的类阻止将其增加到此队列中，则抛出 java.lang.ClassCastException；
• 如果指定的元素为 null 且该队列不容许 null 元素，则抛出 java.lang.NullPointerException；
• 如果此元素的某些属性阻止将其增加到此队列中，则抛出 java.lang.IllegalArgumentException。

4）boolean offerLast(E e);

• 将指定的元素插入到 Deque 的尾部，除非它违反容量限度，胜利时返回 true，否则返回 false。当应用容量设限的队列时，这个办法通常比 addLast() 更适宜应用，因为在不能增加元素时，addLast() 办法只能抛出异样；
• 如果指定元素的类阻止将其增加到此队列中，则抛出 java.lang.ClassCastException；
• 如果指定的元素为 null 且该队列不容许 null 元素，则抛出 java.lang.NullPointerException；
• 如果此元素的某些属性阻止将其增加到此队列中，则抛出 java.lang.IllegalArgumentException。

5）E removeFirst();

• 检索并移除该 Deque 的第一个元素（头部元素）。此办法与 pollFirst() 的不同之处在于：当该 Deque 为空时，则抛出异样；
• 如果该 Deque 为空，则抛出 java.util.NoSuchElementException。

6）E removeLast();

• 检索并移除该 Deque 的最初一个元素（尾部元素）。此办法与 pollLast() 的不同之处在于：当该 Deque 为空时，则抛出异样；
• 如果该 Deque 为空，则抛出 java.util.NoSuchElementException。

7）E pollFirst();

• 检索并移除该 Deque 的第一个元素（头部元素），如果该 Deque 为空，则返回 null。

8）E pollLast();

• 检索并移除该 Deque 的最初一个元素（尾部元素），如果该 Deque 为空，则返回 null。

9）E getFirst();

• 检索（但并不移除）该 Deque 的第一个元素（头部元素）。此办法与 peekFirst() 的不同之处在于：当该 Deque 为空时，则抛出异样；
• 如果该 Deque 为空，则抛出 java.util.NoSuchElementException。

10）E getLast();

• 检索（但并不移除）该 Deque 的最初一个元素（尾部元素）。此办法与 peekLast() 的不同之处在于：当该 Deque 为空时，则抛出异样；
• 如果该 Deque 为空，则抛出 java.util.NoSuchElementException。

11）E peekFirst();

• 检索（但并不移除）该 Deque 的第一个元素（头部元素），如果该 Deque 为空，则返回 null。

12）E peekLast();

• 检索（但并不移除）该 Deque 的最初一个元素（尾部元素），如果该 Deque 为空，则返回 null。

13）boolean removeFirstOccurrence(Object o);

• 从 Deque 中移除指定元素的第一个匹配项。如果该 Deque 中不蕴含该元素，则它不会有所扭转。更正式地说，即移除第一个满足 (o==null ? e==null : o.equals(e)) 表达式的元素 e（如果存在这样的元素的话）。如果该 Deque 蕴含指定的元素则移除它并返回 true；
• 如果指定元素的类型与 Deque 不兼容，则抛出 java.lang.ClassCastException（可选）；
• 如果指定的元素是 null，而这个 Deque 是不容许 null 元素的，则抛出 java.lang.NullPointerException（可选）。

注：“可选”指具体的 Deque 实现可依据本人的实现目标而抉择适合的策略，或返回此异样，或返回胜利。

14）boolean removeLastOccurrence(Object o);

• 从 Deque 中移除指定元素的最初一个匹配项。如果该 Deque 中不蕴含该元素，则它不会有所扭转。更正式地说，即移除最初一个满足 (o==null ? e==null : o.equals(e)) 表达式的元素 e（如果存在这样的元素的话）。如果该 Deque 蕴含指定的元素则移除它并返回 true；
• 如果指定元素的类型与 Deque 不兼容，则抛出 java.lang.ClassCastException（可选）；
• 如果指定的元素是 null，而这个 Deque 是不容许 null 元素的，则抛出 java.lang.NullPointerException（可选）。

— 以下为 Queue 队列办法 —

15）boolean add(E e);

• 如果能够在不违反容量限度的状况下立刻将指定的元素插入到该 Deque 所示意的 Queue 队列中（换句话说，插入到该 Deque 的尾部），则在插入胜利时返回 true（如 Collection.add() 所指定的），当应用容量设限的 Deque 时，通常最好应用 offer() 办法。此办法与 addLast() 办法等效；
• 如果此时因为容量限度（没有可用空间）而不能增加元素，则抛出 java.lang.IllegalStateException；
• 如果指定元素的类阻止将其增加到此队列中，则抛出 java.lang.ClassCastException；
• 如果指定的元素为 null 且该队列不容许 null 元素，则抛出 java.lang.NullPointerException；
• 如果此元素的某些属性阻止将其增加到此队列中，则抛出 java.lang.IllegalArgumentException。

16）boolean offer(E e);

• 如果能够在不违反容量限度的状况下立刻将指定的元素插入到该 Deque 所示意的 Queue 队列中（换句话说，插入到该 Deque 的尾部），则在插入胜利时返回 true，否则返回 false，当应用容量设限的 Deque 时，这个办法通常比 add() 更适宜应用，因为在因容量限度（没有可用空间）而不能增加元素时，add() 办法只能抛出异样。此办法与 offerLast() 办法等效；
• 如果指定元素的类阻止将其增加到此队列中，则抛出 java.lang.ClassCastException；
• 如果指定的元素为 null 且该队列不容许 null 元素，则抛出 java.lang.NullPointerException；
• 如果此元素的某些属性阻止将其增加到此队列中，则抛出 java.lang.IllegalArgumentException。

17）E remove();

• 检索并移除此 Deque 所示意的 Queue 队列的头部元素（换句话说，移除该 Deque 的第一个元素），此办法与 poll() 办法的不同之处在于：如果队列为空，则抛出异样。此办法与 removeFirst() 办法等效；
• 如果队列为空，则抛出 java.util.NoSuchElementException。

18）E poll();

• 检索并移除此 Deque 所示意的 Queue 队列的头部元素（换句话说，移除该 Deque 的第一个元素），如果队列为空，返回 null。此办法与 pollFirst() 办法等效。

19）E element();

• 检索（但并不移除）此 Deque 所示意的 Queue 队列的头部元素（换句话说，检索该 Deque 的第一个元素），此办法与 peek() 办法的不同之处在于：如果队列为空，则抛出异样。此办法与 getFirst() 办法等效；
• 如果队列为空，则抛出 java.util.NoSuchElementException。

20）E peek();

• 检索（但并不移除）此 Deque 所示意的 Queue 队列的头部元素（换句话说，检索该 Deque 的第一个元素），如果队列为空，返回 null。此办法与 peekFirst() 办法等效。

— 以下为 Stack 堆栈办法 —

21）void push(E e);

• 在不违反容量限度的状况下立刻将一个元素压入到该 Deque 所示意的 Stack 堆栈中（换句话说，压入到该 Deque 的头部）。此办法与 addFirst() 办法等效；
• 如果此时因为容量限度（没有可用空间）而不能增加元素，则抛出 java.lang.IllegalStateException；
• 如果指定元素的类阻止将其增加到此堆栈中，则抛出 java.lang.ClassCastException；
• 如果指定的元素为 null 且该堆栈不容许 null 元素，则抛出 java.lang.NullPointerException；
• 如果此元素的某些属性阻止将其增加到此堆栈中，则抛出 java.lang.IllegalArgumentException。

22）E pop();

• 从这个 Deque 所示意的 Stack 堆栈中弹出一个元素。换句话说，移除并返回该 Deque 的第一个元素。此办法与 removeFirst() 办法等效；
• 如果堆栈为空，则抛出 java.util.NoSuchElementException。

— 以下为 Collection 汇合办法 —

23）boolean remove(Object o);

• 从 Deque 中移除指定元素的第一个匹配项。如果该 Deque 中不蕴含该元素，则它不会有所扭转。更正式地说，即移除第一个满足 (o==null ? e==null : o.equals(e)) 表达式的元素 e（如果存在这样的元素的话）。如果该 Deque 蕴含指定的元素则移除它并返回 true。此办法与 removeFirstOccurrence(Object o) 办法等效；
• 如果指定元素的类型与 Deque 不兼容，则抛出 java.lang.ClassCastException（可选）；
• 如果指定的元素是 null，而这个 Deque 是不容许 null 元素的，则抛出 java.lang.NullPointerException（可选）。

24）boolean contains(Object o);

• 如果 Deque 蕴含指定的元素时返回 true。更正式地说，当且仅当这个 Deque 至多蕴含一个满足 (o==null ? e==null : o.equals(e)) 表达式的元素 e 时返回 true；
• 如果指定元素的类型与 Deque 不兼容，则抛出 java.lang.ClassCastException（可选）；
• 如果指定的元素是 null，而这个 Deque 是不容许 null 元素的，则抛出 java.lang.NullPointerException（可选）。

25）public int size();

• 返回 Deque 中蕴含的元素的数量。

26）Iterator<E> iterator();

• 依照程序返回 Deque 中所有元素的迭代器，元素将按从头到尾的程序返回。

27）Iterator<E> descendingIterator();

• 以反向程序返回该 Deque 中所有元素的迭代器，元素将按从尾到头的程序返回。