com.exonum.binding.storage.indices

Class ProofMapIndexProxy<K,V>

java.lang.Object

com.exonum.binding.proxy.AbstractNativeProxy

com.exonum.binding.storage.indices.ProofMapIndexProxy<K,V>

Type Parameters:

K - the type of keys in this map. Must be 32-byte long in the serialized form

V - the type of values in this map

All Implemented Interfaces:

MapIndex<K,V>

public final class ProofMapIndexProxy<K,V>
extends AbstractNativeProxy
implements MapIndex<K,V>

A ProofMapIndexProxy is an index that maps keys to values. A map cannot contain duplicate keys; each key corresponds to at most one value. This map is capable of providing cryptographic proofs that a certain key is mapped to a particular value or that there are no mapping for the key in the map.

This map is implemented as a Merkle-Patricia tree. It does not permit null keys and values, and requires that keys are 32-byte long.

The "destructive" methods of the map, i.e., the one that change the map contents, are specified to throw UnsupportedOperationException if the map has been created with a read-only database view.

All method arguments are non-null by default.

This class is not thread-safe and and its instances shall not be shared between threads.

When the view goes out of scope, this map is destroyed. Subsequent use of the closed map is prohibited and will result in IllegalStateException.

See Also:

View

Field Summary

Fields inherited from class com.exonum.binding.proxy.AbstractNativeProxy

nativeHandle

Method Summary

Modifier and Type	Method and Description
void	clear() Removes all of the key-value pairs from the map.
boolean	containsKey(K key) Returns true if this map contains a mapping for the specified key.
java.util.Iterator<MapEntry<K,V>>	entries() Returns an iterator over the map entries.
V	get(K key) Returns the value associated with the specified key, or null if there is no mapping for the key.
java.lang.String	getName() Returns the name of this index.
java.lang.String	getName() Returns the name of this index.
com.exonum.binding.common.proofs.map.UncheckedMapProof	getProof(java.util.Collection<? extends K> keys) Returns a proof that there are values mapped to the specified keys or that there are no such mappings.
com.exonum.binding.common.proofs.map.UncheckedMapProof	getProof(K key, K... otherKeys) Returns a proof that there are values mapped to the specified keys or that there are no such mappings.
com.exonum.binding.common.hash.HashCode	getRootHash() Returns the root hash of the underlying Merkle-Patricia tree.
java.util.Iterator<K>	keys() Returns an iterator over the map keys in lexicographical order.
static <K,V> ProofMapIndexProxy<K,V>	newInGroupUnsafe(java.lang.String groupName, byte[] mapId, View view, com.exonum.binding.common.serialization.Serializer<K> keySerializer, com.exonum.binding.common.serialization.Serializer<V> valueSerializer) Creates a new proof map in a collection group with the given name.
static <K,V> ProofMapIndexProxy<K,V>	newInstance(java.lang.String name, View view, com.exonum.binding.common.serialization.Serializer<K> keySerializer, com.exonum.binding.common.serialization.Serializer<V> valueSerializer) Creates a ProofMapIndexProxy.
void	put(K key, V value) Puts a new key-value pair into the map.
void	putAll(java.util.Map<? extends K,? extends V> sourceMap) Puts all key-value pairs from the given map into this map.
void	remove(K key) Removes the value mapped to the specified key from the map.
java.lang.String	toString()
java.util.Iterator<V>	values() Returns an iterator over the map values in lexicographical order of keys.

Methods inherited from class com.exonum.binding.proxy.AbstractNativeProxy

getNativeHandle, isValidHandle

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.exonum.binding.storage.indices.MapIndex

isEmpty

Method Detail

newInstance

public static <K,V> ProofMapIndexProxy<K,V> newInstance(java.lang.String name,
                                                        View view,
                                                        com.exonum.binding.common.serialization.Serializer<K> keySerializer,
                                                        com.exonum.binding.common.serialization.Serializer<V> valueSerializer)

Creates a ProofMapIndexProxy.

Type Parameters:

K - the type of keys in the map

V - the type of values in the map

Parameters:

name - a unique alphanumeric non-empty identifier of this map in the underlying storage: [a-zA-Z0-9_]

view - a database view. Must be valid. If a view is read-only, "destructive" operations are not permitted.

keySerializer - a serializer of keys, must always produce 32-byte long values

valueSerializer - a serializer of values

Throws:

java.lang.IllegalStateException - if the view is not valid

java.lang.IllegalArgumentException - if the name is empty

See Also:

StandardSerializers

newInGroupUnsafe

public static <K,V> ProofMapIndexProxy<K,V> newInGroupUnsafe(java.lang.String groupName,
                                                             byte[] mapId,
                                                             View view,
                                                             com.exonum.binding.common.serialization.Serializer<K> keySerializer,
                                                             com.exonum.binding.common.serialization.Serializer<V> valueSerializer)

