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.Beta;
20 import com.google.common.annotations.GwtCompatible;
21 import java.util.Comparator;
22 import java.util.Iterator;
23 import java.util.NoSuchElementException;
24 import java.util.SortedSet;
25 import org.checkerframework.checker.nullness.qual.Nullable;
26
27 /**
28 * A sorted set which forwards all its method calls to another sorted set. Subclasses should
29 * override one or more methods to modify the behavior of the backing sorted set as desired per the
30 * <a href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
31 *
32 * <p><b>Warning:</b> The methods of {@code ForwardingSortedSet} forward <i>indiscriminately</i> to
33 * the methods of the delegate. For example, overriding {@link #add} alone <i>will not</i> change
34 * the behavior of {@link #addAll}, which can lead to unexpected behavior. In this case, you should
35 * override {@code addAll} as well, either providing your own implementation, or delegating to the
36 * provided {@code standardAddAll} method.
37 *
38 * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
39 * default} methods. Instead, it inherits their default implementations. When those implementations
40 * invoke methods, they invoke methods on the {@code ForwardingSortedSet}.
41 *
42 * <p>Each of the {@code standard} methods, where appropriate, uses the set's comparator (or the
43 * natural ordering of the elements, if there is no comparator) to test element equality. As a
44 * result, if the comparator is not consistent with equals, some of the standard implementations may
45 * violate the {@code Set} contract.
46 *
47 * <p>The {@code standard} methods and the collection views they return are not guaranteed to be
48 * thread-safe, even when all of the methods that they depend on are thread-safe.
49 *
50 * @author Mike Bostock
51 * @author Louis Wasserman
52 * @since 2.0
53 */
54 @GwtCompatible
55 public abstract class ForwardingSortedSet<E> extends ForwardingSet<E> implements SortedSet<E> {
56
57 /** Constructor for use by subclasses. */
58 protected ForwardingSortedSet() {}
59
60 @Override
61 protected abstract SortedSet<E> delegate();
62
63 @Override
64 public Comparator<? super E> comparator() {
65 return delegate().comparator();
66 }
67
68 @Override
69 public E first() {
70 return delegate().first();
71 }
72
73 @Override
74 public SortedSet<E> headSet(E toElement) {
75 return delegate().headSet(toElement);
76 }
77
78 @Override
79 public E last() {
80 return delegate().last();
81 }
82
83 @Override
84 public SortedSet<E> subSet(E fromElement, E toElement) {
85 return delegate().subSet(fromElement, toElement);
86 }
87
88 @Override
89 public SortedSet<E> tailSet(E fromElement) {
90 return delegate().tailSet(fromElement);
91 }
92
93 // unsafe, but worst case is a CCE is thrown, which callers will be expecting
94 @SuppressWarnings("unchecked")
95 private int unsafeCompare(@Nullable Object o1, @Nullable Object o2) {
96 Comparator<? super E> comparator = comparator();
97 return (comparator == null)
98 ? ((Comparable<Object>) o1).compareTo(o2)
99 : ((Comparator<Object>) comparator).compare(o1, o2);
100 }
101
102 /**
103 * A sensible definition of {@link #contains} in terms of the {@code first()} method of {@link
104 * #tailSet}. If you override {@link #tailSet}, you may wish to override {@link #contains} to
105 * forward to this implementation.
106 *
107 * @since 7.0
108 */
109 @Override
110 @Beta
111 protected boolean standardContains(@Nullable Object object) {
112 try {
113 // any ClassCastExceptions are caught
114 @SuppressWarnings("unchecked")
115 SortedSet<Object> self = (SortedSet<Object>) this;
116 Object ceiling = self.tailSet(object).first();
117 return unsafeCompare(ceiling, object) == 0;
118 } catch (ClassCastException | NoSuchElementException | NullPointerException e) {
119 return false;
120 }
121 }
122
123 /**
124 * A sensible definition of {@link #remove} in terms of the {@code iterator()} method of {@link
125 * #tailSet}. If you override {@link #tailSet}, you may wish to override {@link #remove} to
126 * forward to this implementation.
127 *
128 * @since 7.0
129 */
130 @Override
131 @Beta
132 protected boolean standardRemove(@Nullable Object object) {
133 try {
134 // any ClassCastExceptions are caught
135 @SuppressWarnings("unchecked")
136 SortedSet<Object> self = (SortedSet<Object>) this;
137 Iterator<Object> iterator = self.tailSet(object).iterator();
138 if (iterator.hasNext()) {
139 Object ceiling = iterator.next();
140 if (unsafeCompare(ceiling, object) == 0) {
141 iterator.remove();
142 return true;
143 }
144 }
145 } catch (ClassCastException | NullPointerException e) {
146 return false;
147 }
148 return false;
149 }
150
151 /**
152 * A sensible default implementation of {@link #subSet(Object, Object)} in terms of {@link
153 * #headSet(Object)} and {@link #tailSet(Object)}. In some situations, you may wish to override
154 * {@link #subSet(Object, Object)} to forward to this implementation.
155 *
156 * @since 7.0
157 */
158 @Beta
159 protected SortedSet<E> standardSubSet(E fromElement, E toElement) {
160 return tailSet(fromElement).headSet(toElement);
161 }
162 }