1 /* 2 * Copyright (C) 2007 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * 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 17 package com.google.common.collect; 18 19 import com.google.common.annotations.Beta; 20 import com.google.common.annotations.GwtCompatible; 21 22 import java.util.NoSuchElementException; 23 import java.util.Queue; 24 25 /** 26 * A queue which forwards all its method calls to another queue. Subclasses 27 * should override one or more methods to modify the behavior of the backing 28 * queue as desired per the <a 29 * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>. 30 * 31 * <p><b>Warning:</b> The methods of {@code ForwardingQueue} forward 32 * <b>indiscriminately</b> to the methods of the delegate. For example, 33 * overriding {@link #add} alone <b>will not</b> change the behavior of {@link 34 * #offer} which can lead to unexpected behavior. In this case, you should 35 * override {@code offer} as well, either providing your own implementation, or 36 * delegating to the provided {@code standardOffer} method. 37 * 38 * <p>The {@code standard} methods are not guaranteed to be thread-safe, even 39 * when all of the methods that they depend on are thread-safe. 40 * 41 * @author Mike Bostock 42 * @author Louis Wasserman 43 * @since 2.0 (imported from Google Collections Library) 44 */ 45 @GwtCompatible 46 public abstract class ForwardingQueue<E> extends ForwardingCollection<E> 47 implements Queue<E> { 48 49 /** Constructor for use by subclasses. */ 50 protected ForwardingQueue() {} 51 52 @Override protected abstract Queue<E> delegate(); 53 54 @Override 55 public boolean offer(E o) { 56 return delegate().offer(o); 57 } 58 59 @Override 60 public E poll() { 61 return delegate().poll(); 62 } 63 64 @Override 65 public E remove() { 66 return delegate().remove(); 67 } 68 69 @Override 70 public E peek() { 71 return delegate().peek(); 72 } 73 74 @Override 75 public E element() { 76 return delegate().element(); 77 } 78 79 /** 80 * A sensible definition of {@link #offer} in terms of {@link #add}. If you 81 * override {@link #add}, you may wish to override {@link #offer} to forward 82 * to this implementation. 83 * 84 * @since 7.0 85 */ 86 @Beta protected boolean standardOffer(E e) { 87 try { 88 return add(e); 89 } catch (IllegalStateException caught) { 90 return false; 91 } 92 } 93 94 /** 95 * A sensible definition of {@link #peek} in terms of {@link #element}. If you 96 * override {@link #element}, you may wish to override {@link #peek} to 97 * forward to this implementation. 98 * 99 * @since 7.0 100 */ 101 @Beta protected E standardPeek() { 102 try { 103 return element(); 104 } catch (NoSuchElementException caught) { 105 return null; 106 } 107 } 108 109 /** 110 * A sensible definition of {@link #poll} in terms of {@link #remove}. If you 111 * override {@link #remove}, you may wish to override {@link #poll} to forward 112 * to this implementation. 113 * 114 * @since 7.0 115 */ 116 @Beta protected E standardPoll() { 117 try { 118 return remove(); 119 } catch (NoSuchElementException caught) { 120 return null; 121 } 122 } 123 } 124
