View Javadoc
1   /*
2    * Copyright (C) 2013 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package com.google.common.collect;
18  
19  import static com.google.common.collect.CollectPreconditions.checkEntryNotNull;
20  
21  import com.google.common.annotations.GwtIncompatible;
22  import javax.annotation.Nullable;
23  
24  /**
25   * Implementation of {@code Map.Entry} for {@link ImmutableMap} that adds extra methods to traverse
26   * hash buckets for the key and the value. This allows reuse in {@link RegularImmutableMap} and
27   * {@link RegularImmutableBiMap}, which don't have to recopy the entries created by their
28   * {@code Builder} implementations.
29   *
30   * <p>This base implementation has no key or value pointers, so instances of ImmutableMapEntry
31   * (but not its subclasses) can be reused when copied from one ImmutableMap to another.
32   *
33   * @author Louis Wasserman
34   */
35  @GwtIncompatible // unnecessary
36  class ImmutableMapEntry<K, V> extends ImmutableEntry<K, V> {
37    /**
38     * Creates an {@code ImmutableMapEntry} array to hold parameterized entries. The
39     * result must never be upcast back to ImmutableMapEntry[] (or Object[], etc.), or
40     * allowed to escape the class.
41     */
42    @SuppressWarnings("unchecked") // Safe as long as the javadocs are followed
43    static <K, V> ImmutableMapEntry<K, V>[] createEntryArray(int size) {
44      return new ImmutableMapEntry[size];
45    }
46  
47    ImmutableMapEntry(K key, V value) {
48      super(key, value);
49      checkEntryNotNull(key, value);
50    }
51  
52    ImmutableMapEntry(ImmutableMapEntry<K, V> contents) {
53      super(contents.getKey(), contents.getValue());
54      // null check would be redundant
55    }
56  
57    @Nullable
58    ImmutableMapEntry<K, V> getNextInKeyBucket() {
59      return null;
60    }
61  
62    @Nullable
63    ImmutableMapEntry<K, V> getNextInValueBucket() {
64      return null;
65    }
66  
67    /**
68     * Returns true if this entry has no bucket links and can safely be reused as a terminal
69     * entry in a bucket in another map.
70     */
71    boolean isReusable() {
72      return true;
73    }
74  
75    static class NonTerminalImmutableMapEntry<K, V> extends ImmutableMapEntry<K, V> {
76      private final transient ImmutableMapEntry<K, V> nextInKeyBucket;
77  
78      NonTerminalImmutableMapEntry(K key, V value, ImmutableMapEntry<K, V> nextInKeyBucket) {
79        super(key, value);
80        this.nextInKeyBucket = nextInKeyBucket;
81      }
82  
83      @Override
84      @Nullable
85      final ImmutableMapEntry<K, V> getNextInKeyBucket() {
86        return nextInKeyBucket;
87      }
88  
89      @Override
90      final boolean isReusable() {
91        return false;
92      }
93    }
94  
95    static final class NonTerminalImmutableBiMapEntry<K, V>
96        extends NonTerminalImmutableMapEntry<K, V> {
97      private final transient ImmutableMapEntry<K, V> nextInValueBucket;
98  
99      NonTerminalImmutableBiMapEntry(
100         K key,
101         V value,
102         ImmutableMapEntry<K, V> nextInKeyBucket,
103         ImmutableMapEntry<K, V> nextInValueBucket) {
104       super(key, value, nextInKeyBucket);
105       this.nextInValueBucket = nextInValueBucket;
106     }
107 
108     @Override
109     @Nullable
110     ImmutableMapEntry<K, V> getNextInValueBucket() {
111       return nextInValueBucket;
112     }
113   }
114 }