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