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    
017    package com.google.common.collect;
018    
019    import com.google.common.annotations.Beta;
020    import com.google.common.annotations.GwtCompatible;
021    import com.google.common.base.Objects;
022    
023    import java.util.Collection;
024    import java.util.Map;
025    import java.util.Set;
026    
027    import 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
056    public 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    }