    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.collections4.keyvalue;
    018
    019import java.util.Map;
    020
    021import org.apache.commons.collections4.KeyValue;
    022
    023/**
    024 * A mutable {@code KeyValue} pair that does not implement
    025 * {@link java.util.Map.Entry Map.Entry}.
    026 * <p>
    027 * Note that a {@code DefaultKeyValue} instance may not contain
    028 * itself as a key or value.
    029 * </p>
    030 *
    031 * @param <K> the type of keys
    032 * @param <V> the type of values
    033 * @since 3.0
    034 */
    035public class DefaultKeyValue<K, V> extends AbstractKeyValue<K, V> {
    036
    037    /**
    038     * Constructs a new pair with a null key and null value.
    039     */
    040    public DefaultKeyValue() {
    041        super(null, null);
    042    }
    043
    044    /**
    045     * Constructs a new pair with the specified key and given value.
    046     *
    047     * @param key  the key for the entry, may be null
    048     * @param value  the value for the entry, may be null
    049     */
    050    public DefaultKeyValue(final K key, final V value) {
    051        super(key, value);
    052    }
    053
    054    /**
    055     * Constructs a new pair from the specified {@code KeyValue}.
    056     *
    057     * @param pair  the pair to copy, must not be null
    058     * @throws NullPointerException if the entry is null
    059     */
    060    public DefaultKeyValue(final KeyValue<? extends K, ? extends V> pair) {
    061        super(pair.getKey(), pair.getValue());
    062    }
    063
    064    /**
    065     * Constructs a new pair from the specified {@code Map.Entry}.
    066     *
    067     * @param entry  the entry to copy, must not be null
    068     * @throws NullPointerException if the entry is null
    069     */
    070    public DefaultKeyValue(final Map.Entry<? extends K, ? extends V> entry) {
    071        super(entry.getKey(), entry.getValue());
    072    }
    073
    074    /**
    075     * Compares this {@code Map.Entry} with another {@code Map.Entry}.
    076     * <p>
    077     * Returns true if the compared object is also a {@code DefaultKeyValue},
    078     * and its key and value are equal to this object's key and value.
    079     *
    080     * @param obj  the object to compare to
    081     * @return true if equal key and value
    082     */
    083    @Override
    084    public boolean equals(final Object obj) {
    085        if (obj == this) {
    086            return true;
    087        }
    088        if (!(obj instanceof DefaultKeyValue)) {
    089            return false;
    090        }
    091
    092        final DefaultKeyValue<?, ?> other = (DefaultKeyValue<?, ?>) obj;
    093        return
    094            (getKey() == null ? other.getKey() == null : getKey().equals(other.getKey())) &&
    095            (getValue() == null ? other.getValue() == null : getValue().equals(other.getValue()));
    096    }
    097
    098    /**
    099     * Gets a hashCode compatible with the equals method.
    100     * <p>
    101     * Implemented per API documentation of {@link java.util.Map.Entry#hashCode()},
    102     * however subclasses may override this.
    103     *
    104     * @return a suitable hash code
    105     */
    106    @Override
    107    public int hashCode() {
    108        return (getKey() == null ? 0 : getKey().hashCode()) ^
    109               (getValue() == null ? 0 : getValue().hashCode());
    110    }
    111
    112    /**
    113     * Sets the key.
    114     *
    115     * @param key  the new key
    116     * @return the old key
    117     * @throws IllegalArgumentException if key is this object
    118     */
    119    @Override
    120    public K setKey(final K key) {
    121        if (key == this) {
    122            throw new IllegalArgumentException("DefaultKeyValue may not contain itself as a key.");
    123        }
    124
    125        return super.setKey(key);
    126    }
    127
    128    /**
    129     * Sets the value.
    130     *
    131     * @return the old value of the value
    132     * @param value the new value
    133     * @throws IllegalArgumentException if value is this object
    134     */
    135    @Override
    136    public V setValue(final V value) {
    137        if (value == this) {
    138            throw new IllegalArgumentException("DefaultKeyValue may not contain itself as a value.");
    139        }
    140
    141        return super.setValue(value);
    142    }
    143
    144    /**
    145     * Returns a new {@code Map.Entry} object with key and value from this pair.
    146     *
    147     * @return a MapEntry instance
    148     */
    149    public Map.Entry<K, V> toMapEntry() {
    150        return new DefaultMapEntry<>(this);
    151    }
    152
    153}