path: root/guava/src/com/google/common/collect/ImmutableTable.java

/*
 * Copyright (C) 2009 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.common.collect;

import static com.google.common.base.Preconditions.checkNotNull;

import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;

import java.util.Comparator;
import java.util.List;
import java.util.Map;

import javax.annotation.Nullable;

/**
 * An immutable {@link Table} with reliable user-specified iteration order.
 * Does not permit null keys or values.
 *
 * <p><b>Note</b>: Although this class is not final, it cannot be subclassed as
 * it has no public or protected constructors. Thus, instances of this class are
 * guaranteed to be immutable.
 *
 * @author gak@google.com (Gregory Kick)
 * @since 11.0
 */
@Beta
@GwtCompatible
// TODO(gak): make serializable
public abstract class ImmutableTable<R, C, V> implements Table<R, C, V> {
  /** Returns an empty immutable table. */
  @SuppressWarnings("unchecked")
  public static final <R, C, V> ImmutableTable<R, C, V> of() {
    return (ImmutableTable<R, C, V>) EmptyImmutableTable.INSTANCE;
  }

  /** Returns an immutable table containing a single cell. */
  public static final <R, C, V> ImmutableTable<R, C, V> of(R rowKey,
      C columnKey, V value) {
    return new SingletonImmutableTable<R, C, V>(rowKey, columnKey, value);
  }

  /**
   * Returns an immutable copy of the provided table.
   *
   * <p>The {@link Table#cellSet()} iteration order of the provided table
   * determines the iteration ordering of all views in the returned table. Note
   * that some views of the original table and the copied table may have
   * different iteration orders. For more control over the ordering, create a
   * {@link Builder} and call {@link Builder#orderRowsBy},
   * {@link Builder#orderColumnsBy}, and {@link Builder#putAll}
   *
   * <p>Despite the method name, this method attempts to avoid actually copying
   * the data when it is safe to do so. The exact circumstances under which a
   * copy will or will not be performed are undocumented and subject to change.
   */
  public static final <R, C, V> ImmutableTable<R, C, V> copyOf(
      Table<? extends R, ? extends C, ? extends V> table) {
    if (table instanceof ImmutableTable<?, ?, ?>) {
      @SuppressWarnings("unchecked")
      ImmutableTable<R, C, V> parameterizedTable
          = (ImmutableTable<R, C, V>) table;
      return parameterizedTable;
    } else {
      int size = table.size();
      switch (size) {
        case 0:
          return of();
        case 1:
          Cell<? extends R, ? extends C, ? extends V> onlyCell
              = Iterables.getOnlyElement(table.cellSet());
          return ImmutableTable.<R, C, V>of(onlyCell.getRowKey(),
              onlyCell.getColumnKey(), onlyCell.getValue());
        default:
          ImmutableSet.Builder<Cell<R, C, V>> cellSetBuilder
              = ImmutableSet.builder();
          for (Cell<? extends R, ? extends C, ? extends V> cell :
              table.cellSet()) {
            /*
             * Must cast to be able to create a Cell<R, C, V> rather than a
             * Cell<? extends R, ? extends C, ? extends V>
             */
            cellSetBuilder.add(cellOf((R) cell.getRowKey(),
                (C) cell.getColumnKey(), (V) cell.getValue()));
          }
          return RegularImmutableTable.forCells(cellSetBuilder.build());
      }
    }
  }

  /**
   * Returns a new builder. The generated builder is equivalent to the builder
   * created by the {@link Builder#Builder()} constructor.
   */
  public static final <R, C, V> Builder<R, C, V> builder() {
    return new Builder<R, C, V>();
  }

  /**
   * Verifies that {@code rowKey}, {@code columnKey} and {@code value} are
   * non-null, and returns a new entry with those values.
   */
  static <R, C, V> Cell<R, C, V> cellOf(R rowKey, C columnKey, V value) {
    return Tables.immutableCell(checkNotNull(rowKey), checkNotNull(columnKey),
        checkNotNull(value));
  }

  /**
   * A builder for creating immutable table instances, especially {@code public
   * static final} tables ("constant tables"). Example: <pre>   {@code
   *
   *   static final ImmutableTable<Integer, Character, String> SPREADSHEET =
   *       new ImmutableTable.Builder<Integer, Character, String>()
   *           .put(1, 'A', "foo")
   *           .put(1, 'B', "bar")
   *           .put(2, 'A', "baz")
   *           .build();}</pre>
   *
   * <p>By default, the order in which cells are added to the builder determines
   * the iteration ordering of all views in the returned table, with {@link
   * #putAll} following the {@link Table#cellSet()} iteration order. However, if
   * {@link #orderRowsBy} or {@link #orderColumnsBy} is called, the views are
   * sorted by the supplied comparators.
   *
   * For empty or single-cell immutable tables, {@link #of()} and
   * {@link #of(Object, Object, Object)} are even more convenient.
   *
   * <p>Builder instances can be reused - it is safe to call {@link #build}
   * multiple times to build multiple tables in series. Each table is a superset
   * of the tables created before it.
   *
   * @since 11.0
   */
  public static final class Builder<R, C, V> {
    private final List<Cell<R, C, V>> cells = Lists.newArrayList();
    private Comparator<? super R> rowComparator;
    private Comparator<? super C> columnComparator;

