1 /*

     2  * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package java.util;

    27 

    28 import jdk.internal.vm.annotation.Stable;

    29 

    30 /**

    31  * An immutable container for a key and a value, suitable for use

    32  * in creating and populating {@code Map} instances.

    33  *

    34  * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>

    35  * class; use of identity-sensitive operations (including reference equality

    36  * ({@code ==}), identity hash code, or synchronization) on instances of

    37  * {@code KeyValueHolder} may have unpredictable results and should be avoided.

    38  *

    39  * @apiNote

    40  * This class is not public. Instances can be created using the

    41  * {@link Map#entry Map.entry(k, v)} factory method, which is public.

    42  *

    43  * <p>This class differs from AbstractMap.SimpleImmutableEntry in the following ways:

    44  * it is not serializable, it is final, and its key and value must be non-null.

    45  *

    46  * @param <K> the key type

    47  * @param <V> the value type

    48  *

    49  * @see Map#ofEntries Map.ofEntries()

    50  * @since 9

    51  */

    52 final class KeyValueHolder<K,V> implements Map.Entry<K,V> {

    53     @Stable

    54     final K key;

    55     @Stable

    56     final V value;

    57 

    58     KeyValueHolder(K k, V v) {

    59         key = Objects.requireNonNull(k);

    60         value = Objects.requireNonNull(v);

    61     }

    62 

    63     /**

    64      * Gets the key from this holder.

    65      *

    66      * @return the key

    67      */

    68     @Override

    69     public K getKey() {

    70         return key;

    71     }

    72 

    73     /**

    74      * Gets the value from this holder.

    75      *

    76      * @return the value

    77      */

    78     @Override

    79     public V getValue() {

    80         return value;

    81     }

    82 

    83     /**

    84      * Throws {@link UnsupportedOperationException}.

    85      *

    86      * @param value ignored

    87      * @return never returns normally

    88      */

    89     @Override

    90     public V setValue(V value) {

    91         throw new UnsupportedOperationException("not supported");

    92     }

    93 

    94     /**

    95      * Compares the specified object with this entry for equality.

    96      * Returns {@code true} if the given object is also a map entry and

    97      * the two entries' keys and values are equal. Note that key and

    98      * value are non-null, so equals() can be called safely on them.

    99      */

   100     @Override

   101     public boolean equals(Object o) {

   102         if (!(o instanceof Map.Entry))

   103             return false;

   104         Map.Entry<?,?> e = (Map.Entry<?,?>)o;

   105         return key.equals(e.getKey()) && value.equals(e.getValue());

   106     }

   107 

   108     /**

   109      * Returns the hash code value for this map entry. The hash code

   110      * is {@code key.hashCode() ^ value.hashCode()}. Note that key and

   111      * value are non-null, so hashCode() can be called safely on them.

   112      */

   113     @Override

   114     public int hashCode() {

   115         return key.hashCode() ^ value.hashCode();

   116     }

   117 

   118     /**

   119      * Returns a String representation of this map entry.  This

   120      * implementation returns the string representation of this

   121      * entry's key followed by the equals character ("{@code =}")

   122      * followed by the string representation of this entry's value.

   123      *

   124      * @return a String representation of this map entry

   125      */

   126     @Override

   127     public String toString() {

   128         return key + "=" + value;

   129     }

   130 }