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.Beta; 20 import com.google.common.annotations.GwtCompatible; 21 import com.google.common.base.Objects; 22 23 import java.util.Collection; 24 import java.util.Map; 25 import java.util.Set; 26 27 import javax.annotation.Nullable; 28 29 /** 30 * A collection that associates an ordered pair of keys, called a row key and a 31 * column key, with a single value. A table may be sparse, with only a small 32 * fraction of row key / column key pairs possessing a corresponding value. 33 * 34 * <p>The mappings corresponding to a given row key may be viewed as a {@link 35 * Map} whose keys are the columns. The reverse is also available, associating a 36 * column with a row key / value map. Note that, in some implementations, data 37 * access by column key may have fewer supported operations or worse performance 38 * than data access by row key. 39 * 40 * <p>The methods returning collections or maps always return views of the 41 * underlying table. Updating the table can change the contents of those 42 * collections, and updating the collections will change the table. 43 * 44 * <p>All methods that modify the table are optional, and the views returned by 45 * the table may or may not be modifiable. When modification isn't supported, 46 * those methods will throw an {@link UnsupportedOperationException}. 47 * 48 * @author Jared Levy 49 * @param <R> the type of the table row keys 50 * @param <C> the type of the table column keys 51 * @param <V> the type of the mapped values 52 * @since 7.0 53 */ 54 @GwtCompatible 55 @Beta 56 public interface Table<R, C, V> { 57 // TODO(jlevy): Consider adding methods similar to ConcurrentMap methods. 58 59 // Accessors 60 61 /** 62 * Returns {@code true} if the table contains a mapping with the specified 63 * row and column keys. 64 * 65 * @param rowKey key of row to search for 66 * @param columnKey key of column to search for 67 */ 68 boolean contains(@Nullable Object rowKey, @Nullable Object columnKey); 69 70 /** 71 * Returns {@code true} if the table contains a mapping with the specified 72 * row key. 73 * 74 * @param rowKey key of row to search for 75 */ 76 boolean containsRow(@Nullable Object rowKey); 77 78 /** 79 * Returns {@code true} if the table contains a mapping with the specified 80 * column. 81 * 82 * @param columnKey key of column to search for 83 */ 84 boolean containsColumn(@Nullable Object columnKey); 85 86 /** 87 * Returns {@code true} if the table contains a mapping with the specified 88 * value. 89 * 90 * @param value value to search for 91 */ 92 boolean containsValue(@Nullable Object value); 93 94 /** 95 * Returns the value corresponding to the given row and column keys, or 96 * {@code null} if no such mapping exists. 97 * 98 * @param rowKey key of row to search for 99 * @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 } 296
