001/* 002 * Copyright (C) 2011 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the 010 * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 011 * express or implied. See the License for the specific language governing permissions and 012 * limitations under the License. 013 */ 014 015package com.google.common.collect; 016 017import com.google.common.annotations.Beta; 018import com.google.common.annotations.GwtCompatible; 019import java.util.Comparator; 020import java.util.Iterator; 021import java.util.NavigableSet; 022 023/** 024 * A sorted multiset which forwards all its method calls to another sorted multiset. Subclasses 025 * should override one or more methods to modify the behavior of the backing multiset as desired per 026 * the <a href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>. 027 * 028 * <p><b>Warning:</b> The methods of {@code ForwardingSortedMultiset} forward 029 * <b>indiscriminately</b> to the methods of the delegate. For example, overriding {@link 030 * #add(Object, int)} alone <b>will not</b> change the behavior of {@link #add(Object)}, which can 031 * lead to unexpected behavior. In this case, you should override {@code add(Object)} as well, 032 * either providing your own implementation, or delegating to the provided {@code standardAdd} 033 * method. 034 * 035 * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code 036 * default} methods. Instead, it inherits their default implementations. When those implementations 037 * invoke methods, they invoke methods on the {@code ForwardingSortedMultiset}. 038 * 039 * <p>The {@code standard} methods and any collection views they return are not guaranteed to be 040 * thread-safe, even when all of the methods that they depend on are thread-safe. 041 * 042 * @author Louis Wasserman 043 * @since 15.0 044 */ 045@Beta 046@GwtCompatible(emulated = true) 047public abstract class ForwardingSortedMultiset<E> extends ForwardingMultiset<E> 048 implements SortedMultiset<E> { 049 /** Constructor for use by subclasses. */ 050 protected ForwardingSortedMultiset() {} 051 052 @Override 053 protected abstract SortedMultiset<E> delegate(); 054 055 @Override 056 public NavigableSet<E> elementSet() { 057 return delegate().elementSet(); 058 } 059 060 /** 061 * A sensible implementation of {@link SortedMultiset#elementSet} in terms of the following 062 * methods: {@link SortedMultiset#clear}, {@link SortedMultiset#comparator}, {@link 063 * SortedMultiset#contains}, {@link SortedMultiset#containsAll}, {@link SortedMultiset#count}, 064 * {@link SortedMultiset#firstEntry} {@link SortedMultiset#headMultiset}, {@link 065 * SortedMultiset#isEmpty}, {@link SortedMultiset#lastEntry}, {@link SortedMultiset#subMultiset}, 066 * {@link SortedMultiset#tailMultiset}, the {@code size()} and {@code iterator()} methods of 067 * {@link SortedMultiset#entrySet}, and {@link SortedMultiset#remove(Object, int)}. In many 068 * situations, you may wish to override {@link SortedMultiset#elementSet} to forward to this 069 * implementation or a subclass thereof. 070 * 071 * @since 15.0 072 */ 073 protected class StandardElementSet extends SortedMultisets.NavigableElementSet<E> { 074 /** Constructor for use by subclasses. */ 075 public StandardElementSet() { 076 super(ForwardingSortedMultiset.this); 077 } 078 } 079 080 @Override 081 public Comparator<? super E> comparator() { 082 return delegate().comparator(); 083 } 084 085 @Override 086 public SortedMultiset<E> descendingMultiset() { 087 return delegate().descendingMultiset(); 088 } 089 090 /** 091 * A skeleton implementation of a descending multiset view. Normally, {@link 092 * #descendingMultiset()} will not reflect any changes you make to the behavior of methods such as 093 * {@link #add(Object)} or {@link #pollFirstEntry}. This skeleton implementation correctly 094 * delegates each of its operations to the appropriate methods of this {@code 095 * ForwardingSortedMultiset}. 096 * 097 * <p>In many cases, you may wish to override {@link #descendingMultiset()} to return an instance 098 * of a subclass of {@code StandardDescendingMultiset}. 099 * 100 * @since 15.0 101 */ 102 protected abstract class StandardDescendingMultiset extends DescendingMultiset<E> { 103 /** Constructor for use by subclasses. */ 104 public StandardDescendingMultiset() {} 105 106 @Override 107 SortedMultiset<E> forwardMultiset() { 108 return ForwardingSortedMultiset.this; 109 } 110 } 111 112 @Override 113 public Entry<E> firstEntry() { 114 return delegate().firstEntry(); 115 } 116 117 /** 118 * A sensible definition of {@link #firstEntry()} in terms of {@code entrySet().iterator()}. 119 * 120 * <p>If you override {@link #entrySet()}, you may wish to override {@link #firstEntry()} to 121 * forward to this implementation. 122 */ 123 protected Entry<E> standardFirstEntry() { 124 Iterator<Entry<E>> entryIterator = entrySet().iterator(); 125 if (!entryIterator.hasNext()) { 126 return null; 127 } 128 Entry<E> entry = entryIterator.next(); 129 return Multisets.immutableEntry(entry.getElement(), entry.getCount()); 130 } 131 132 @Override 133 public Entry<E> lastEntry() { 134 return delegate().lastEntry(); 135 } 136 137 /** 138 * A sensible definition of {@link #lastEntry()} in terms of {@code 139 * descendingMultiset().entrySet().iterator()}. 140 * 141 * <p>If you override {@link #descendingMultiset} or {@link #entrySet()}, you may wish to override 142 * {@link #firstEntry()} to forward to this implementation. 143 */ 144 protected Entry<E> standardLastEntry() { 145 Iterator<Entry<E>> entryIterator = descendingMultiset().entrySet().iterator(); 146 if (!entryIterator.hasNext()) { 147 return null; 148 } 149 Entry<E> entry = entryIterator.next(); 150 return Multisets.immutableEntry(entry.getElement(), entry.getCount()); 151 } 152 153 @Override 154 public Entry<E> pollFirstEntry() { 155 return delegate().pollFirstEntry(); 156 } 157 158 /** 159 * A sensible definition of {@link #pollFirstEntry()} in terms of {@code entrySet().iterator()}. 160 * 161 * <p>If you override {@link #entrySet()}, you may wish to override {@link #pollFirstEntry()} to 162 * forward to this implementation. 163 */ 164 protected Entry<E> standardPollFirstEntry() { 165 Iterator<Entry<E>> entryIterator = entrySet().iterator(); 166 if (!entryIterator.hasNext()) { 167 return null; 168 } 169 Entry<E> entry = entryIterator.next(); 170 entry = Multisets.immutableEntry(entry.getElement(), entry.getCount()); 171 entryIterator.remove(); 172 return entry; 173 } 174 175 @Override 176 public Entry<E> pollLastEntry() { 177 return delegate().pollLastEntry(); 178 } 179 180 /** 181 * A sensible definition of {@link #pollLastEntry()} in terms of {@code 182 * descendingMultiset().entrySet().iterator()}. 183 * 184 * <p>If you override {@link #descendingMultiset()} or {@link #entrySet()}, you may wish to 185 * override {@link #pollLastEntry()} to forward to this implementation. 186 */ 187 protected Entry<E> standardPollLastEntry() { 188 Iterator<Entry<E>> entryIterator = descendingMultiset().entrySet().iterator(); 189 if (!entryIterator.hasNext()) { 190 return null; 191 } 192 Entry<E> entry = entryIterator.next(); 193 entry = Multisets.immutableEntry(entry.getElement(), entry.getCount()); 194 entryIterator.remove(); 195 return entry; 196 } 197 198 @Override 199 public SortedMultiset<E> headMultiset(E upperBound, BoundType boundType) { 200 return delegate().headMultiset(upperBound, boundType); 201 } 202 203 @Override 204 public SortedMultiset<E> subMultiset( 205 E lowerBound, BoundType lowerBoundType, E upperBound, BoundType upperBoundType) { 206 return delegate().subMultiset(lowerBound, lowerBoundType, upperBound, upperBoundType); 207 } 208 209 /** 210 * A sensible definition of {@link #subMultiset(Object, BoundType, Object, BoundType)} in terms of 211 * {@link #headMultiset(Object, BoundType) headMultiset} and {@link #tailMultiset(Object, 212 * BoundType) tailMultiset}. 213 * 214 * <p>If you override either of these methods, you may wish to override {@link 215 * #subMultiset(Object, BoundType, Object, BoundType)} to forward to this implementation. 216 */ 217 protected SortedMultiset<E> standardSubMultiset( 218 E lowerBound, BoundType lowerBoundType, E upperBound, BoundType upperBoundType) { 219 return tailMultiset(lowerBound, lowerBoundType).headMultiset(upperBound, upperBoundType); 220 } 221 222 @Override 223 public SortedMultiset<E> tailMultiset(E lowerBound, BoundType boundType) { 224 return delegate().tailMultiset(lowerBound, boundType); 225 } 226}