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