Module io.github.brantunger.unruly.core

Package io.github.brantunger.unruly.api

Class FactMap<T extends @Nullable Object>

java.lang.Object

io.github.brantunger.unruly.api.FactMap<T>

Type Parameters:

T - The object/value type of the facts

All Implemented Interfaces:

FactStore<T>, Map<String,@Nullable FactReference<T>>

public class FactMap<T extends @Nullable Object>
extends Object
implements FactStore<T>, Map<String,@Nullable FactReference<T>>

The built-in FactStore: a map from each fact's name to its FactReference, backed by a HashMap.

Every way of adding a fact rejects a null name, and rejects a key that differs from the name of the fact stored under it, with IllegalArgumentException. That includes Map.Entry.setValue(V) on an entrySet() entry and replaceAll(java.util.function.BiFunction<? super java.lang.String, ? super io.github.brantunger.unruly.api.FactReference<T>, ? extends io.github.brantunger.unruly.api.FactReference<T>>). The varargs constructor also rejects two facts with the same name. getValue(java.lang.String) rejects a null name too, while get(java.lang.Object), containsKey(java.lang.Object) and remove(java.lang.Object) follow the Map contract: a null key is never stored, so they find nothing under it.

A FactMap is a Map as well as a FactStore, so a FactMap variable has every Map method. asMap() returns a read-only view of it.

equals, hashCode and toString follow the Map contract: two maps holding equal facts under the same names are equal, whatever their implementation.

Threads: not thread-safe, like the HashMap it wraps. Build one for each run, and don't change it while a run reads it.

See Also:

• Facts
• Reusing and sharing a store

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Constructor Summary

Constructors

Constructor	Description
FactMap()	Construct a new empty FactMap.
FactMap(FactReference<T>... facts)	Construct a new FactMap from an array of existing FactReference objects
FactMap(Map<String,? extends @Nullable FactReference<T>> facts)	Construct a new FactMap from a map of facts.

Method Summary

Modifier and Type	Method	Description
Map<String,@Nullable FactReference<T>>	asMap()	Returns a read-only view of the facts, keyed by name.
void	clear()
boolean	containsKey(@Nullable Object key)
boolean	containsValue(@Nullable Object value)
Set<Map.Entry<String,@Nullable FactReference<T>>>	entrySet()	Returns a view of the entries backed by this map.
boolean	equals(@Nullable Object o)	Compares by entries, as the Map contract requires: equal to any Map, of any implementation, holding equal facts under the same names.
@Nullable FactReference<T>	get(@Nullable Object key)
@Nullable T	getValue(String name)	Gets the value of the fact stored under a name.
int	hashCode()
boolean	isEmpty()
Set<String>	keySet()
@Nullable FactReference<T>	put(FactReference<T> fact)	Stores a FactReference under its name.
@Nullable FactReference<T>	put(String key, @Nullable FactReference<T> fact)	Stores fact under key.
void	putAll(Map<? extends String,? extends @Nullable FactReference<T>> map)	Copies every entry of map into this map.
@Nullable FactReference<T>	remove(@Nullable Object key)
void	replaceAll(BiFunction<? super String,? super @Nullable FactReference<T>,? extends @Nullable FactReference<T>> function)	Replaces every fact with the function's result.
void	setValue(String name, T obj)	Sets the value of the named fact by storing a new Fact.
int	size()
String	toString()
Collection<@Nullable FactReference<T>>	values()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace

Constructor Details

FactMap

public FactMap()

Construct a new empty FactMap.

FactMap

public FactMap(Map<String,? extends @Nullable FactReference<T>> facts)

Construct a new FactMap from a map of facts. The map itself is copied, and the FactReference objects are shared with it. Changing a value through setValue(java.lang.String, T) affects only this map.

Parameters:

facts - The fact map to construct the facts from. Its values may be any FactReference implementation, such as a Map<String, Fact<T>>.

Throws:

IllegalArgumentException - if a key is null or differs from its fact's name

NullPointerException - if facts is null

FactMap

@SafeVarargs
public FactMap(FactReference<T>... facts)

Construct a new FactMap from an array of existing FactReference objects

Parameters:

facts - The facts to construct a new FactMap with

Throws:

IllegalArgumentException - if a fact's name is null, or two facts share a name

NullPointerException - if facts or any element is null

Method Details

