001 /*
002 * Copyright (C) 2008 Google Inc.
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
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 boolean equals(@Nullable Object obj);
116
117 /**
118 * Returns the hash code for this table. The hash code of a table is defined
119 * as the hash code of its cell view, as returned by {@link #cellSet}.
120 */
121 int hashCode();
122
123 // Mutators
124
125 /** Removes all mappings from the table. */
126 void clear();
127
128 /**
129 * Associates the specified value with the specified keys. If the table
130 * already contained a mapping for those keys, the old value is replaced with
131 * the specified value.
132 *
133 * @param rowKey row key that the value should be associated with
134 * @param columnKey column key that the value should be associated with
135 * @param value value to be associated with the specified keys
136 * @return the value previously associated with the keys, or {@code null} if
137 * no mapping existed for the keys
138 */
139 V put(R rowKey, C columnKey, V value);
140
141 /**
142 * Copies all mappings from the specified table to this table. The effect is
143 * equivalent to calling {@link #put} with each row key / column key / value
144 * mapping in {@code table}.
145 *
146 * @param table the table to add to this table
147 */
148 void putAll(Table<? extends R, ? extends C, ? extends V> table);
149
150 /**
151 * Removes the mapping, if any, associated with the given keys.
152 *
153 * @param rowKey row key of mapping to be removed
154 * @param columnKey column key of mapping to be removed
155 * @return the value previously associated with the keys, or {@code null} if
156 * no such value existed
157 */
158 V remove(@Nullable Object rowKey, @Nullable Object columnKey);
159
160 // Views
161
162 /**
163 * Returns a view of all mappings that have the given row key. For each row
164 * key / column key / value mapping in the table with that row key, the
165 * returned map associates the column key with the value. If no mappings in
166 * the table have the provided row key, an empty map is returned.
167 *
168 * <p>Changes to the returned map will update the underlying table, and vice
169 * versa.
170 *
171 * @param rowKey key of row to search for in the table
172 * @return the corresponding map from column keys to values
173 */
174 Map<C, V> row(R rowKey);
175
176 /**
177 * Returns a view of all mappings that have the given column key. For each row
178 * key / column key / value mapping in the table with that column key, the
179 * returned map associates the row key with the value. If no mappings in the
180 * table have the provided column key, an empty map is returned.
181 *
182 * <p>Changes to the returned map will update the underlying table, and vice
183 * versa.
184 *
185 * @param columnKey key of column to search for in the table
186 * @return the corresponding map from row keys to values
187 */
188 Map<R, V> column(C columnKey);
189
190 /**
191 * Returns a set of all row key / column key / value triplets. Changes to the
192 * returned set will update the underlying table, and vice versa. The cell set
193 * does not support the {@code add} or {@code addAll} methods.
194 *
195 * @return set of table cells consisting of row key / column key / value
196 * triplets
197 */
198 Set<Cell<R, C, V>> cellSet();
199
200 /**
201 * Returns a set of row keys that have one or more values in the table.
202 * Changes to the set will update the underlying table, and vice versa.
203 *
204 * @return set of row keys
205 */
206 Set<R> rowKeySet();
207
208 /**
209 * Returns a set of column keys that have one or more values in the table.
210 * Changes to the set will update the underlying table, and vice versa.
211 *
212 * @return set of column keys
213 */
214 Set<C> columnKeySet();
215
216 /**
217 * Returns a collection of all values, which may contain duplicates. Changes
218 * to the returned collection will update the underlying table, and vice
219 * versa.
220 *
221 * @return collection of values
222 */
223 Collection<V> values();
224
225 /**
226 * Returns a view that associates each row key with the corresponding map from
227 * column keys to values. Changes to the returned map will update this table.
228 * The returned map does not support {@code put()} or {@code putAll()}, or
229 * {@code setValue()} on its entries.
230 *
231 * <p>In contrast, the maps returned by {@code rowMap().get()} have the same
232 * behavior as those returned by {@link #row}. Those maps may support {@code
233 * setValue()}, {@code put()}, and {@code putAll()}.
234 *
235 * @return a map view from each row key to a secondary map from column keys to
236 * values
237 */
238 Map<R, Map<C, V>> rowMap();
239
240 /**
241 * Returns a view that associates each column key with the corresponding map
242 * from row keys to values. Changes to the returned map will update this
243 * table. The returned map does not support {@code put()} or {@code putAll()},
244 * or {@code setValue()} on its entries.
245 *
246 * <p>In contrast, the maps returned by {@code columnMap().get()} have the
247 * same behavior as those returned by {@link #column}. Those maps may support
248 * {@code setValue()}, {@code put()}, and {@code putAll()}.
249 *
250 * @return a map view from each column key to a secondary map from row keys to
251 * values
252 */
253 Map<C, Map<R, V>> columnMap();
254
255 /**
256 * Row key / column key / value triplet corresponding to a mapping in a table.
257 *
258 * @since 7
259 */
260 @Beta
261 interface Cell<R, C, V> {
262 /**
263 * Returns the row key of this cell.
264 */
265 R getRowKey();
266
267 /**
268 * Returns the column key of this cell.
269 */
270 C getColumnKey();
271
272 /**
273 * Returns the value of this cell.
274 */
275 V getValue();
276
277 /**
278 * Compares the specified object with this cell for equality. Two cells are
279 * equal when they have equal row keys, column keys, and values.
280 */
281 boolean equals(@Nullable Object obj);
282
283 /**
284 * Returns the hash code of this cell.
285 *
286 * <p>The hash code of a table cell is equal to {@link
287 * Objects#hashCode}{@code (e.getRowKey(), e.getColumnKey(), e.getValue())}.
288 */
289 int hashCode();
290 }
291 }