1 /*
2 * Copyright (C) 2012 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.GwtIncompatible;
21 import java.util.Iterator;
22 import java.util.NavigableSet;
23 import java.util.SortedSet;
24
25 /**
26 * A navigable set which forwards all its method calls to another navigable set. Subclasses should
27 * override one or more methods to modify the behavior of the backing set as desired per the <a
28 * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
29 *
30 * <p><b>Warning:</b> The methods of {@code ForwardingNavigableSet} forward <i>indiscriminately</i>
31 * to the methods of the delegate. For example, overriding {@link #add} alone <i>will not</i> change
32 * the behavior of {@link #addAll}, which can lead to unexpected behavior. In this case, you should
33 * override {@code addAll} as well, either providing your own implementation, or delegating to the
34 * provided {@code standardAddAll} method.
35 *
36 * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
37 * default} methods. Instead, it inherits their default implementations. When those implementations
38 * invoke methods, they invoke methods on the {@code ForwardingNavigableSet}.
39 *
40 * <p>Each of the {@code standard} methods uses the set's comparator (or the natural ordering of the
41 * elements, if there is no comparator) to test element equality. As a result, if the comparator is
42 * not consistent with equals, some of the standard implementations may violate the {@code Set}
43 * contract.
44 *
45 * <p>The {@code standard} methods and the collection views they return are not guaranteed to be
46 * thread-safe, even when all of the methods that they depend on are thread-safe.
47 *
48 * @author Louis Wasserman
49 * @since 12.0
50 */
51 @GwtIncompatible
52 public abstract class ForwardingNavigableSet<E> extends ForwardingSortedSet<E>
53 implements NavigableSet<E> {
54
55 /** Constructor for use by subclasses. */
56 protected ForwardingNavigableSet() {}
57
58 @Override
59 protected abstract NavigableSet<E> delegate();
60
61 @Override
62 public E lower(E e) {
63 return delegate().lower(e);
64 }
65
66 /**
67 * A sensible definition of {@link #lower} in terms of the {@code descendingIterator} method of
68 * {@link #headSet(Object, boolean)}. If you override {@link #headSet(Object, boolean)}, you may
69 * wish to override {@link #lower} to forward to this implementation.
70 */
71 protected E standardLower(E e) {
72 return Iterators.getNext(headSet(e, false).descendingIterator(), null);
73 }
74
75 @Override
76 public E floor(E e) {
77 return delegate().floor(e);
78 }
79
80 /**
81 * A sensible definition of {@link #floor} in terms of the {@code descendingIterator} method of
82 * {@link #headSet(Object, boolean)}. If you override {@link #headSet(Object, boolean)}, you may
83 * wish to override {@link #floor} to forward to this implementation.
84 */
85 protected E standardFloor(E e) {
86 return Iterators.getNext(headSet(e, true).descendingIterator(), null);
87 }
88
89 @Override
90 public E ceiling(E e) {
91 return delegate().ceiling(e);
92 }
93
94 /**
95 * A sensible definition of {@link #ceiling} in terms of the {@code iterator} method of {@link
96 * #tailSet(Object, boolean)}. If you override {@link #tailSet(Object, boolean)}, you may wish to
97 * override {@link #ceiling} to forward to this implementation.
98 */
99 protected E standardCeiling(E e) {
100 return Iterators.getNext(tailSet(e, true).iterator(), null);
101 }
102
103 @Override
104 public E higher(E e) {
105 return delegate().higher(e);
106 }
107
108 /**
109 * A sensible definition of {@link #higher} in terms of the {@code iterator} method of {@link
110 * #tailSet(Object, boolean)}. If you override {@link #tailSet(Object, boolean)}, you may wish to
111 * override {@link #higher} to forward to this implementation.
112 */
113 protected E standardHigher(E e) {
114 return Iterators.getNext(tailSet(e, false).iterator(), null);
115 }
116
117 @Override
118 public E pollFirst() {
119 return delegate().pollFirst();
120 }
121
122 /**
123 * A sensible definition of {@link #pollFirst} in terms of the {@code iterator} method. If you
124 * override {@link #iterator} you may wish to override {@link #pollFirst} to forward to this
125 * implementation.
126 */
127 protected E standardPollFirst() {
128 return Iterators.pollNext(iterator());
129 }
130
131 @Override
132 public E pollLast() {
133 return delegate().pollLast();
134 }
135
136 /**
137 * A sensible definition of {@link #pollLast} in terms of the {@code descendingIterator} method.
138 * If you override {@link #descendingIterator} you may wish to override {@link #pollLast} to
139 * forward to this implementation.
140 */
141 protected E standardPollLast() {
142 return Iterators.pollNext(descendingIterator());
143 }
144
145 protected E standardFirst() {
146 return iterator().next();
147 }
148
149 protected E standardLast() {
150 return descendingIterator().next();
151 }
152
153 @Override
154 public NavigableSet<E> descendingSet() {
155 return delegate().descendingSet();
156 }
157
158 /**
159 * A sensible implementation of {@link NavigableSet#descendingSet} in terms of the other methods
160 * of {@link NavigableSet}, notably including {@link NavigableSet#descendingIterator}.
161 *
162 * <p>In many cases, you may wish to override {@link ForwardingNavigableSet#descendingSet} to
163 * forward to this implementation or a subclass thereof.
164 *
165 * @since 12.0
166 */
167 @Beta
168 protected class StandardDescendingSet extends Sets.DescendingSet<E> {
169 /** Constructor for use by subclasses. */
170 public StandardDescendingSet() {
171 super(ForwardingNavigableSet.this);
172 }
173 }
174
175 @Override
176 public Iterator<E> descendingIterator() {
177 return delegate().descendingIterator();
178 }
179
180 @Override
181 public NavigableSet<E> subSet(
182 E fromElement, boolean fromInclusive, E toElement, boolean toInclusive) {
183 return delegate().subSet(fromElement, fromInclusive, toElement, toInclusive);
184 }
185
186 /**
187 * A sensible definition of {@link #subSet(Object, boolean, Object, boolean)} in terms of the
188 * {@code headSet} and {@code tailSet} methods. In many cases, you may wish to override {@link
189 * #subSet(Object, boolean, Object, boolean)} to forward to this implementation.
190 */
191 @Beta
192 protected NavigableSet<E> standardSubSet(
193 E fromElement, boolean fromInclusive, E toElement, boolean toInclusive) {
194 return tailSet(fromElement, fromInclusive).headSet(toElement, toInclusive);
195 }
196
197 /**
198 * A sensible definition of {@link #subSet(Object, Object)} in terms of the {@link #subSet(Object,
199 * boolean, Object, boolean)} method. If you override {@link #subSet(Object, boolean, Object,
200 * boolean)}, you may wish to override {@link #subSet(Object, Object)} to forward to this
201 * implementation.
202 */
203 @Override
204 protected SortedSet<E> standardSubSet(E fromElement, E toElement) {
205 return subSet(fromElement, true, toElement, false);
206 }
207
208 @Override
209 public NavigableSet<E> headSet(E toElement, boolean inclusive) {
210 return delegate().headSet(toElement, inclusive);
211 }
212
213 /**
214 * A sensible definition of {@link #headSet(Object)} in terms of the {@link #headSet(Object,
215 * boolean)} method. If you override {@link #headSet(Object, boolean)}, you may wish to override
216 * {@link #headSet(Object)} to forward to this implementation.
217 */
218 protected SortedSet<E> standardHeadSet(E toElement) {
219 return headSet(toElement, false);
220 }
221
222 @Override
223 public NavigableSet<E> tailSet(E fromElement, boolean inclusive) {
224 return delegate().tailSet(fromElement, inclusive);
225 }
226
227 /**
228 * A sensible definition of {@link #tailSet(Object)} in terms of the {@link #tailSet(Object,
229 * boolean)} method. If you override {@link #tailSet(Object, boolean)}, you may wish to override
230 * {@link #tailSet(Object)} to forward to this implementation.
231 */
232 protected SortedSet<E> standardTailSet(E fromElement) {
233 return tailSet(fromElement, true);
234 }
235 }