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 22 import java.util.Collection; 23 import java.util.Map; 24 import java.util.Set; 25 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 * "http://code.google.com/p/guava-libraries/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 65 * row and column keys. 66 * 67 * @param rowKey key of row to search for 68 * @param columnKey key of column to search for 69 */ 70 boolean contains(@Nullable Object rowKey, @Nullable Object columnKey); 71 72 /** 73 * Returns {@code true} if the table contains a mapping with the specified 74 * row key. 75 * 76 * @param rowKey key of row to search for 77 */ 78 boolean containsRow(@Nullable Object rowKey); 79 80 /** 81 * Returns {@code true} if the table contains a mapping with the specified 82 * column. 83 * 84 * @param columnKey key of column to search for 85 */ 86 boolean containsColumn(@Nullable Object columnKey); 87 88 /** 89 * Returns {@code true} if the table contains a mapping with the specified 90 * value. 91 * 92 * @param value value to search for 93 */ 94 boolean containsValue(@Nullable Object value); 95 96 /** 97 * Returns the value corresponding to the given row and column keys, or 98 * {@code null} if no such mapping exists. 99 * 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 } 297
