    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.0 (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.0
    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.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    }