Queue.java revision adc854b798c1cfe3bfd4c27d68d5cee38ca617da 
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 * This kind of collection provides advanced operations compared to basic
21 * collections, such as insertion, extraction, and inspection.
22 * <p>
23 * Generally, a queue orders its elements by means of first-in-first-out.
24 * However, a priority queue orders its elements according to a comparator
25 * specified or the elements' natural order. Furthermore, a stack orders its
26 * elements last-in-first out.
27 * </p>
28 * <p>
29 * A typical queue does not allow {@code null} to be inserted as its element,
30 * while some implementations such as {@code LinkedList} allow it. But {@code
31 * null} should not be inserted even in these implementations, since the method
32 * {@code poll} returns {@code null} to indicate that there is no element left
33 * in the queue.
34 * </p>
35 * <p>
36 * {@code Queue} does not provide blocking queue methods, which would block
37 * until the operation of the method is allowed. See the
38 * {@link java.util.concurrent.BlockingQueue} interface for information about
39 * blocking queue methods.
40 * </p>
41 *
42 * @since Android 1.0
43 */
44public interface Queue<E> extends Collection<E> {
45
46    /**
47     * Inserts the specified element into the queue provided that the condition
48     * allows such an operation. The method is generally preferable to
49     * {@link Collection#add}, since the latter might throw an exception if the
50     * operation fails.
51     *
52     * @param o
53     *            the specified element to insert into the queue.
54     * @return {@code true} if the operation succeeds and {@code false} if it
55     *         fails.
56     * @since Android 1.0
57     */
58    public boolean offer(E o);
59
60    /**
61     * Gets and removes the element at the head of the queue, or returns {@code
62     * null} if there is no element in the queue.
63     *
64     * @return the element at the head of the queue or {@code null} if there is
65     *         no element in the queue.
66     * @since Android 1.0
67     */
68    public E poll();
69
70    /**
71     * Gets and removes the element at the head of the queue. Throws a
72     * NoSuchElementException if there is no element in the queue.
73     *
74     * @return the element at the head of the queue.
75     * @throws NoSuchElementException
76     *             if there is no element in the queue.
77     * @since Android 1.0
78     */
79    public E remove();
80
81    /**
82     * Gets but does not remove the element at the head of the queue.
83     *
84     * @return the element at the head of the queue or {@code null} if there is
85     *         no element in the queue.
86     * @since Android 1.0
87     */
88    public E peek();
89
90    /**
91     * Gets but does not remove the element at the head of the queue. Throws a
92     * {@code NoSuchElementException} if there is no element in the queue.
93     *
94     * @return the element at the head of the queue.
95     * @throws NoSuchElementException
96     *             if there is no element in the queue.
97     * @since Android 1.0
98     */
99    public E element();
100
101}
102