001 /*
002 * Copyright (C) 2009 Google Inc.
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
017 package com.google.common.collect;
018
019 import static com.google.common.base.Preconditions.checkNotNull;
020
021 import com.google.common.annotations.GwtCompatible;
022
023 import java.util.Comparator;
024 import java.util.List;
025 import java.util.Map;
026
027 import javax.annotation.Nullable;
028
029 /**
030 * An immutable {@link Table} with reliable user-specified iteration order.
031 * Does not permit null keys or values.
032 *
033 * <p><b>Note</b>: Although this class is not final, it cannot be subclassed as
034 * it has no public or protected constructors. Thus, instances of this class are
035 * guaranteed to be immutable.
036 *
037 * <p>See the Guava User Guide article on <a href=
038 * "http://code.google.com/p/guava-libraries/wiki/ImmutableCollectionsExplained">
039 * immutable collections</a>.
040 *
041 * @author gak@google.com (Gregory Kick)
042 * @since 11.0
043 */
044 @GwtCompatible
045 // TODO(gak): make serializable
046 public abstract class ImmutableTable<R, C, V> implements Table<R, C, V> {
047 /** Returns an empty immutable table. */
048 @SuppressWarnings("unchecked")
049 public static final <R, C, V> ImmutableTable<R, C, V> of() {
050 return (ImmutableTable<R, C, V>) EmptyImmutableTable.INSTANCE;
051 }
052
053 /** Returns an immutable table containing a single cell. */
054 public static final <R, C, V> ImmutableTable<R, C, V> of(R rowKey,
055 C columnKey, V value) {
056 return new SingletonImmutableTable<R, C, V>(rowKey, columnKey, value);
057 }
058
059 /**
060 * Returns an immutable copy of the provided table.
061 *
062 * <p>The {@link Table#cellSet()} iteration order of the provided table
063 * determines the iteration ordering of all views in the returned table. Note
064 * that some views of the original table and the copied table may have
065 * different iteration orders. For more control over the ordering, create a
066 * {@link Builder} and call {@link Builder#orderRowsBy},
067 * {@link Builder#orderColumnsBy}, and {@link Builder#putAll}
068 *
069 * <p>Despite the method name, this method attempts to avoid actually copying
070 * the data when it is safe to do so. The exact circumstances under which a
071 * copy will or will not be performed are undocumented and subject to change.
072 */
073 public static final <R, C, V> ImmutableTable<R, C, V> copyOf(
074 Table<? extends R, ? extends C, ? extends V> table) {
075 if (table instanceof ImmutableTable<?, ?, ?>) {
076 @SuppressWarnings("unchecked")
077 ImmutableTable<R, C, V> parameterizedTable
078 = (ImmutableTable<R, C, V>) table;
079 return parameterizedTable;
080 } else {
081 int size = table.size();
082 switch (size) {
083 case 0:
084 return of();
085 case 1:
086 Cell<? extends R, ? extends C, ? extends V> onlyCell
087 = Iterables.getOnlyElement(table.cellSet());
088 return ImmutableTable.<R, C, V>of(onlyCell.getRowKey(),
089 onlyCell.getColumnKey(), onlyCell.getValue());
090 default:
091 ImmutableSet.Builder<Cell<R, C, V>> cellSetBuilder
092 = ImmutableSet.builder();
093 for (Cell<? extends R, ? extends C, ? extends V> cell :
094 table.cellSet()) {
095 /*
096 * Must cast to be able to create a Cell<R, C, V> rather than a
097 * Cell<? extends R, ? extends C, ? extends V>
098 */
099 cellSetBuilder.add(cellOf((R) cell.getRowKey(),
100 (C) cell.getColumnKey(), (V) cell.getValue()));
101 }
102 return RegularImmutableTable.forCells(cellSetBuilder.build());
103 }
104 }
105 }
106
107 /**
108 * Returns a new builder. The generated builder is equivalent to the builder
109 * created by the {@link Builder#ImmutableTable.Builder()} constructor.
110 */
111 public static final <R, C, V> Builder<R, C, V> builder() {
112 return new Builder<R, C, V>();
113 }
114
115 /**
116 * Verifies that {@code rowKey}, {@code columnKey} and {@code value} are
117 * non-null, and returns a new entry with those values.
118 */
119 static <R, C, V> Cell<R, C, V> cellOf(R rowKey, C columnKey, V value) {
120 return Tables.immutableCell(checkNotNull(rowKey), checkNotNull(columnKey),
121 checkNotNull(value));
122 }
123
124 /**
125 * A builder for creating immutable table instances, especially {@code public
126 * static final} tables ("constant tables"). Example: <pre> {@code
127 *
128 * static final ImmutableTable<Integer, Character, String> SPREADSHEET =
129 * new ImmutableTable.Builder<Integer, Character, String>()
130 * .put(1, 'A', "foo")
131 * .put(1, 'B', "bar")
132 * .put(2, 'A', "baz")
133 * .build();}</pre>
134 *
135 * <p>By default, the order in which cells are added to the builder determines
136 * the iteration ordering of all views in the returned table, with {@link
137 * #putAll} following the {@link Table#cellSet()} iteration order. However, if
138 * {@link #orderRowsBy} or {@link #orderColumnsBy} is called, the views are
139 * sorted by the supplied comparators.
140 *
141 * For empty or single-cell immutable tables, {@link #of()} and
142 * {@link #of(Object, Object, Object)} are even more convenient.
143 *
144 * <p>Builder instances can be reused - it is safe to call {@link #build}
145 * multiple times to build multiple tables in series. Each table is a superset
146 * of the tables created before it.
147 *
148 * @since 11.0
149 */
150 public static final class Builder<R, C, V> {
151 private final List<Cell<R, C, V>> cells = Lists.newArrayList();
152 private Comparator<? super R> rowComparator;
153 private Comparator<? super C> columnComparator;
154
155 /**
156 * Creates a new builder. The returned builder is equivalent to the builder
157 * generated by {@link ImmutableTable#builder}.
158 */
159 public Builder() {}
160
161 /**
162 * Specifies the ordering of the generated table's rows.
163 */
164 public Builder<R, C, V> orderRowsBy(Comparator<? super R> rowComparator) {
165 this.rowComparator = checkNotNull(rowComparator);
166 return this;
167 }
168
169 /**
170 * Specifies the ordering of the generated table's columns.
171 */
172 public Builder<R, C, V> orderColumnsBy(
173 Comparator<? super C> columnComparator) {
174 this.columnComparator = checkNotNull(columnComparator);
175 return this;
176 }
177
178 /**
179 * Associates the ({@code rowKey}, {@code columnKey}) pair with {@code
180 * value} in the built table. Duplicate key pairs are not allowed and will
181 * cause {@link #build} to fail.
182 */
183 public Builder<R, C, V> put(R rowKey, C columnKey, V value) {
184 cells.add(cellOf(rowKey, columnKey, value));
185 return this;
186 }
187
188 /**
189 * Adds the given {@code cell} to the table, making it immutable if
190 * necessary. Duplicate key pairs are not allowed and will cause {@link
191 * #build} to fail.
192 */
193 public Builder<R, C, V> put(
194 Cell<? extends R, ? extends C, ? extends V> cell) {
195 if (cell instanceof Tables.ImmutableCell) {
196 checkNotNull(cell.getRowKey());
197 checkNotNull(cell.getColumnKey());
198 checkNotNull(cell.getValue());
199 @SuppressWarnings("unchecked") // all supported methods are covariant
200 Cell<R, C, V> immutableCell = (Cell<R, C, V>) cell;
201 cells.add(immutableCell);
202 } else {
203 put(cell.getRowKey(), cell.getColumnKey(), cell.getValue());
204 }
205 return this;
206 }
207
208 /**
209 * Associates all of the given table's keys and values in the built table.
210 * Duplicate row key column key pairs are not allowed, and will cause
211 * {@link #build} to fail.
212 *
213 * @throws NullPointerException if any key or value in {@code table} is null
214 */
215 public Builder<R, C, V> putAll(
216 Table<? extends R, ? extends C, ? extends V> table) {
217 for (Cell<? extends R, ? extends C, ? extends V> cell : table.cellSet()) {
218 put(cell);
219 }
220 return this;
221 }
222
223 /**
224 * Returns a newly-created immutable table.
225 *
226 * @throws IllegalArgumentException if duplicate key pairs were added
227 */
228 public ImmutableTable<R, C, V> build() {
229 int size = cells.size();
230 switch (size) {
231 case 0:
232 return of();
233 case 1:
234 return new SingletonImmutableTable<R, C, V>(
235 Iterables.getOnlyElement(cells));
236 default:
237 return RegularImmutableTable.forCells(
238 cells, rowComparator, columnComparator);
239 }
240 }
241 }
242
243 ImmutableTable() {}
244
245 @Override public abstract ImmutableSet<Cell<R, C, V>> cellSet();
246
247 /**
248 * {@inheritDoc}
249 *
250 * @throws NullPointerException if {@code columnKey} is {@code null}
251 */
252 @Override public abstract ImmutableMap<R, V> column(C columnKey);
253
254 @Override public abstract ImmutableSet<C> columnKeySet();
255
256 /**
257 * {@inheritDoc}
258 *
259 * <p>The value {@code Map<R, V>}s in the returned map are
260 * {@link ImmutableMap}s as well.
261 */
262 @Override public abstract ImmutableMap<C, Map<R, V>> columnMap();
263
264 /**
265 * {@inheritDoc}
266 *
267 * @throws NullPointerException if {@code rowKey} is {@code null}
268 */
269 @Override public abstract ImmutableMap<C, V> row(R rowKey);
270
271 @Override public abstract ImmutableSet<R> rowKeySet();
272
273 /**
274 * {@inheritDoc}
275 *
276 * <p>The value {@code Map<C, V>}s in the returned map are
277 * {@link ImmutableMap}s as well.
278 */
279 @Override public abstract ImmutableMap<R, Map<C, V>> rowMap();
280
281 /**
282 * Guaranteed to throw an exception and leave the table unmodified.
283 *
284 * @throws UnsupportedOperationException always
285 */
286 @Override public final void clear() {
287 throw new UnsupportedOperationException();
288 }
289
290 /**
291 * Guaranteed to throw an exception and leave the table unmodified.
292 *
293 * @throws UnsupportedOperationException always
294 */
295 @Override public final V put(R rowKey, C columnKey, V value) {
296 throw new UnsupportedOperationException();
297 }
298
299 /**
300 * Guaranteed to throw an exception and leave the table unmodified.
301 *
302 * @throws UnsupportedOperationException always
303 */
304 @Override public final void putAll(
305 Table<? extends R, ? extends C, ? extends V> table) {
306 throw new UnsupportedOperationException();
307 }
308
309 /**
310 * Guaranteed to throw an exception and leave the table unmodified.
311 *
312 * @throws UnsupportedOperationException always
313 */
314 @Override public final V remove(Object rowKey, Object columnKey) {
315 throw new UnsupportedOperationException();
316 }
317
318 @Override public boolean equals(@Nullable Object obj) {
319 if (obj == this) {
320 return true;
321 } else if (obj instanceof Table<?, ?, ?>) {
322 Table<?, ?, ?> that = (Table<?, ?, ?>) obj;
323 return this.cellSet().equals(that.cellSet());
324 } else {
325 return false;
326 }
327 }
328
329 @Override public int hashCode() {
330 return cellSet().hashCode();
331 }
332
333 @Override public String toString() {
334 return rowMap().toString();
335 }
336 }