Class ProofListIndexProxy<E>

java.lang.Object
com.exonum.binding.core.proxy.AbstractNativeProxy
com.exonum.binding.core.storage.indices.ProofListIndexProxy<E>
Type Parameters:
E - the type of elements in this list
All Implemented Interfaces:
HashableIndex, ListIndex<E>, StorageIndex, java.lang.Iterable<E>

public final class ProofListIndexProxy<E>
extends AbstractNativeProxy
implements ListIndex<E>, HashableIndex
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 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 list is destroyed. Subsequent use of the closed list is prohibited and will result in IllegalStateException.

See Also:
Access
  • Field Summary

    Fields inherited from class com.exonum.binding.core.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​(java.util.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.
    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.
    T getLast()
    Returns the last element of the list.
    ListProof getProof​(long index)
    Returns a proof of either existence or absence of an element at the specified index in this list.
    ListProof getRangeProof​(long from, long to)
    Returns a proof of either existence or absence of some elements in the specified range in this list.
    boolean isEmpty()
    Returns true if the list is empty, false — otherwise.
    java.util.Iterator<T> iterator()
    Returns an iterator over the elements of the list.
    static <E> ProofListIndexProxy<E> newInstance​(IndexAddress address, AbstractAccess access, Serializer<E> serializer)
    Creates a new ProofListIndexProxy.
    T removeLast()
    Removes the last element of the list and returns it.
    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.
    java.util.stream.Stream<T> stream()
    Returns a stream of elements in this list.
    java.lang.String toString()  
    void truncate​(long newSize)
    Truncates the list, reducing its size to newSize.

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

    forEach, spliterator

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

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

    Methods inherited from interface com.exonum.binding.core.storage.indices.StorageIndex

    getAddress, getName
  • Method Details

    • newInstance

      public static <E> ProofListIndexProxy<E> newInstance​(IndexAddress address, AbstractAccess access, Serializer<E> serializer)
      Creates a new ProofListIndexProxy.

      Warning: do not invoke this method from service code, use Access.getProofList(IndexAddress, Serializer).

      Type Parameters:
      E - the type of elements in this list
      Parameters:
      address - an index address
      access - a database access. Must be valid. If an access is read-only, "destructive" operations are not permitted.
      serializer - a serializer of elements
      Throws:
      java.lang.IllegalStateException - if the access is not valid
      java.lang.IllegalArgumentException - if the name is empty
      See Also:
      StandardSerializers
    • getProof

      public ListProof getProof​(long index)
      Returns a proof of either existence or absence of an element at the specified index in this list.
      Parameters:
      index - the element index
      Throws:
      java.lang.IndexOutOfBoundsException - if the index is invalid
      java.lang.IllegalStateException - if this list is not valid
      See Also:
      Blockchain Proofs
    • getRangeProof

      public ListProof getRangeProof​(long from, long to)
      Returns a proof of either existence or absence of some elements in the specified range in this list. If some elements are present in the list, but some — are not (i.e., the requested range exceeds its size), a proof of absence is returned.
      Parameters:
      from - the index of the first element
      to - the index after the last element
      Throws:
      java.lang.IndexOutOfBoundsException - if the range is not valid
      java.lang.IllegalStateException - if this list is not valid
    • getIndexHash

      public HashCode 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 interface HashableIndex
    • 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​(java.util.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
    • removeLast

      public T removeLast()
      Description copied from interface: ListIndex
      Removes the last element of the list and returns it.
      Specified by:
      removeLast in interface ListIndex<T>
      Returns:
      the last element of the list.
    • truncate

      public void truncate​(long newSize)
      Description copied from interface: ListIndex
      Truncates the list, reducing its size to newSize.

      If newSize < size(), keeps the first newSize elements, removing the rest. If newSize >= size(), has no effect.

      Specified by:
      truncate in interface ListIndex<T>
      Parameters:
      newSize - the maximum number of elements to keep
    • 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 java.util.Iterator<T> iterator()
      Description copied from interface: ListIndex
      Returns an iterator over the elements of the list.
      Specified by:
      iterator in interface java.lang.Iterable<T>
      Specified by:
      iterator in interface ListIndex<T>
    • stream

      public java.util.stream.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.
      Specified by:
      stream in interface ListIndex<T>
    • getAddress

      public IndexAddress 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 interface StorageIndex
    • toString

      public java.lang.String toString()
      Overrides:
      toString in class java.lang.Object