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