001/* 002 * Copyright (C) 2012 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.Beta; 020import com.google.common.annotations.GwtIncompatible; 021import java.util.Iterator; 022import java.util.NavigableSet; 023import java.util.SortedSet; 024 025/** 026 * A navigable set which forwards all its method calls to another navigable set. Subclasses should 027 * override one or more methods to modify the behavior of the backing set 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 ForwardingNavigableSet} forward <i>indiscriminately</i> 031 * to the methods of the delegate. For example, overriding {@link #add} alone <i>will not</i> change 032 * the behavior of {@link #addAll}, which can lead to unexpected behavior. In this case, you should 033 * override {@code addAll} as well, either providing your own implementation, or delegating to the 034 * provided {@code standardAddAll} method. 035 * 036 * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code 037 * default} methods. Instead, it inherits their default implementations. When those implementations 038 * invoke methods, they invoke methods on the {@code ForwardingNavigableSet}. 039 * 040 * <p>Each of the {@code standard} methods uses the set's comparator (or the natural ordering of the 041 * elements, if there is no comparator) to test element equality. As a result, if the comparator is 042 * not consistent with equals, some of the standard implementations may violate the {@code Set} 043 * contract. 044 * 045 * <p>The {@code standard} methods and the collection views they return are not guaranteed to be 046 * thread-safe, even when all of the methods that they depend on are thread-safe. 047 * 048 * @author Louis Wasserman 049 * @since 12.0 050 */ 051@GwtIncompatible 052public abstract class ForwardingNavigableSet<E> extends ForwardingSortedSet<E> 053 implements NavigableSet<E> { 054 055 /** Constructor for use by subclasses. */ 056 protected ForwardingNavigableSet() {} 057 058 @Override 059 protected abstract NavigableSet<E> delegate(); 060 061 @Override 062 public E lower(E e) { 063 return delegate().lower(e); 064 } 065 066 /** 067 * A sensible definition of {@link #lower} in terms of the {@code descendingIterator} method of 068 * {@link #headSet(Object, boolean)}. If you override {@link #headSet(Object, boolean)}, you may 069 * wish to override {@link #lower} to forward to this implementation. 070 */ 071 protected E standardLower(E e) { 072 return Iterators.getNext(headSet(e, false).descendingIterator(), null); 073 } 074 075 @Override 076 public E floor(E e) { 077 return delegate().floor(e); 078 } 079 080 /** 081 * A sensible definition of {@link #floor} in terms of the {@code descendingIterator} method of 082 * {@link #headSet(Object, boolean)}. If you override {@link #headSet(Object, boolean)}, you may 083 * wish to override {@link #floor} to forward to this implementation. 084 */ 085 protected E standardFloor(E e) { 086 return Iterators.getNext(headSet(e, true).descendingIterator(), null); 087 } 088 089 @Override 090 public E ceiling(E e) { 091 return delegate().ceiling(e); 092 } 093 094 /** 095 * A sensible definition of {@link #ceiling} in terms of the {@code iterator} method of {@link 096 * #tailSet(Object, boolean)}. If you override {@link #tailSet(Object, boolean)}, you may wish to 097 * override {@link #ceiling} to forward to this implementation. 098 */ 099 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}