Queue.java revision fdb2704414a9ed92394ada0d1395e4db86889465 
1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17package java.util;
18
19/**
20 * A kind of collection provides advanced operations than other basic
21 * collections, such as insertion, extraction, and inspection.
22 *
23 * Generally, a queue orders its elements by means of first-in-first-out. While
24 * priority queue orders its elements according to a comparator specified or the
25 * elements' natural order. Furthermore, a stack orders its elements
26 * last-in-first out.
27 *
28 * A typical queue does not allow null to be inserted as its element, while some
29 * implementations such as LinkedList allow it. But null should not be inserted
30 * even in these implementations, since method poll return null to indicate that
31 * there is no element left in the queue.
32 *
33 * Queue does not provide blocking queue methods, which will block until the
34 * operation of the method is allowed. BlockingQueue interface defines such
35 * methods.
36 */
37public interface Queue<E> extends Collection<E> {
38
39    /**
40     * Inserts the specified element into the queue provided that the condition
41     * allows such an operation. The method is generally preferable to the
42     * collection.add(E), since the latter might throw an exception if the
43     * operation fails.
44     *
45     * @param o
46     *            the specified element to insert into the queue.
47     * @return true if the operation succeeds and false if it fails.
48     */
49    public boolean offer(E o);
50
51    /**
52     * Gets and removes the element in the head of the queue, or returns null if
53     * there is no element in the queue.
54     *
55     * @return the element in the head of the queue or null if there is no
56     *         element in the queue.
57     */
58    public E poll();
59
60    /**
61     * Gets and removes the element in the head of the queue. Throws a
62     * NoSuchElementException if there is no element in the queue.
63     *
64     * @return the element in the head of the queue.
65     * @throws NoSuchElementException
66     *             if there is no element in the queue.
67     */
68    public E remove();
69
70    /**
71     * Gets but not removes the element in the head of the queue, or throws
72     * exception if there is no element in the queue.
73     *
74     * @return the element in the head of the queue or null if there is no
75     *         element in the queue.
76     */
77    public E peek();
78
79    /**
80     * Gets but not removes the element in the head of the queue. Throws a
81     * NoSuchElementException if there is no element in the queue.
82     *
83     * @return the element in the head of the queue.
84     * @throws NoSuchElementException
85     *             if there is no element in the queue.
86     */
87    public E element();
88
89}
90