    /**
     * Creates a new builder. The returned builder is equivalent to the builder
     * generated by {@link ImmutableTable#builder}.
     */
    public Builder() {}

    /**
     * Specifies the ordering of the generated table's rows.
     */
    public Builder<R, C, V> orderRowsBy(Comparator<? super R> rowComparator) {
      this.rowComparator = checkNotNull(rowComparator);
      return this;
    }

    /**
     * Specifies the ordering of the generated table's columns.
     */
    public Builder<R, C, V> orderColumnsBy(
        Comparator<? super C> columnComparator) {
      this.columnComparator = checkNotNull(columnComparator);
      return this;
    }

    /**
     * Associates the ({@code rowKey}, {@code columnKey}) pair with {@code
     * value} in the built table. Duplicate key pairs are not allowed and will
     * cause {@link #build} to fail.
     */
    public Builder<R, C, V> put(R rowKey, C columnKey, V value) {
      cells.add(cellOf(rowKey, columnKey, value));
      return this;
    }

    /**
     * Adds the given {@code cell} to the table, making it immutable if
     * necessary. Duplicate key pairs are not allowed and will cause {@link
     * #build} to fail.
     */
    public Builder<R, C, V> put(
        Cell<? extends R, ? extends C, ? extends V> cell) {
      if (cell instanceof Tables.ImmutableCell) {
        checkNotNull(cell.getRowKey());
        checkNotNull(cell.getColumnKey());
        checkNotNull(cell.getValue());
        @SuppressWarnings("unchecked") // all supported methods are covariant
        Cell<R, C, V> immutableCell = (Cell<R, C, V>) cell;
        cells.add(immutableCell);
      } else {
        put(cell.getRowKey(), cell.getColumnKey(), cell.getValue());
      }
      return this;
    }

    /**
     * Associates all of the given table's keys and values in the built table.
     * Duplicate row key column key pairs are not allowed, and will cause
     * {@link #build} to fail.
     *
     * @throws NullPointerException if any key or value in {@code table} is null
     */
    public Builder<R, C, V> putAll(
        Table<? extends R, ? extends C, ? extends V> table) {
      for (Cell<? extends R, ? extends C, ? extends V> cell : table.cellSet()) {
        put(cell);
      }
      return this;
    }

    /**
     * Returns a newly-created immutable table.
     *
     * @throws IllegalArgumentException if duplicate key pairs were added
     */
    public ImmutableTable<R, C, V> build() {
      int size = cells.size();
      switch (size) {
        case 0:
          return of();
        case 1:
          return new SingletonImmutableTable<R, C, V>(
              Iterables.getOnlyElement(cells));
        default:
         return RegularImmutableTable.forCells(
             cells, rowComparator, columnComparator);
      }
    }
  }

  ImmutableTable() {}

  @Override public abstract ImmutableSet<Cell<R, C, V>> cellSet();

  /**
   * {@inheritDoc}
   *
   * @throws NullPointerException if {@code columnKey} is {@code null}
   */
  @Override public abstract ImmutableMap<R, V> column(C columnKey);

  @Override public abstract ImmutableSet<C> columnKeySet();

  /**
   * {@inheritDoc}
   *
   * <p>The value {@code Map<R, V>}s in the returned map are
   * {@link ImmutableMap}s as well.
   */
  @Override public abstract ImmutableMap<C, Map<R, V>> columnMap();

  /**
   * {@inheritDoc}
   *
   * @throws NullPointerException if {@code rowKey} is {@code null}
   */
  @Override public abstract ImmutableMap<C, V> row(R rowKey);

  @Override public abstract ImmutableSet<R> rowKeySet();

  /**
   * {@inheritDoc}
   *
   * <p>The value {@code Map<C, V>}s in the returned map are
   * {@link ImmutableMap}s as well.
   */
  @Override public abstract ImmutableMap<R, Map<C, V>> rowMap();

  /**
   * Guaranteed to throw an exception and leave the table unmodified.
   *
   * @throws UnsupportedOperationException always
   */
  @Override public final void clear() {
    throw new UnsupportedOperationException();
  }

  /**
   * Guaranteed to throw an exception and leave the table unmodified.
   *
   * @throws UnsupportedOperationException always
   */
  @Override public final V put(R rowKey, C columnKey, V value) {
    throw new UnsupportedOperationException();
  }

  /**
   * Guaranteed to throw an exception and leave the table unmodified.
   *
   * @throws UnsupportedOperationException always
   */
  @Override public final void putAll(
      Table<? extends R, ? extends C, ? extends V> table) {
    throw new UnsupportedOperationException();
  }

  /**
   * Guaranteed to throw an exception and leave the table unmodified.
   *
   * @throws UnsupportedOperationException always
   */
  @Override public final V remove(Object rowKey, Object columnKey) {
    throw new UnsupportedOperationException();
  }

  @Override public boolean equals(@Nullable Object obj) {
    if (obj == this) {
      return true;
    } else if (obj instanceof Table<?, ?, ?>) {
      Table<?, ?, ?> that = (Table<?, ?, ?>) obj;
      return this.cellSet().equals(that.cellSet());
    } else {
      return false;
    }
  }

  @Override public int hashCode() {
    return cellSet().hashCode();
  }

  @Override public String toString() {
    return rowMap().toString();
  }
}