de.unkrig.commons.lang.protocol.Mapping Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of de-unkrig-commons Show documentation
Show all versions of de-unkrig-commons Show documentation
A versatile Java(TM) library that implements many useful container and utility classes.
/*
* de.unkrig.commons - A general-purpose Java class library
*
* Copyright (c) 2014, Arno Unkrig
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
* following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the
* following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
* following disclaimer in the documentation and/or other materials provided with the distribution.
* 3. The name of the author may not be used to endorse or promote products derived from this software without
* specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
* TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
* THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
package de.unkrig.commons.lang.protocol;
import java.util.Collection;
import java.util.Map;
import java.util.Set;
import de.unkrig.commons.nullanalysis.NotNullByDefault;
import de.unkrig.commons.nullanalysis.Nullable;
/**
* A map that computes a value only when {@link #get(Object)} is invoked.
* Consequently, in contrast with {@link Map}, it has no specific {@link Map#size() size()}, and thus no {@link
* Map#entrySet() entrySet()}, {@link Map#keySet() keySet()} and {@link Map#values() values()} set.
* Also the modifying operations ({@link Map#put(Object, Object) put}, {@link Map#putAll(Map) putAll}, {@link
* Map#remove(Object) remove} and {@link Map#clear() clear}) are all missing, because a {@link Mapping} is not changed
* by "putting" key-value-pairs into it.
*
* Actually {@link Map} should extend {@link Mapping}, but it doesn't - thus there are the {@link #asMap()} and
* {@link Mappings#fromMap(Map)} helper methods.
*
*
* The relationship between {@link Mapping} and {@link Map} is very much like that between {@link Predicate} and
* {@link Collection}.
*
*
* IMPORTANT NOTICE:
*
* When using this type in a variable, parameter or field declaration, never write:
*
* Mapping<key-type, value-type>
*
* , but always:
*
* Mapping<? super key-type, ? extends value-type>
*
* That way many type conversions are possible which otherwise aren't.
*
*
* @param The 'key' type
* @param The 'value' type
*/
public abstract
class Mapping {
/** @see Map#containsKey(Object) */
public abstract boolean
containsKey(@Nullable Object key);
/** @see Map#get(Object) */
@Nullable public abstract V
get(@Nullable Object key);
/**
* Returns a proxy {@link Map} for a {@link Mapping} where all methods declared by {@link Map} but not by
* {@link Mapping} throw an {@link UnsupportedOperationException}.
*/
@NotNullByDefault(false) public final Map
asMap() {
return new Map() {
@Override public boolean containsKey(Object key) { return Mapping.this.containsKey(key); }
@Override public V get(Object key) { return Mapping.this.get(key); }
// SUPPRESS CHECKSTYLE LineLength:16
@Override public int size() { throw new UnsupportedOperationException("size"); }
@Override public boolean isEmpty() { throw new UnsupportedOperationException("isEmpty"); }
@Override public boolean containsValue(Object value) { throw new UnsupportedOperationException("containsValue"); }
@Override public V put(K key, V value) { throw new UnsupportedOperationException("put"); }
@Override public V remove(Object key) { throw new UnsupportedOperationException("remove"); }
@Override public void putAll(Map t) { throw new UnsupportedOperationException("putAll"); }
@Override public void clear() { throw new UnsupportedOperationException("clear"); }
@Override public Set keySet() { throw new UnsupportedOperationException("keySet"); }
@Override public Collection values() { throw new UnsupportedOperationException("values"); }
@Override public Set> entrySet() { throw new UnsupportedOperationException("entrySet"); }
@Override public boolean equals(Object o) { return o == this; }
@Override public int hashCode() { return System.identityHashCode(this); }
@Override public String toString() { return "Mapping"; }
@Override protected Object clone() throws CloneNotSupportedException { throw new CloneNotSupportedException("Mapping"); }
};
}
}