001: /* Licensed to the Apache Software Foundation (ASF) under one or more
002: * contributor license agreements. See the NOTICE file distributed with
003: * this work for additional information regarding copyright ownership.
004: * The ASF licenses this file to You under the Apache License, Version 2.0
005: * (the "License"); you may not use this file except in compliance with
006: * the License. You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package java.util;
018:
019: /**
020: *
021: * An abstract class which gives out skeletal implementations for some methods
022: * in Queue which include add, remove, and element that are based on offer,
023: * poll, and peek except that they throw exception to indicate the occurrence of
024: * some error instead of the return value of false or null.
025: *
026: * @param <E>
027: * the type of the element in the collection.
028: */
029: public abstract class AbstractQueue<E> extends AbstractCollection<E>
030: implements Queue<E> {
031:
032: /**
033: * Constructor for the sub classes.
034: *
035: */
036: protected AbstractQueue() {
037: super ();
038: }
039:
040: /**
041: * Adds an element to the queue.
042: *
043: * @param o the element added to the queue.
044: * @return true if the operation succeeds.
045: * @throws NullPointerException if the element is null.
046: * @throws IllegalStateException if the element is not allowed to be added
047: * to the queue.
048: */
049: @Override
050: public boolean add(E o) {
051: if (null == o) {
052: throw new NullPointerException();
053: }
054: if (offer(o)) {
055: return true;
056: }
057: throw new IllegalStateException();
058: }
059:
060: /**
061: * Adds all the elements of a collection to the queue. If the collection is
062: * the queue itself, then an IllegalArgumentException will be thrown out. If
063: * during the process, some runtime exception is thrown out, then part of
064: * the elements in the collection that have successfully added will remain
065: * in the queue.
066: *
067: * The result of the method is undefined if the collection is modified
068: * during the process of the method.
069: *
070: * @param c the collection to be added to the queue.
071: * @return true if the operation succeeds.
072: * @throws NullPointerException if the collection or any element of it is
073: * null.
074: * @throws IllegalArgumentException If the collection to be added to the
075: * queue is the queue itself.
076: */
077: @Override
078: public boolean addAll(Collection<? extends E> c) {
079: if (null == c) {
080: throw new NullPointerException();
081: }
082: if (this == c) {
083: throw new IllegalArgumentException();
084: }
085: return super .addAll(c);
086: }
087:
088: /**
089: * Gets and removes the element in the head of the queue.
090: *
091: * @return the element in the head of the queue.
092: * @throws NoSuchElementException if the queue is empty.
093: */
094: public E remove() {
095: E o = poll();
096: if (null == o) {
097: throw new NoSuchElementException();
098: }
099: return o;
100: }
101:
102: /**
103: * Gets but not removes the element in the head of the queue.
104: *
105: * @return the element in the head of the queue.
106: * @throws NoSuchElementException if the queue is empty.
107: */
108: public E element() {
109: E o = peek();
110: if (null == o) {
111: throw new NoSuchElementException();
112: }
113: return o;
114: }
115:
116: /**
117: * Removes all elements of the queue.
118: */
119: @Override
120: public void clear() {
121: E o;
122: do {
123: o = poll();
124: } while (null != o);
125: }
126: }
|