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 boolean equals(@Nullable Object obj);
118
119 /**
120 * Returns the hash code for this table. The hash code of a table is defined
121 * as the hash code of its cell view, as returned by {@link #cellSet}.
122 */
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 interface Cell<R, C, V> {
263 /**
264 * Returns the row key of this cell.
265 */
266 R getRowKey();
267
268 /**
269 * Returns the column key of this cell.
270 */
271 C getColumnKey();
272
273 /**
274 * Returns the value of this cell.
275 */
276 V getValue();
277
278 /**
279 * Compares the specified object with this cell for equality. Two cells are
280 * equal when they have equal row keys, column keys, and values.
281 */
282 boolean equals(@Nullable Object obj);
283
284 /**
285 * Returns the hash code of this cell.
286 *
287 * <p>The hash code of a table cell is equal to {@link
288 * Objects#hashCode}{@code (e.getRowKey(), e.getColumnKey(), e.getValue())}.
289 */
290 int hashCode();
291 }
292 }