Creates a new proof map in a collection group with the given name.

See a caveat on index identifiers.

Type Parameters:

K - the type of keys in the map

V - the type of values in the map

Parameters:

groupName - a name of the collection group

mapId - an identifier of this collection in the group, see the caveats

view - a database view

keySerializer - a serializer of keys, must always produce 32-byte long values

valueSerializer - a serializer of values

Returns:

a new map proxy

Throws:

java.lang.IllegalStateException - if the view is not valid

java.lang.IllegalArgumentException - if the name or index id is empty

See Also:

StandardSerializers

containsKey

public boolean containsKey(K key)

Description copied from interface: MapIndex

Returns true if this map contains a mapping for the specified key.

Specified by:

containsKey in interface MapIndex<K,V>

put

public void put(K key,
                V value)

Puts a new key-value pair into the map. If this map already contains a mapping for the specified key, overwrites the old value with the specified value.

Specified by:

put in interface MapIndex<K,V>

Parameters:

key - a proof map key, must be 32-byte long when serialized

value - a storage value to associate with the key

Throws:

java.lang.IllegalStateException - if this map is not valid

java.lang.IllegalArgumentException - if the size of the key is not 32 bytes

java.lang.UnsupportedOperationException - if this map is read-only

putAll

public void putAll(java.util.Map<? extends K,? extends V> sourceMap)

Description copied from interface: MapIndex

Puts all key-value pairs from the given map into this map. Equivalent to a sequence of individual MapIndex.put(K, V) operations.

Specified by:

putAll in interface MapIndex<K,V>

Parameters:

sourceMap - a map to put into this one

get

public V get(K key)

Description copied from interface: MapIndex

Returns the value associated with the specified key, or null if there is no mapping for the key.

Specified by:

get in interface MapIndex<K,V>

Parameters:

key - a storage key

Returns:

the value mapped to the specified key, or null if this map contains no mapping for the key.

getProof

public com.exonum.binding.common.proofs.map.UncheckedMapProof getProof(K key,
                                                                       K... otherKeys)

Returns a proof that there are values mapped to the specified keys or that there are no such mappings.

Parameters:

key - a proof map key which might be mapped to some value, must be 32-byte long

otherKeys - other proof map keys which might be mapped to some values, each must be 32-byte long

Throws:

java.lang.IllegalStateException - if this map is not valid

java.lang.IllegalArgumentException - if the size of any of the keys is not 32 bytes

getProof

public com.exonum.binding.common.proofs.map.UncheckedMapProof getProof(java.util.Collection<? extends K> keys)

Returns a proof that there are values mapped to the specified keys or that there are no such mappings.

Parameters:

keys - proof map keys which might be mapped to some values, each must be 32-byte long

Throws:

java.lang.IllegalStateException - if this map is not valid

java.lang.IllegalArgumentException - if the size of any of the keys is not 32 bytes or keys collection is empty

getRootHash

public com.exonum.binding.common.hash.HashCode getRootHash()

Returns the root hash of the underlying Merkle-Patricia tree.

Throws:

java.lang.IllegalStateException - if this map is not valid

remove

public void remove(K key)

Description copied from interface: MapIndex

Removes the value mapped to the specified key from the map. If there is no such mapping, has no effect.

Specified by:

remove in interface MapIndex<K,V>

Parameters:

key - a storage key

keys

public java.util.Iterator<K> keys()

Description copied from interface: MapIndex

Returns an iterator over the map keys in lexicographical order.

Any destructive operation on the same Fork this map uses (but not necessarily on this map) will invalidate the iterator.

Specified by:

keys in interface MapIndex<K,V>

values

public java.util.Iterator<V> values()

Description copied from interface: MapIndex

Returns an iterator over the map values in lexicographical order of keys.

Any destructive operation on the same Fork this map uses (but not necessarily on this map) will invalidate the iterator.

Specified by:

values in interface MapIndex<K,V>

entries

public java.util.Iterator<MapEntry<K,V>> entries()

Description copied from interface: MapIndex

Returns an iterator over the map entries. The entries are ordered by keys in lexicographical order.

Any destructive operation on the same Fork this map uses (but not necessarily on this map) will invalidate the iterator.

Specified by:

entries in interface MapIndex<K,V>

clear

public void clear()

Description copied from interface: MapIndex

Removes all of the key-value pairs from the map. The map will be empty after this method returns.

Specified by:

clear in interface MapIndex<K,V>

getName

public java.lang.String getName()

Returns the name of this index.

getName

public final java.lang.String getName()

Returns the name of this index.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object