001 /*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * 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 com.google.common.collect;
018
019 import com.google.common.annotations.Beta;
020 import com.google.common.annotations.GwtCompatible;
021
022 import java.util.NoSuchElementException;
023 import java.util.Queue;
024
025 /**
026 * A queue which forwards all its method calls to another queue. Subclasses
027 * should override one or more methods to modify the behavior of the backing
028 * queue as desired per the <a
029 * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
030 *
031 * <p><b>Warning:</b> The methods of {@code ForwardingQueue} forward
032 * <b>indiscriminately</b> to the methods of the delegate. For example,
033 * overriding {@link #add} alone <b>will not</b> change the behavior of {@link
034 * #offer} which can lead to unexpected behavior. In this case, you should
035 * override {@code offer} as well, either providing your own implementation, or
036 * delegating to the provided {@code standardOffer} method.
037 *
038 * <p>The {@code standard} methods are not guaranteed to be thread-safe, even
039 * when all of the methods that they depend on are thread-safe.
040 *
041 * @author Mike Bostock
042 * @author Louis Wasserman
043 * @since 2 (imported from Google Collections Library)
044 */
045 @GwtCompatible
046 public abstract class ForwardingQueue<E> extends ForwardingCollection<E>
047 implements Queue<E> {
048
049 /** Constructor for use by subclasses. */
050 protected ForwardingQueue() {}
051
052 @Override protected abstract Queue<E> delegate();
053
054 @Override
055 public boolean offer(E o) {
056 return delegate().offer(o);
057 }
058
059 @Override
060 public E poll() {
061 return delegate().poll();
062 }
063
064 @Override
065 public E remove() {
066 return delegate().remove();
067 }
068
069 @Override
070 public E peek() {
071 return delegate().peek();
072 }
073
074 @Override
075 public E element() {
076 return delegate().element();
077 }
078
079 /**
080 * A sensible definition of {@link #offer} in terms of {@link #add}. If you
081 * override {@link #add}, you may wish to override {@link #offer} to forward
082 * to this implementation.
083 *
084 * @since 7
085 */
086 @Beta protected boolean standardOffer(E e) {
087 try {
088 return add(e);
089 } catch (IllegalStateException caught) {
090 return false;
091 }
092 }
093
094 /**
095 * A sensible definition of {@link #peek} in terms of {@link #element}. If you
096 * override {@link #element}, you may wish to override {@link #peek} to
097 * forward to this implementation.
098 *
099 * @since 7
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
115 */
116 @Beta protected E standardPoll() {
117 try {
118 return remove();
119 } catch (NoSuchElementException caught) {
120 return null;
121 }
122 }
123 }