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}