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