1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package java.util; 18 19/** 20 * AbstractQueue is an abstract class which implements some of the methods in 21 * {@link Queue}. The provided implementations of {@code add, remove} and 22 * {@code element} are based on {@code offer, poll}, and {@code peek} except 23 * that they throw exceptions to indicate some error instead of returning true 24 * or false. 25 * 26 * @param <E> 27 * the type of the element in the collection. 28 */ 29public abstract class AbstractQueue<E> extends AbstractCollection<E> implements 30 Queue<E> { 31 32 /** 33 * Constructor to be used by subclasses. 34 */ 35 protected AbstractQueue() { 36 super(); 37 } 38 39 /** 40 * Adds an element to the queue. 41 * 42 * @param o 43 * the element to be added to the queue. 44 * @return {@code true} if the operation succeeds, otherwise {@code false}. 45 * @throws IllegalStateException 46 * if the element is not allowed to be added to the queue. 47 */ 48 @Override 49 public boolean add(E o) { 50 if (null == o) { 51 throw new NullPointerException(); 52 } 53 if (offer(o)) { 54 return true; 55 } 56 throw new IllegalStateException(); 57 } 58 59 /** 60 * Adds all the elements of a collection to the queue. If the collection is 61 * the queue itself, then an IllegalArgumentException will be thrown. If 62 * during the process, some runtime exception is thrown, then those elements 63 * in the collection which have already successfully been added will remain 64 * in the queue. The result of the method is undefined if the collection is 65 * modified during the process of the method. 66 * 67 * @param c 68 * the collection to be added to the queue. 69 * @return {@code true} if the operation succeeds, otherwise {@code false}. 70 * @throws NullPointerException 71 * if the collection or any element of it is null. 72 * @throws IllegalArgumentException 73 * If the collection to be added to the queue is the queue 74 * itself. 75 */ 76 @Override 77 public boolean addAll(Collection<? extends E> c) { 78 if (null == c) { 79 throw new NullPointerException(); 80 } 81 if (this == c) { 82 throw new IllegalArgumentException(); 83 } 84 return super.addAll(c); 85 } 86 87 /** 88 * Removes the element at the head of the queue and returns it. 89 * 90 * @return the element at the head of the queue. 91 * @throws NoSuchElementException 92 * if the queue is empty. 93 */ 94 public E remove() { 95 E o = poll(); 96 if (null == o) { 97 throw new NoSuchElementException(); 98 } 99 return o; 100 } 101 102 /** 103 * Returns but does not remove the element at the head of the queue. 104 * 105 * @return the element at the head of the queue. 106 * @throws NoSuchElementException 107 * if the queue is empty. 108 */ 109 public E element() { 110 E o = peek(); 111 if (null == o) { 112 throw new NoSuchElementException(); 113 } 114 return o; 115 } 116 117 /** 118 * Removes all elements of the queue, leaving it empty. 119 */ 120 @Override 121 public void clear() { 122 E o; 123 do { 124 o = poll(); 125 } while (null != o); 126 } 127} 128