Class ProofMapIndexProxy<K,V>
- Type Parameters:
K
- the type of keys in this mapV
- the type of values in this map
- All Implemented Interfaces:
HashableIndex
,MapIndex<K,V>
,StorageIndex
public final class ProofMapIndexProxy<K,V> extends AbstractNativeProxy implements MapIndex<K,V>, HashableIndex
This map is implemented as a Merkle-Patricia tree. It does not permit null keys and values.
The Merkle-Patricia tree backing the proof map uses internal 32-byte keys. The tree balance relies on the internal keys being uniformly distributed.
Key hashing in proof maps
By default, when creating the proof map using method
#newInstance
,
the user keys are converted into internal keys through hashing. This allows to use keys of
an arbitrary size and ensures the balance of the internal tree.
It is also possible to create a proof map that will not hash keys with method
#newInstanceNoKeyHashing
. In this mode the map will use the user keys as internal
tree keys. Such mode of operation is appropriate iff all of the following conditions
hold:
- All keys are 32-byte long
- The keys are uniformly distributed
- The keys come from a trusted source that cannot influence their distribution and affect the tree balance.
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 access.
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 access goes out of scope, this map is destroyed. Subsequent use of the closed map
is prohibited and will result in IllegalStateException
.
- See Also:
Access
-
Field Summary
-
Method Summary
Modifier and Type Method 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, ornull
if there is no mapping for the key.IndexAddress
getAddress()
Returns the index address: its identifier in the database.HashCode
getIndexHash()
Returns the index hash which represents the complete state of this index.MapProof
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.MapProof
getProof(K key, K... otherKeys)
Returns a proof that there are values mapped to the specified keys or that there are no such mappings.java.util.Iterator<K>
keys()
Returns an iterator over the map keys.static <K, V> ProofMapIndexProxy<K,V>
newInstance(IndexAddress address, AbstractAccess access, Serializer<K> keySerializer, Serializer<V> valueSerializer)
Creates a ProofMapIndexProxy.static <K, V> ProofMapIndexProxy<K,V>
newInstanceNoKeyHashing(IndexAddress address, AbstractAccess access, Serializer<K> keySerializer, Serializer<V> valueSerializer)
Creates a ProofMapIndexProxy that uses non-hashed keys.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.Methods inherited from class com.exonum.binding.core.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.core.storage.indices.StorageIndex
getAddress, getName
-
Method Details
-
newInstance
public static <K, V> ProofMapIndexProxy<K,V> newInstance(IndexAddress address, AbstractAccess access, Serializer<K> keySerializer, Serializer<V> valueSerializer)Creates a ProofMapIndexProxy.Warning: do not invoke this method from service code, use
Access.getProofMap(IndexAddress, Serializer, Serializer)
.- Type Parameters:
K
- the type of keys in the mapV
- the type of values in the map- Parameters:
address
- an index addressaccess
- a database access. Must be valid. If an access is read-only, "destructive" operations are not permitted.keySerializer
- a serializer of keysvalueSerializer
- a serializer of values- Throws:
java.lang.IllegalStateException
- if the access is not validjava.lang.IllegalArgumentException
- if the name is empty- See Also:
StandardSerializers
-
newInstanceNoKeyHashing
public static <K, V> ProofMapIndexProxy<K,V> newInstanceNoKeyHashing(IndexAddress address, AbstractAccess access, Serializer<K> keySerializer, Serializer<V> valueSerializer)Creates a ProofMapIndexProxy that uses non-hashed keys. Requires that keys are 32-byte long.Warning: do not invoke this method from service code, use
Access.getRawProofMap(IndexAddress, Serializer, Serializer)
.- Type Parameters:
K
- the type of keys in the mapV
- the type of values in the map- Parameters:
address
- an index addressaccess
- a database access. Must be valid. If an access is read-only, "destructive" operations are not permitted.keySerializer
- a serializer of keys, must always produce 32-byte long valuesvalueSerializer
- a serializer of values- Throws:
java.lang.IllegalStateException
- if the access is not validjava.lang.IllegalArgumentException
- if the name is empty- See Also:
StandardSerializers
-
containsKey
Description copied from interface:MapIndex
Returns true if this map contains a mapping for the specified key.- Specified by:
containsKey
in interfaceMapIndex<K,V>
-
put
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 interfaceMapIndex<K,V>
- Parameters:
key
- a proof map keyvalue
- a storage value to associate with the key- Throws:
java.lang.IllegalStateException
- if this map is not validjava.lang.IllegalArgumentException
- if the size of the key is not 32 bytes (in case of a proof map that uses non-hashed keys)java.lang.UnsupportedOperationException
- if this map is read-only
-
putAll
Description copied from interface:MapIndex
Puts all key-value pairs from the given map into this map. Equivalent to a sequence of individualMapIndex.put(K, V)
operations. -
get
Description copied from interface:MapIndex
Returns the value associated with the specified key, ornull
if there is no mapping for the key. -
getProof
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 valueotherKeys
- other proof map keys which might be mapped to some values- Throws:
java.lang.IllegalStateException
- if this map is not validjava.lang.IllegalArgumentException
- if the size of any of the keys is not 32 bytes (in case of a proof map that uses non-hashed keys)- See Also:
- Blockchain Proofs
-
getProof
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- Throws:
java.lang.IllegalStateException
- if this map is not validjava.lang.IllegalArgumentException
- if the size of any of the keys is not 32 bytes (in case of a proof map that uses non-hashed keys) or keys collection is empty- See Also:
- Blockchain Proofs
-
getIndexHash
Description copied from interface:HashableIndex
Returns the index hash which represents the complete state of this index. Any modifications to the stored entries affect the index hash.How index hash is computed depends on the index data structure implementation.
- Specified by:
getIndexHash
in interfaceHashableIndex
-
remove
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. -
keys
Description copied from interface:MapIndex
Returns an iterator over the map keys. The keys are ordered in lexicographical order. -
values
Description copied from interface:MapIndex
Returns an iterator over the map values. The values are ordered in lexicographical order of keys. -
entries
Description copied from interface:MapIndex
Returns an iterator over the map entries. The entries are ordered by keys in lexicographical order. -
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. -
getAddress
Description copied from interface:StorageIndex
Returns the index address: its identifier in the database.Please note that the implementations may return either relative or absolute address. The address is not required to be equal to the one passed to the index constructor.
- Specified by:
getAddress
in interfaceStorageIndex
-
toString
public java.lang.String toString()- Overrides:
toString
in classjava.lang.Object
-