001/*
002 * Copyright (C) 2008 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.GwtCompatible;
021import com.google.common.base.Objects;
022
023import java.util.Collection;
024import java.util.Map;
025import java.util.Set;
026
027import javax.annotation.Nullable;
028
029/**
030 * A collection that associates an ordered pair of keys, called a row key and a
031 * column key, with a single value. A table may be sparse, with only a small
032 * fraction of row key / column key pairs possessing a corresponding value.
033 *
034 * <p>The mappings corresponding to a given row key may be viewed as a {@link
035 * Map} whose keys are the columns. The reverse is also available, associating a
036 * column with a row key / value map. Note that, in some implementations, data
037 * access by column key may have fewer supported operations or worse performance
038 * than data access by row key.
039 *
040 * <p>The methods returning collections or maps always return views of the
041 * underlying table. Updating the table can change the contents of those
042 * collections, and updating the collections will change the table.
043 *
044 * <p>All methods that modify the table are optional, and the views returned by
045 * the table may or may not be modifiable. When modification isn't supported,
046 * those methods will throw an {@link UnsupportedOperationException}.
047 *
048 * @author Jared Levy
049 * @param <R> the type of the table row keys
050 * @param <C> the type of the table column keys
051 * @param <V> the type of the mapped values
052 * @since 7
053 */
054@GwtCompatible
055@Beta
056public interface Table<R, C, V> {
057  // TODO(jlevy): Consider adding methods similar to ConcurrentMap methods.
058
059  // Accessors
060
061  /**
062   * Returns {@code true} if the table contains a mapping with the specified
063   * row and column keys.
064   *
065   * @param rowKey key of row to search for
066   * @param columnKey key of column to search for
067   */
068  boolean contains(@Nullable Object rowKey, @Nullable Object columnKey);
069
070  /**
071   * Returns {@code true} if the table contains a mapping with the specified
072   * row key.
073   *
074   * @param rowKey key of row to search for
075   */
076  boolean containsRow(@Nullable Object rowKey);
077
078  /**
079   * Returns {@code true} if the table contains a mapping with the specified
080   * column.
081   *
082   * @param columnKey key of column to search for
083   */
084  boolean containsColumn(@Nullable Object columnKey);
085
086  /**
087   * Returns {@code true} if the table contains a mapping with the specified
088   * value.
089   *
090   * @param value value to search for
091   */
092  boolean containsValue(@Nullable Object value);
093
094  /**
095   * Returns the value corresponding to the given row and column keys, or
096   * {@code null} if no such mapping exists.
097   *
098   * @param rowKey key of row to search for
099   * @param columnKey key of column to search for
100   */
101  V get(@Nullable Object rowKey, @Nullable Object columnKey);
102
103  /** Returns {@code true} if the table contains no mappings. */
104  boolean isEmpty();
105
106  /**
107   * Returns the number of row key / column key / value mappings in the table.
108   */
109  int size();
110
111  /**
112   * Compares the specified object with this table for equality. Two tables are
113   * equal when their cell views, as returned by {@link #cellSet}, are equal.
114   */
115  @Override
116  boolean equals(@Nullable Object obj);
117
118  /**
119   * Returns the hash code for this table. The hash code of a table is defined
120   * as the hash code of its cell view, as returned by {@link #cellSet}.
121   */
122  @Override
123  int hashCode();
124
125  // Mutators
126
127  /** Removes all mappings from the table. */
128  void clear();
129
130  /**
131   * Associates the specified value with the specified keys. If the table
132   * already contained a mapping for those keys, the old value is replaced with
133   * the specified value.
134   *
135   * @param rowKey row key that the value should be associated with
136   * @param columnKey column key that the value should be associated with
137   * @param value value to be associated with the specified keys
138   * @return the value previously associated with the keys, or {@code null} if
139   *     no mapping existed for the keys
140   */
141  V put(R rowKey, C columnKey, V value);
142
143  /**
144   * Copies all mappings from the specified table to this table. The effect is
145   * equivalent to calling {@link #put} with each row key / column key / value
146   * mapping in {@code table}.
147   *
148   * @param table the table to add to this table
149   */
150  void putAll(Table<? extends R, ? extends C, ? extends V> table);
151
152  /**
153   * Removes the mapping, if any, associated with the given keys.
154   *
155   * @param rowKey row key of mapping to be removed
156   * @param columnKey column key of mapping to be removed
157   * @return the value previously associated with the keys, or {@code null} if
158   *     no such value existed
159   */
160  V remove(@Nullable Object rowKey, @Nullable Object columnKey);
161
162  // Views
163
164  /**
165   * Returns a view of all mappings that have the given row key. For each row
166   * key / column key / value mapping in the table with that row key, the
167   * returned map associates the column key with the value. If no mappings in
168   * the table have the provided row key, an empty map is returned.
169   *
170   * <p>Changes to the returned map will update the underlying table, and vice
171   * versa.
172   *
173   * @param rowKey key of row to search for in the table
174   * @return the corresponding map from column keys to values
175   */
176  Map<C, V> row(R rowKey);
177
178  /**
179   * Returns a view of all mappings that have the given column key. For each row
180   * key / column key / value mapping in the table with that column key, the
181   * returned map associates the row key with the value. If no mappings in the
182   * table have the provided column key, an empty map is returned.
183   *
184   * <p>Changes to the returned map will update the underlying table, and vice
185   * versa.
186   *
187   * @param columnKey key of column to search for in the table
188   * @return the corresponding map from row keys to values
189   */
190  Map<R, V> column(C columnKey);
191
192  /**
193   * Returns a set of all row key / column key / value triplets. Changes to the
194   * returned set will update the underlying table, and vice versa. The cell set
195   * does not support the {@code add} or {@code addAll} methods.
196   *
197   * @return set of table cells consisting of row key / column key / value
198   *     triplets
199   */
200  Set<Cell<R, C, V>> cellSet();
201
202  /**
203   * Returns a set of row keys that have one or more values in the table.
204   * Changes to the set will update the underlying table, and vice versa.
205   *
206   * @return set of row keys
207   */
208  Set<R> rowKeySet();
209
210  /**
211   * Returns a set of column keys that have one or more values in the table.
212   * Changes to the set will update the underlying table, and vice versa.
213   *
214   * @return set of column keys
215   */
216  Set<C> columnKeySet();
217
218  /**
219   * Returns a collection of all values, which may contain duplicates. Changes
220   * to the returned collection will update the underlying table, and vice
221   * versa.
222   *
223   * @return collection of values
224   */
225  Collection<V> values();
226
227  /**
228   * Returns a view that associates each row key with the corresponding map from
229   * column keys to values. Changes to the returned map will update this table.
230   * The returned map does not support {@code put()} or {@code putAll()}, or
231   * {@code setValue()} on its entries.
232   *
233   * <p>In contrast, the maps returned by {@code rowMap().get()} have the same
234   * behavior as those returned by {@link #row}. Those maps may support {@code
235   * setValue()}, {@code put()}, and {@code putAll()}.
236   *
237   * @return a map view from each row key to a secondary map from column keys to
238   *     values
239   */
240  Map<R, Map<C, V>> rowMap();
241
242  /**
243   * Returns a view that associates each column key with the corresponding map
244   * from row keys to values. Changes to the returned map will update this
245   * table. The returned map does not support {@code put()} or {@code putAll()},
246   * or {@code setValue()} on its entries.
247   *
248   * <p>In contrast, the maps returned by {@code columnMap().get()} have the
249   * same behavior as those returned by {@link #column}. Those maps may support
250   * {@code setValue()}, {@code put()}, and {@code putAll()}.
251   *
252   * @return a map view from each column key to a secondary map from row keys to
253   *     values
254   */
255  Map<C, Map<R, V>> columnMap();
256
257  /**
258   * Row key / column key / value triplet corresponding to a mapping in a table.
259   *
260   * @since 7
261   */
262  @Beta
263  interface Cell<R, C, V> {
264    /**
265     * Returns the row key of this cell.
266     */
267    R getRowKey();
268
269    /**
270     * Returns the column key of this cell.
271     */
272    C getColumnKey();
273
274    /**
275     * Returns the value of this cell.
276     */
277    V getValue();
278
279    /**
280     * Compares the specified object with this cell for equality. Two cells are
281     * equal when they have equal row keys, column keys, and values.
282     */
283    @Override
284    boolean equals(@Nullable Object obj);
285
286    /**
287     * Returns the hash code of this cell.
288     *
289     * <p>The hash code of a table cell is equal to {@link
290     * Objects#hashCode}{@code (e.getRowKey(), e.getColumnKey(), e.getValue())}.
291     */
292    @Override
293    int hashCode();
294  }
295}