libcore/luni/src/main/java/java/util/Queue.java

   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  */
  17 package 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  * A typical queue does not allow {@code null} to be inserted as its element,
  29  * while some implementations such as {@code LinkedList} allow it. But {@code
  30  * null} should not be inserted even in these implementations, since the method
  31  * {@code poll} returns {@code null} to indicate that there is no element left
  32  * in the queue.
  33  * <p>
  34  * {@code Queue} does not provide blocking queue methods, which would block
  35  * until the operation of the method is allowed. See the
  36  * {@link java.util.concurrent.BlockingQueue} interface for information about
  37  * blocking queue methods.
  38  */
  39 public interface Queue<E> extends Collection<E> {
  40
  41     /**
  42      * Inserts the specified element into the queue provided that the condition
  43      * allows such an operation. The method is generally preferable to
  44      * {@link Collection#add}, since the latter might throw an exception if the
  45      * operation fails.
  46      *
  47      * @param o
  48      *            the specified element to insert into the queue.
  49      * @return {@code true} if the operation succeeds and {@code false} if it
  50      *         fails.
  51      */
  52     public boolean offer(E o);
  53
  54     /**
  55      * Gets and removes the element at the head of the queue, or returns {@code
  56      * null} if there is no element in the queue.
  57      *
  58      * @return the element at the head of the queue or {@code null} if there is
  59      *         no element in the queue.
  60      */
  61     public E poll();
  62
  63     /**
  64      * Gets and removes the element at the head of the queue. Throws a
  65      * NoSuchElementException if there is no element in the queue.
  66      *
  67      * @return the element at the head of the queue.
  68      * @throws NoSuchElementException
  69      *             if there is no element in the queue.
  70      */
  71     public E remove();
  72
  73     /**
  74      * Gets but does not remove the element at the head of the queue.
  75      *
  76      * @return the element at the head of the queue or {@code null} if there is
  77      *         no element in the queue.
  78      */
  79     public E peek();
  80
  81     /**
  82      * Gets but does not remove the element at the head of the queue. Throws a
  83      * {@code NoSuchElementException} if there is no element in the queue.
  84      *
  85      * @return the element at the head of the queue.
  86      * @throws NoSuchElementException
  87      *             if there is no element in the queue.
  88      */
  89     public E element();
  90
  91 }