com.google.common.collect.ImmutableBiMapBuilder Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of google-collect Show documentation

Google Collections Library is a suite of new collections and collection-related goodness for Java 5.0

There is a newer version: snapshot-20080530

/*
 * Copyright (C) 2007 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 com.google.common.base.Nullable;
import static com.google.common.base.Preconditions.checkState;

/**
 * A convenient way to populate immutable BiMap instances, especially
 * static-final "constant BiMaps". Code such as
 *
 *  *   static final BiMap<String,Integer> ENGLISH_TO_INTEGER_BIMAP
 *       = createNumbersMap();
 *
 *   static BiMap<String,Integer> createNumbersMap() {
 *     BiMap<String,Integer> bimap = StandardBiMap.newInstance();
 *     bimap.put("one", 1);
 *     bimap.put("two", 2);
 *     bimap.put("three", 3);
 *     return StandardBiMap.unmodifiableBiMap(bimap);
 *   }
 * 
 * ... can be rewritten far more simply as ...
 *  *   static final BiMap<String,Integer> ENGLISH_TO_INTEGER_BIMAP
 *     = new ImmutableBiMapBuilder<String,Integer>()
 *       .put("one", 1)
 *       .put("two", 2)
 *       .put("three", 3)
 *       .getBiMap();
 * 
 * (Actually, for small immutable bimaps, you can use members of the
 * even-more-convenient {@link Maps#immutableBiMap()} family of methods.)
 *
 * @author Alex Dovlecel
 */
public class ImmutableBiMapBuilder {
  /**
   * Temporary bimap used for holding the state of the builder before the bimap
   * will be created. When the bimap is created, it is set to {@code null}.
   */
  private BiMap biMap;

  /** Creates a new ImmutableBiMapBuilder with an unspecified expected size. */
  public ImmutableBiMapBuilder() {
    this(8);
  }

  /**
   * Creates a new ImmutableBiMapBuilder with the given expected size.
   *
   * @param expectedSize the approximate number of key-value pairs you expect
   *     this bimap to contain
   */
  public ImmutableBiMapBuilder(int expectedSize) {
    biMap = new HashBiMap(expectedSize);
  }

  /**
   * Adds a key-value mapping to the bimap that will be returned by {@code
   * getBiMap()}.
   *
   * @param key key with which the specified value is to be associated
   * @param value value to be associated with the specified key
   * @return this bimap builder (to enable call chaining)
   * @throws IllegalStateException if {@code getBiMap()} has already been
   *     called
   */
  public ImmutableBiMapBuilder put(@Nullable K key, @Nullable V value) {
    checkState(biMap != null, "bimap has already been created");
    biMap.put(key, value);
    return this;
  }

  /**
   * Returns a newly-created, immutable BiMap instance containing the keys and
   * values that were specified using {@code put()}.
   *
   * @return a new, immutable {@link BiMap} instance
   * @throws IllegalStateException if {@code getBiMap()} has already been
   *     called
   */
  public BiMap getBiMap() {
    checkState(biMap != null, "bimap has already been created");
    try {
      return Maps.unmodifiableBiMap(biMap);
    } finally {
      biMap = null;
    }
  }
}