agi.foundation.infrastructure.threading

(agi.foundation.core-2024r3.jar)

Class PersistentDictionary<TKey,TValue>

java.lang.Object

agi.foundation.infrastructure.threading.PersistentDictionaryNode<TKey,TValue>

agi.foundation.infrastructure.threading.PersistentDictionary<TKey,TValue>

Type Parameters:

TKey - The type of the key in the dictionary.

TValue - The type of the value in the dictionary.

All Implemented Interfaces:

Iterable<Map.Entry<TKey,TValue>>

public abstract class PersistentDictionary<TKey,TValue>
extends PersistentDictionaryNode<TKey,TValue>
implements Iterable<Map.Entry<TKey,TValue>>

A dictionary that maps keys to values and is persistent. Persistence means that an instance of this type, once created, cannot be changed. Methods like #add(TKey,TValue) return a new instance instead of modifying the one on which they are called. The new instance shares much of its structure with the original, so modifications are still efficient. This class is useful in multithreaded applications. An instance of this type cannot be created directly. The PersistentDictionary.Empty field contains an empty instance with which to start.

Field Summary

Fields

Modifier and Type	Field and Description
static PersistentDictionary	Empty An empty dictionary.

Constructor Summary

Constructors

Constructor and Description
PersistentDictionary()

Method Summary

Modifier and Type	Method and Description
PersistentDictionary<TKey,TValue>	add(TKey key, TValue value) Adds a specified key/value pair to the dictionary.
abstract PersistentDictionary<TKey,TValue>	add(TKey key, TValue value, PersistentDictionaryAddResult[] result) Adds a specified key/value pair to the dictionary, and returns a value indicating whether the key was newly added to the dictionary or it already existed and the value was replaced.
boolean	containsKey(TKey key) Determines if a specified key exists in the dictionary.
TValue	get(TKey key) Gets the value corresponding to the specified key.
abstract int	getCount() Gets the number of elements in this dictionary.
Collection<TKey>	getKeys() Gets a read-only collection of keys in the dictionary.
Collection<TValue>	getValues() Gets a read-only collection of values in the dictionary.
abstract Iterator<Map.Entry<TKey,TValue>>	iterator() Gets an enumerator for enumerating over the key/value pairs in the dictionary.
abstract PersistentDictionary<TKey,TValue>	remove(TKey key) Removes an item with the specified key from the dictionary.
abstract boolean	tryGetValue(TKey key, TValue[] value) Gets the value in the dictionary corresponding to the given key.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

Empty

@Nonnull
public static final PersistentDictionary Empty

An empty dictionary.

Constructor Detail

PersistentDictionary

public PersistentDictionary()

Method Detail

getCount

public abstract int getCount()

Gets the number of elements in this dictionary.

add

@Nonnull
public final PersistentDictionary<TKey,TValue> add(TKey key,
                                                             TValue value)

Adds a specified key/value pair to the dictionary. If a value with the specified key already exists, it is replaced. This method does not modify the dictionary on which it is called but instead returns a new dictionary containing the added element.

Parameters:

key - The key of the item to add to the dictionary.

value - The value of the item to add to the dictionary.

Returns:

A new persistent dictionary containing the specified key/value pair.

get

public final TValue get(TKey key)

Gets the value corresponding to the specified key. Throws KeyNotFoundException if the key does not exist in the dictionary.

Parameters:

key - The key to find in the dictionary.

Returns:

The value in the dictionary corresponding to the given key.

getKeys

@Nonnull
public final Collection<TKey> getKeys()

Gets a read-only collection of keys in the dictionary.

getValues

@Nonnull
public final Collection<TValue> getValues()

Gets a read-only collection of values in the dictionary.

containsKey

public final boolean containsKey(TKey key)

Determines if a specified key exists in the dictionary.

Parameters:

key - The key to find in the dictionary.

Returns:

true if the key exists in the dictionary; otherwise false.

add

@Nonnull
public abstract PersistentDictionary<TKey,TValue> add(TKey key,
                                                                TValue value,
                                                                @Nonnull
                                                                PersistentDictionaryAddResult[] result)

Adds a specified key/value pair to the dictionary, and returns a value indicating whether the key was newly added to the dictionary or it already existed and the value was replaced. This method does not modify the dictionary on which it is called but instead returns a new dictionary containing the added element.

Parameters:

key - The key of the item to add to the dictionary.

value - The value of the item to add to the dictionary.

result - On input, an array with one element. On return, the array is populated with a value indicating whether the key was newly added to the dictionary or it already existed and the value was replaced.

Returns:

A new persistent dictionary containing the specified key/value pair.

tryGetValue

public abstract boolean tryGetValue(TKey key,
                                    @Nonnull
                                    TValue[] value)

Gets the value in the dictionary corresponding to the given key.

Parameters:

key - The key of the item to retrieve from the dictionary.

value - On input, an array with one element. On return, the array is populated with the value corresponding to the key.

Returns:

true if the key was found in the dictionary; otherwise false.

remove

@Nonnull
public abstract PersistentDictionary<TKey,TValue> remove(TKey key)

Removes an item with the specified key from the dictionary. This method does not modify the instance on which it is called but instead returns a new instance with the element removed. If the key does not exist in the dictionary, this method returns the instance on which it is called.

Parameters:

key - The key to remove from the dictionary.

Returns:

A new instance without the specified key, or the same instance on which it is called if the key does not exist in the dictionary.

iterator

public abstract Iterator<Map.Entry<TKey,TValue>> iterator()

Gets an enumerator for enumerating over the key/value pairs in the dictionary.

Specified by:

iterator in interface Iterable<Map.Entry<TKey,TValue>>

Returns:

The enumerator.