getValue

public @Nullable T getValue(String name)

Gets the value of the fact stored under a name.

Specified by:

getValue in interface FactStore<T extends @Nullable Object>

Parameters:

name - The fact's name

Returns:

The value, or null either if there is no fact with that name or if the fact's value is null. To tell the two apart, ask FactStore.asMap() whether it containsKey(name).

Throws:

IllegalArgumentException - if name is null

setValue

public void setValue(String name,
 T obj)

Sets the value of the named fact by storing a new Fact. An existing FactReference is replaced, never updated in place, so a FactMap copied from another, or built from the same Fact objects, is not changed by this call. A reference previously obtained from get(java.lang.Object) keeps its old value.

Specified by:

setValue in interface FactStore<T extends @Nullable Object>

Parameters:

name - The name of the fact

obj - The new value

Throws:

IllegalArgumentException - if name is null

put

public @Nullable FactReference<T> put(FactReference<T> fact)

Stores a FactReference under its name.

Specified by:

put in interface FactStore<T extends @Nullable Object>

Parameters:

fact - The FactReference to store

Returns:

The previous FactReference stored under the fact's name, or null if there was none, as with Map.put(Object, Object)

Throws:

IllegalArgumentException - if the fact's name is null

NullPointerException - if fact is null

asMap

public Map<String,@Nullable FactReference<T>> asMap()

Description copied from interface: FactStore

Returns a read-only view of the facts, keyed by name. The view follows later changes to the store. A run copies its entries once, when it starts, binding each fact's value to its key.

Specified by:

asMap in interface FactStore<T extends @Nullable Object>

Returns:

An unmodifiable map of each name to its FactReference; must not be null: a null one fails the run with a NullPointerException

size

public int size()

Specified by:

size in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

containsKey

public boolean containsKey(@Nullable Object key)

Specified by:

containsKey in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

containsValue

public boolean containsValue(@Nullable Object value)

Specified by:

containsValue in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

get

public @Nullable FactReference<T> get(@Nullable Object key)

Specified by:

get in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

put

public @Nullable FactReference<T> put(String key,
 @Nullable FactReference<T> fact)

Stores fact under key.

Specified by:

put in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

Parameters:

key - The fact's name

fact - The fact. Unless it is null, its own name must equal key.

Returns:

The fact previously stored under key, or null if there was none

Throws:

IllegalArgumentException - if key is null or differs from the fact's name

remove

public @Nullable FactReference<T> remove(@Nullable Object key)

Specified by:

remove in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

putAll

public void putAll(Map<? extends String,? extends @Nullable FactReference<T>> map)

Copies every entry of map into this map. Every entry is checked like put(String, FactReference) before any is stored, so an invalid one leaves this map unchanged.

Specified by:

putAll in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

Parameters:

map - The facts to add

Throws:

IllegalArgumentException - if a key is null or differs from its fact's name

NullPointerException - if map is null

clear

public void clear()

Specified by:

clear in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

keySet

public Set<String> keySet()

Specified by:

keySet in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

values

public Collection<@Nullable FactReference<T>> values()

Specified by:

values in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

replaceAll

public void replaceAll(BiFunction<? super String,? super @Nullable FactReference<T>,? extends @Nullable FactReference<T>> function)

Replaces every fact with the function's result. Every result is checked like put(String, FactReference) before any is stored, so an invalid one leaves this map unchanged.

Specified by:

replaceAll in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

Parameters:

function - Computes the replacement for each name and fact

Throws:

IllegalArgumentException - if a result's name differs from its key

entrySet

public Set<Map.Entry<String,@Nullable FactReference<T>>> entrySet()

Returns a view of the entries backed by this map. Removing through the view works as usual, and an entry's Map.Entry.setValue(V) is checked like put(String, FactReference), so it can't store a fact under a key that differs from the fact's name.

Specified by:

entrySet in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

Returns:

A checked view of the entries

equals

public boolean equals(@Nullable Object o)

Compares by entries, as the Map contract requires: equal to any Map, of any implementation, holding equal facts under the same names.

Specified by:

equals in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

Overrides:

equals in class Object

Parameters:

o - The object to compare with

Returns:

true if o is a Map with the same entries

hashCode

public int hashCode()

Specified by:

hashCode in interface Map<String,@Nullable FactReference<T extends @Nullable Object>>

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object