Package com.exonum.binding.storage.indices

Class ProofListIndexProxy<E>

java.lang.Object

com.exonum.binding.proxy.AbstractNativeProxy

com.exonum.binding.storage.indices.ProofListIndexProxy<E>

Type Parameters:

E - the type of elements in this list

All Implemented Interfaces:

ListIndex<E>, Iterable<E>

public final class ProofListIndexProxy<E>
extends AbstractNativeProxy
implements ListIndex<E>

A proof list index proxy is a contiguous list of elements, capable of providing cryptographic proofs that it contains a certain element at a particular position. Non-null elements may be added to the end of the list only.

The proof list is implemented as a hash tree (Merkle tree).

The "destructive" methods of the list, i.e., those that change its contents, are specified to throw UnsupportedOperationException if this list 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 list is destroyed. Subsequent use of the closed list 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	Description
void	add(T e)	Adds a new element to the end of the list.
void	addAll(Collection<? extends T> elements)	Adds all elements from the specified collection to this list.
void	clear()	Clears the list.
T	get(long index)	Returns the element at the given index.
T	getLast()	Returns the last element of the list.
String	getName()	Returns the name of this index.
String	getName()	Returns the name of this index.
UncheckedListProof	getProof(long index)	Returns a proof that an element exists at the specified index in this list.
UncheckedListProof	getRangeProof(long from, long to)	Returns a proof that some elements exist in the specified range in this list.
HashCode	getRootHash()	Returns the root hash of the proof list.
boolean	isEmpty()	Returns true if the list is empty, false — otherwise.
Iterator<T>	iterator()	Returns an iterator over the elements of the list.
static <E> ProofListIndexProxy<E>	newInGroupUnsafe(String groupName, byte[] listId, View view, Serializer<E> serializer)	Creates a new list in a collection group with the given name.
static <E> ProofListIndexProxy<E>	newInstance(String name, View view, Serializer<E> serializer)	Creates a new ProofListIndexProxy.
static <E extends com.google.protobuf.MessageLite> ProofListIndexProxy<E>	newInstance(String name, View view, Class<E> elementType)	Creates a new ProofListIndexProxy storing protobuf messages.
void	set(long index, T e)	Replaces the element at the given index of the list with the specified element.
long	size()	Returns the number of elements in the list.
Stream<T>	stream()	Returns a stream of elements in this list.
String	toString()

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 java.lang.Iterable

forEach, spliterator

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

add, addAll, clear, get, getLast, isEmpty, iterator, set, size, stream

Method Detail

newInstance

public static <E extends com.google.protobuf.MessageLite> ProofListIndexProxy<E> newInstance(String name,
                                                                                             View view,
                                                                                             Class<E> elementType)

Creates a new ProofListIndexProxy storing protobuf messages.

Type Parameters:

E - the type of elements in this list; must be a protobuf message that has a public static #parseFrom(byte[]) method

Parameters:

name - a unique alphanumeric non-empty identifier of this list 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.

elementType - the class of elements-protobuf messages

Throws:

IllegalStateException - if the view is not valid

IllegalArgumentException - if the name is empty

newInstance

public static <E> ProofListIndexProxy<E> newInstance(String name,
                                                     View view,
                                                     Serializer<E> serializer)

Creates a new ProofListIndexProxy.

Type Parameters:

E - the type of elements in this list

Parameters:

name - a unique alphanumeric non-empty identifier of this list 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.

serializer - a serializer of elements

Throws:

IllegalStateException - if the view is not valid

IllegalArgumentException - if the name is empty

See Also:

StandardSerializers

newInGroupUnsafe

public static <E> ProofListIndexProxy<E> newInGroupUnsafe(String groupName,
                                                          byte[] listId,
                                                          View view,
                                                          Serializer<E> serializer)

Creates a new list in a collection group with the given name.

See a caveat on index identifiers.

Type Parameters:

E - the type of elements in this list

Parameters:

groupName - a name of the collection group

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

view - a database view

serializer - a serializer of list elements

Returns:

a new list proxy

Throws:

IllegalStateException - if the view is not valid

IllegalArgumentException - if the name or index id is empty

See Also:

StandardSerializers

getProof

public UncheckedListProof getProof(long index)

Returns a proof that an element exists at the specified index in this list.

Parameters:

index - the element index

Throws:

IndexOutOfBoundsException - if the index is invalid

IllegalStateException - if this list is not valid

getRangeProof

public UncheckedListProof getRangeProof(long from,
                                        long to)

Returns a proof that some elements exist in the specified range in this list.

Parameters:

from - the index of the first element

to - the index after the last element

Throws:

IndexOutOfBoundsException - if the range is not valid

IllegalStateException - if this list is not valid

getRootHash

public HashCode getRootHash()

Returns the root hash of the proof list.

Throws:

IllegalStateException - if this list is not valid

getName

public abstract String getName()

Returns the name of this index.

add

public final void add(T e)

Description copied from interface: ListIndex

Adds a new element to the end of the list.

Specified by:

add in interface ListIndex<T>

Parameters:

e - an element to append to the list

addAll

public void addAll(Collection<? extends T> elements)

Description copied from interface: ListIndex

Adds all elements from the specified collection to this list.

If the collection contains an invalid element, this list is not modified.

Specified by:

addAll in interface ListIndex<T>

Parameters:

elements - elements to add to this list

set

public final void set(long index,
                      T e)

Description copied from interface: ListIndex

Replaces the element at the given index of the list with the specified element.

Specified by:

set in interface ListIndex<T>

Parameters:

index - an index of the element to replace

e - an element to add

get

public final T get(long index)

Description copied from interface: ListIndex

Returns the element at the given index.

Specified by:

get in interface ListIndex<T>

Parameters:

index - an index of the element to return

Returns:

an element at the given index

getLast

public final T getLast()

Description copied from interface: ListIndex

Returns the last element of the list.

Specified by:

getLast in interface ListIndex<T>

Returns:

the last element of the list

clear

public final void clear()

Description copied from interface: ListIndex

Clears the list.

Specified by:

clear in interface ListIndex<T>

isEmpty

public final boolean isEmpty()

Description copied from interface: ListIndex

Returns true if the list is empty, false — otherwise.

Specified by:

isEmpty in interface ListIndex<T>

size

public final long size()

Description copied from interface: ListIndex

Returns the number of elements in the list.

Specified by:

size in interface ListIndex<T>

iterator

public final Iterator<T> iterator()

Description copied from interface: ListIndex

Returns an iterator over the elements of the list.

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

Specified by:

iterator in interface Iterable<T>

Specified by:

iterator in interface ListIndex<T>

stream

public Stream<T> stream()

Description copied from interface: ListIndex

Returns a stream of elements in this list. The returned stream is fail-fast and late-binding; the stream can be used as long as the source list is valid.

Any destructive operation on the same Fork this list uses (but not necessarily on this list) will invalidate the corresponding spliterator.

Specified by:

stream in interface ListIndex<T>

getName

public final String getName()

Returns the name of this index.

toString

public String toString()

Overrides:

toString in class Object