View Javadoc
1   /*
2    * Copyright (C) 2008 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.GwtCompatible;
20  import com.google.common.base.Objects;
21  import com.google.errorprone.annotations.CanIgnoreReturnValue;
22  import com.google.errorprone.annotations.CompatibleWith;
23  import java.util.Collection;
24  import java.util.Map;
25  import java.util.Set;
26  import javax.annotation.Nullable;
27  
28  /**
29   * A collection that associates an ordered pair of keys, called a row key and a
30   * column key, with a single value. A table may be sparse, with only a small
31   * fraction of row key / column key pairs possessing a corresponding value.
32   *
33   * <p>The mappings corresponding to a given row key may be viewed as a {@link
34   * Map} whose keys are the columns. The reverse is also available, associating a
35   * column with a row key / value map. Note that, in some implementations, data
36   * access by column key may have fewer supported operations or worse performance
37   * than data access by row key.
38   *
39   * <p>The methods returning collections or maps always return views of the
40   * underlying table. Updating the table can change the contents of those
41   * collections, and updating the collections will change the table.
42   *
43   * <p>All methods that modify the table are optional, and the views returned by
44   * the table may or may not be modifiable. When modification isn't supported,
45   * those methods will throw an {@link UnsupportedOperationException}.
46   *
47   * <p>See the Guava User Guide article on <a href=
48   * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#table">
49   * {@code Table}</a>.
50   *
51   * @author Jared Levy
52   * @param <R> the type of the table row keys
53   * @param <C> the type of the table column keys
54   * @param <V> the type of the mapped values
55   * @since 7.0
56   */
57  @GwtCompatible
58  public interface Table<R, C, V> {
59    // TODO(jlevy): Consider adding methods similar to ConcurrentMap methods.
60  
61    // Accessors
62  
63    /**
64     * Returns {@code true} if the table contains a mapping with the specified row and column keys.
65     *
66     * @param rowKey key of row to search for
67     * @param columnKey key of column to search for
68     */
69    boolean contains(
70        @Nullable @CompatibleWith("R") Object rowKey,
71        @Nullable @CompatibleWith("C") Object columnKey);
72  
73    /**
74     * Returns {@code true} if the table contains a mapping with the specified row key.
75     *
76     * @param rowKey key of row to search for
77     */
78    boolean containsRow(@Nullable @CompatibleWith("R") Object rowKey);
79  
80    /**
81     * Returns {@code true} if the table contains a mapping with the specified column.
82     *
83     * @param columnKey key of column to search for
84     */
85    boolean containsColumn(@Nullable @CompatibleWith("C") Object columnKey);
86  
87    /**
88     * Returns {@code true} if the table contains a mapping with the specified value.
89     *
90     * @param value value to search for
91     */
92    boolean containsValue(@Nullable @CompatibleWith("V") Object value);
93  
94    /**
95     * Returns the value corresponding to the given row and column keys, or {@code null} if no such
96     * mapping exists.
97     *
98     * @param rowKey key of row to search for
99     * @param columnKey key of column to search for
100    */
101   V get(
102       @Nullable @CompatibleWith("R") Object rowKey,
103       @Nullable @CompatibleWith("C") Object columnKey);
104 
105   /** Returns {@code true} if the table contains no mappings. */
106   boolean isEmpty();
107 
108   /**
109    * Returns the number of row key / column key / value mappings in the table.
110    */
111   int size();
112 
113   /**
114    * Compares the specified object with this table for equality. Two tables are
115    * equal when their cell views, as returned by {@link #cellSet}, are equal.
116    */
117   @Override
118   boolean equals(@Nullable Object obj);
119 
120   /**
121    * Returns the hash code for this table. The hash code of a table is defined
122    * as the hash code of its cell view, as returned by {@link #cellSet}.
123    */
124   @Override
125   int hashCode();
126 
127   // Mutators
128 
129   /** Removes all mappings from the table. */
130   void clear();
131 
132   /**
133    * Associates the specified value with the specified keys. If the table
134    * already contained a mapping for those keys, the old value is replaced with
135    * the specified value.
136    *
137    * @param rowKey row key that the value should be associated with
138    * @param columnKey column key that the value should be associated with
139    * @param value value to be associated with the specified keys
140    * @return the value previously associated with the keys, or {@code null} if
141    *     no mapping existed for the keys
142    */
143   @CanIgnoreReturnValue
144   @Nullable
145   V put(R rowKey, C columnKey, V value);
146 
147   /**
148    * Copies all mappings from the specified table to this table. The effect is
149    * equivalent to calling {@link #put} with each row key / column key / value
150    * mapping in {@code table}.
151    *
152    * @param table the table to add to this table
153    */
154   void putAll(Table<? extends R, ? extends C, ? extends V> table);
155 
156   /**
157    * Removes the mapping, if any, associated with the given keys.
158    *
159    * @param rowKey row key of mapping to be removed
160    * @param columnKey column key of mapping to be removed
161    * @return the value previously associated with the keys, or {@code null} if no such value existed
162    */
163   @CanIgnoreReturnValue
164   @Nullable
165   V remove(
166       @Nullable @CompatibleWith("R") Object rowKey,
167       @Nullable @CompatibleWith("C") Object columnKey);
168 
169   // Views
170 
171   /**
172    * Returns a view of all mappings that have the given row key. For each row
173    * key / column key / value mapping in the table with that row key, the
174    * returned map associates the column key with the value. If no mappings in
175    * the table have the provided row key, an empty map is returned.
176    *
177    * <p>Changes to the returned map will update the underlying table, and vice
178    * versa.
179    *
180    * @param rowKey key of row to search for in the table
181    * @return the corresponding map from column keys to values
182    */
183   Map<C, V> row(R rowKey);
184 
185   /**
186    * Returns a view of all mappings that have the given column key. For each row
187    * key / column key / value mapping in the table with that column key, the
188    * returned map associates the row key with the value. If no mappings in the
189    * table have the provided column key, an empty map is returned.
190    *
191    * <p>Changes to the returned map will update the underlying table, and vice
192    * versa.
193    *
194    * @param columnKey key of column to search for in the table
195    * @return the corresponding map from row keys to values
196    */
197   Map<R, V> column(C columnKey);
198 
199   /**
200    * Returns a set of all row key / column key / value triplets. Changes to the
201    * returned set will update the underlying table, and vice versa. The cell set
202    * does not support the {@code add} or {@code addAll} methods.
203    *
204    * @return set of table cells consisting of row key / column key / value
205    *     triplets
206    */
207   Set<Cell<R, C, V>> cellSet();
208 
209   /**
210    * Returns a set of row keys that have one or more values in the table.
211    * Changes to the set will update the underlying table, and vice versa.
212    *
213    * @return set of row keys
214    */
215   Set<R> rowKeySet();
216 
217   /**
218    * Returns a set of column keys that have one or more values in the table.
219    * Changes to the set will update the underlying table, and vice versa.
220    *
221    * @return set of column keys
222    */
223   Set<C> columnKeySet();
224 
225   /**
226    * Returns a collection of all values, which may contain duplicates. Changes
227    * to the returned collection will update the underlying table, and vice
228    * versa.
229    *
230    * @return collection of values
231    */
232   Collection<V> values();
233 
234   /**
235    * Returns a view that associates each row key with the corresponding map from
236    * column keys to values. Changes to the returned map will update this table.
237    * The returned map does not support {@code put()} or {@code putAll()}, or
238    * {@code setValue()} on its entries.
239    *
240    * <p>In contrast, the maps returned by {@code rowMap().get()} have the same
241    * behavior as those returned by {@link #row}. Those maps may support {@code
242    * setValue()}, {@code put()}, and {@code putAll()}.
243    *
244    * @return a map view from each row key to a secondary map from column keys to
245    *     values
246    */
247   Map<R, Map<C, V>> rowMap();
248 
249   /**
250    * Returns a view that associates each column key with the corresponding map
251    * from row keys to values. Changes to the returned map will update this
252    * table. The returned map does not support {@code put()} or {@code putAll()},
253    * or {@code setValue()} on its entries.
254    *
255    * <p>In contrast, the maps returned by {@code columnMap().get()} have the
256    * same behavior as those returned by {@link #column}. Those maps may support
257    * {@code setValue()}, {@code put()}, and {@code putAll()}.
258    *
259    * @return a map view from each column key to a secondary map from row keys to
260    *     values
261    */
262   Map<C, Map<R, V>> columnMap();
263 
264   /**
265    * Row key / column key / value triplet corresponding to a mapping in a table.
266    *
267    * @since 7.0
268    */
269   interface Cell<R, C, V> {
270     /**
271      * Returns the row key of this cell.
272      */
273     @Nullable
274     R getRowKey();
275 
276     /**
277      * Returns the column key of this cell.
278      */
279     @Nullable
280     C getColumnKey();
281 
282     /**
283      * Returns the value of this cell.
284      */
285     @Nullable
286     V getValue();
287 
288     /**
289      * Compares the specified object with this cell for equality. Two cells are
290      * equal when they have equal row keys, column keys, and values.
291      */
292     @Override
293     boolean equals(@Nullable Object obj);
294 
295     /**
296      * Returns the hash code of this cell.
297      *
298      * <p>The hash code of a table cell is equal to {@link
299      * Objects#hashCode}{@code (e.getRowKey(), e.getColumnKey(), e.getValue())}.
300      */
301     @Override
302     int hashCode();
303   }
304 }