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