    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.0
    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.0
    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    }