1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
/* * @(#)AbstractQueue.java 1.11 06/04/21 * * Copyright 2006 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package java.util; /** * This class provides skeletal implementations of some {@link Queue} * operations. The implementations in this class are appropriate when * the base implementation does <em>not</em> allow <tt>null</tt> * elements. Methods {@link #add add}, {@link #remove remove}, and * {@link #element element} are based on {@link #offer offer}, {@link * #poll poll}, and {@link #peek peek}, respectively but throw * exceptions instead of indicating failure via <tt>false</tt> or * <tt>null</tt> returns. * * <p> A <tt>Queue</tt> implementation that extends this class must * minimally define a method {@link Queue#offer} which does not permit * insertion of <tt>null</tt> elements, along with methods {@link * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, and a * {@link Collection#iterator} supporting {@link * Iterator#remove}. Typically, additional methods will be overridden * as well. If these requirements cannot be met, consider instead * subclassing {@link AbstractCollection}. * * <p>This class is a member of the * <a href="{@docRoot}/../technotes/guides/collections/index.html"> * Java Collections Framework</a>. * * @since 1.5 * @author Doug Lea * @param <E> the type of elements held in this collection */ public abstract class AbstractQueue<E> extends AbstractCollection<E> implements Queue<E> { /** * Constructor for use by subclasses. */ protected AbstractQueue() { } /** * Inserts the specified element into this queue if it is possible to do so * immediately without violating capacity restrictions, returning * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt> * if no space is currently available. * * <p>This implementation returns <tt>true</tt> if <tt>offer</tt> succeeds, * else throws an <tt>IllegalStateException</tt>. * * @param e the element to add * @return <tt>true</tt> (as specified by {@link Collection#add}) * @throws IllegalStateException if the element cannot be added at this * time due to capacity restrictions * @throws ClassCastException if the class of the specified element * prevents it from being added to this queue * @throws NullPointerException if the specified element is null and * this queue does not permit null elements * @throws IllegalArgumentException if some property of this element * prevents it from being added to this queue */ public boolean add(E e) { if (offer(e)) return true; else throw new IllegalStateException("Queue full"); } /** * Retrieves and removes the head of this queue. This method differs * from {@link #poll poll} only in that it throws an exception if this * queue is empty. * * <p>This implementation returns the result of <tt>poll</tt> * unless the queue is empty. * * @return the head of this queue * @throws NoSuchElementException if this queue is empty */ public E remove() { E x = poll(); if (x != null) return x; else throw new NoSuchElementException(); } /** * Retrieves, but does not remove, the head of this queue. This method * differs from {@link #peek peek} only in that it throws an exception if * this queue is empty. * * <p>This implementation returns the result of <tt>peek</tt> * unless the queue is empty. * * @return the head of this queue * @throws NoSuchElementException if this queue is empty */ public E element() { E x = peek(); if (x != null) return x; else throw new NoSuchElementException(); } /** * Removes all of the elements from this queue. * The queue will be empty after this call returns. * * <p>This implementation repeatedly invokes {@link #poll poll} until it * returns <tt>null</tt>. */ public void clear() { while (poll() != null) ; } /** * Adds all of the elements in the specified collection to this * queue. Attempts to addAll of a queue to itself result in * <tt>IllegalArgumentException</tt>. Further, the behavior of * this operation is undefined if the specified collection is * modified while the operation is in progress. * * <p>This implementation iterates over the specified collection, * and adds each element returned by the iterator to this * queue, in turn. A runtime exception encountered while * trying to add an element (including, in particular, a * <tt>null</tt> element) may result in only some of the elements * having been successfully added when the associated exception is * thrown. * * @param c collection containing elements to be added to this queue * @return <tt>true</tt> if this queue changed as a result of the call * @throws ClassCastException if the class of an element of the specified * collection prevents it from being added to this queue * @throws NullPointerException if the specified collection contains a * null element and this queue does not permit null elements, * or if the specified collection is null * @throws IllegalArgumentException if some property of an element of the * specified collection prevents it from being added to this * queue, or if the specified collection is this queue * @throws IllegalStateException if not all the elements can be added at * this time due to insertion restrictions * @see #add(Object) */ public boolean addAll(Collection<? extends E> c) { if (c == null) throw new NullPointerException(); if (c == this) throw new IllegalArgumentException(); boolean modified = false; Iterator<? extends E> e = c.iterator(); while (e.hasNext()) { if (add(e.next())) modified = true; } return modified; } }