DefaultKeyValue.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.collections4.keyvalue;

  18. import java.util.Map;
  19. import java.util.Objects;

  20. import org.apache.commons.collections4.KeyValue;

  21. /**
  22.  * A mutable {@code KeyValue} pair that does not implement
  23.  * {@link java.util.Map.Entry Map.Entry}.
  24.  * <p>
  25.  * Note that a {@code DefaultKeyValue} instance may not contain
  26.  * itself as a key or value.
  27.  * </p>
  28.  *
  29.  * @param <K> the type of keys
  30.  * @param <V> the type of values
  31.  * @since 3.0
  32.  */
  33. public class DefaultKeyValue<K, V> extends AbstractKeyValue<K, V> {

  34.     /**
  35.      * Constructs a new pair with a null key and null value.
  36.      */
  37.     public DefaultKeyValue() {
  38.         super(null, null);
  39.     }

  40.     /**
  41.      * Constructs a new pair with the specified key and given value.
  42.      *
  43.      * @param key  the key for the entry, may be null
  44.      * @param value  the value for the entry, may be null
  45.      */
  46.     public DefaultKeyValue(final K key, final V value) {
  47.         super(key, value);
  48.     }

  49.     /**
  50.      * Constructs a new pair from the specified {@code KeyValue}.
  51.      *
  52.      * @param pair  the pair to copy, must not be null
  53.      * @throws NullPointerException if the entry is null
  54.      */
  55.     public DefaultKeyValue(final KeyValue<? extends K, ? extends V> pair) {
  56.         super(pair.getKey(), pair.getValue());
  57.     }

  58.     /**
  59.      * Constructs a new pair from the specified {@code Map.Entry}.
  60.      *
  61.      * @param entry  the entry to copy, must not be null
  62.      * @throws NullPointerException if the entry is null
  63.      */
  64.     public DefaultKeyValue(final Map.Entry<? extends K, ? extends V> entry) {
  65.         super(entry.getKey(), entry.getValue());
  66.     }

  67.     /**
  68.      * Compares this {@code Map.Entry} with another {@code Map.Entry}.
  69.      * <p>
  70.      * Returns true if the compared object is also a {@code DefaultKeyValue},
  71.      * and its key and value are equal to this object's key and value.
  72.      *
  73.      * @param obj  the object to compare to
  74.      * @return true if equal key and value
  75.      */
  76.     @Override
  77.     public boolean equals(final Object obj) {
  78.         if (obj == this) {
  79.             return true;
  80.         }
  81.         if (!(obj instanceof DefaultKeyValue)) {
  82.             return false;
  83.         }

  84.         final DefaultKeyValue<?, ?> other = (DefaultKeyValue<?, ?>) obj;
  85.         return
  86.             Objects.equals(getKey(), other.getKey()) &&
  87.             Objects.equals(getValue(), other.getValue());
  88.     }

  89.     /**
  90.      * Gets a hashCode compatible with the equals method.
  91.      * <p>
  92.      * Implemented per API documentation of {@link java.util.Map.Entry#hashCode()},
  93.      * however subclasses may override this.
  94.      *
  95.      * @return a suitable hash code
  96.      */
  97.     @Override
  98.     public int hashCode() {
  99.         return (getKey() == null ? 0 : getKey().hashCode()) ^
  100.                (getValue() == null ? 0 : getValue().hashCode());
  101.     }

  102.     /**
  103.      * Sets the key.
  104.      *
  105.      * @param key  the new key
  106.      * @return the old key
  107.      * @throws IllegalArgumentException if key is this object
  108.      */
  109.     @Override
  110.     public K setKey(final K key) {
  111.         if (key == this) {
  112.             throw new IllegalArgumentException("DefaultKeyValue may not contain itself as a key.");
  113.         }

  114.         return super.setKey(key);
  115.     }

  116.     /**
  117.      * Sets the value.
  118.      *
  119.      * @return the old value of the value
  120.      * @param value the new value
  121.      * @throws IllegalArgumentException if value is this object
  122.      */
  123.     @Override
  124.     public V setValue(final V value) {
  125.         if (value == this) {
  126.             throw new IllegalArgumentException("DefaultKeyValue may not contain itself as a value.");
  127.         }

  128.         return super.setValue(value);
  129.     }

  130.     /**
  131.      * Returns a new {@code Map.Entry} object with key and value from this pair.
  132.      *
  133.      * @return a MapEntry instance
  134.      */
  135.     public Map.Entry<K, V> toMapEntry() {
  136.         return new DefaultMapEntry<>(this);
  137.     }

  138. }