Queue.java revision 4fefecee9d4a5d2a4510f516b4015607b19e8d09
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 * 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 */ 39public 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} 92