001/*
002 * Copyright (C) 2007 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
017package com.google.common.collect;
018
019import static com.google.common.base.Preconditions.checkArgument;
020import static com.google.common.base.Preconditions.checkNotNull;
021import static com.google.common.collect.Platform.getDeclaringClassOrObjectForJ2cl;
022
023import com.google.common.annotations.GwtCompatible;
024import com.google.common.annotations.GwtIncompatible;
025import com.google.common.annotations.J2ktIncompatible;
026import java.io.IOException;
027import java.io.ObjectInputStream;
028import java.io.ObjectOutputStream;
029import java.util.EnumMap;
030import java.util.Map;
031
032/**
033 * A {@code BiMap} backed by two {@code EnumMap} instances. Null keys and values are not permitted.
034 * An {@code EnumBiMap} and its inverse are both serializable.
035 *
036 * <p>See the Guava User Guide article on <a href=
037 * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#bimap">{@code BiMap}</a>.
038 *
039 * @author Mike Bostock
040 * @since 2.0
041 */
042@GwtCompatible(emulated = true)
043@J2ktIncompatible
044@ElementTypesAreNonnullByDefault
045public final class EnumBiMap<K extends Enum<K>, V extends Enum<V>> extends AbstractBiMap<K, V> {
046  /*
047   * J2CL's EnumMap does not need the Class instance, so we can use Object.class instead. (Or we
048   * could use null, but that messes with our nullness checking, including under J2KT. We could
049   * probably work around it by changing how we annotate the J2CL EnumMap, but that's probably more
050   * trouble than just using Object.class.)
051   *
052   * Then we declare the getters for these fields as @GwtIncompatible so that no one can try to use
053   * them under J2CL—or, as an unfortunate side effect, under GWT. We do still give the fields
054   * themselves their proper values under GWT, since GWT's EnumMap does need the Class instance.
055   *
056   * Note that sometimes these fields *do* have correct values under J2CL: They will if the caller
057   * calls `create(Foo.class)`, rather than `create(map)`. That's fine; we just shouldn't rely on
058   * it.
059   */
060  transient Class<K> keyTypeOrObjectUnderJ2cl;
061  transient Class<V> valueTypeOrObjectUnderJ2cl;
062
063  /**
064   * Returns a new, empty {@code EnumBiMap} using the specified key and value types.
065   *
066   * @param keyType the key type
067   * @param valueType the value type
068   */
069  public static <K extends Enum<K>, V extends Enum<V>> EnumBiMap<K, V> create(
070      Class<K> keyType, Class<V> valueType) {
071    return new EnumBiMap<>(keyType, valueType);
072  }
073
074  /**
075   * Returns a new bimap with the same mappings as the specified map. If the specified map is an
076   * {@code EnumBiMap}, the new bimap has the same types as the provided map. Otherwise, the
077   * specified map must contain at least one mapping, in order to determine the key and value types.
078   *
079   * @param map the map whose mappings are to be placed in this map
080   * @throws IllegalArgumentException if map is not an {@code EnumBiMap} instance and contains no
081   *     mappings
082   */
083  public static <K extends Enum<K>, V extends Enum<V>> EnumBiMap<K, V> create(Map<K, V> map) {
084    EnumBiMap<K, V> bimap =
085        create(inferKeyTypeOrObjectUnderJ2cl(map), inferValueTypeOrObjectUnderJ2cl(map));
086    bimap.putAll(map);
087    return bimap;
088  }
089
090  private EnumBiMap(Class<K> keyTypeOrObjectUnderJ2cl, Class<V> valueTypeOrObjectUnderJ2cl) {
091    super(
092        new EnumMap<K, V>(keyTypeOrObjectUnderJ2cl), new EnumMap<V, K>(valueTypeOrObjectUnderJ2cl));
093    this.keyTypeOrObjectUnderJ2cl = keyTypeOrObjectUnderJ2cl;
094    this.valueTypeOrObjectUnderJ2cl = valueTypeOrObjectUnderJ2cl;
095  }
096
097  static <K extends Enum<K>> Class<K> inferKeyTypeOrObjectUnderJ2cl(Map<K, ?> map) {
098    if (map instanceof EnumBiMap) {
099      return ((EnumBiMap<K, ?>) map).keyTypeOrObjectUnderJ2cl;
100    }
101    if (map instanceof EnumHashBiMap) {
102      return ((EnumHashBiMap<K, ?>) map).keyTypeOrObjectUnderJ2cl;
103    }
104    checkArgument(!map.isEmpty());
105    return getDeclaringClassOrObjectForJ2cl(map.keySet().iterator().next());
106  }
107
108  private static <V extends Enum<V>> Class<V> inferValueTypeOrObjectUnderJ2cl(Map<?, V> map) {
109    if (map instanceof EnumBiMap) {
110      return ((EnumBiMap<?, V>) map).valueTypeOrObjectUnderJ2cl;
111    }
112    checkArgument(!map.isEmpty());
113    return getDeclaringClassOrObjectForJ2cl(map.values().iterator().next());
114  }
115
116  /** Returns the associated key type. */
117  @GwtIncompatible
118  public Class<K> keyType() {
119    return keyTypeOrObjectUnderJ2cl;
120  }
121
122  /** Returns the associated value type. */
123  @GwtIncompatible
124  public Class<V> valueType() {
125    return valueTypeOrObjectUnderJ2cl;
126  }
127
128  @Override
129  K checkKey(K key) {
130    return checkNotNull(key);
131  }
132
133  @Override
134  V checkValue(V value) {
135    return checkNotNull(value);
136  }
137
138  /**
139   * @serialData the key class, value class, number of entries, first key, first value, second key,
140   *     second value, and so on.
141   */
142  @GwtIncompatible // java.io.ObjectOutputStream
143  private void writeObject(ObjectOutputStream stream) throws IOException {
144    stream.defaultWriteObject();
145    stream.writeObject(keyTypeOrObjectUnderJ2cl);
146    stream.writeObject(valueTypeOrObjectUnderJ2cl);
147    Serialization.writeMap(this, stream);
148  }
149
150  @SuppressWarnings("unchecked") // reading fields populated by writeObject
151  @GwtIncompatible // java.io.ObjectInputStream
152  private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException {
153    stream.defaultReadObject();
154    keyTypeOrObjectUnderJ2cl = (Class<K>) stream.readObject();
155    valueTypeOrObjectUnderJ2cl = (Class<V>) stream.readObject();
156    setDelegates(
157        new EnumMap<K, V>(keyTypeOrObjectUnderJ2cl), new EnumMap<V, K>(valueTypeOrObjectUnderJ2cl));
158    Serialization.populateMap(this, stream);
159  }
160
161  @GwtIncompatible // not needed in emulated source.
162  private static final long serialVersionUID = 0;
163}