Package com.exonum.binding.storage.indices

Class ProofListIndexProxy<E>

  • Type Parameters:
    E - the type of elements in this list
    All Implemented Interfaces:
    ListIndex<E>, java.lang.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

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      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.
      T getLast()
      Returns the last element of the list.
      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.list.UncheckedListProof getProof​(long index)
      Returns a proof that an element exists at the specified index in this list.
      com.exonum.binding.common.proofs.list.UncheckedListProof getRangeProof​(long from, long to)
      Returns a proof that some elements exist in the specified range in this list.
      com.exonum.binding.common.hash.HashCode getRootHash()
      Returns the root hash of the proof 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> newInGroupUnsafe​(java.lang.String groupName, byte[] listId, View view, com.exonum.binding.common.serialization.Serializer<E> serializer)
      Creates a new list in a collection group with the given name.
      static <E> ProofListIndexProxy<E> newInstance​(java.lang.String name, View view, com.exonum.binding.common.serialization.Serializer<E> serializer)
      Creates a new ProofListIndexProxy.
      static <E extends com.google.protobuf.MessageLite>
      ProofListIndexProxy<E>      		 newInstance​(java.lang.String name, View view, java.lang.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.
      java.util.stream.Stream<T> stream()
      Returns a stream of elements in this list.
      java.lang.String toString()  

      • 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

    • Method Detail

      • newInstance

        public static <E extends com.google.protobuf.MessageLite> ProofListIndexProxy<E> newInstance​(java.lang.String name,
                                                                                             View view,
                                                                                             java.lang.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:
        java.lang.IllegalStateException - if the view is not valid
        java.lang.IllegalArgumentException - if the name is empty

      • newInstance

        public static <E> ProofListIndexProxy<E> newInstance​(java.lang.String name,
                                                     View view,
                                                     com.exonum.binding.common.serialization.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:
        java.lang.IllegalStateException - if the view is not valid
        java.lang.IllegalArgumentException - if the name is empty
        See Also:
        StandardSerializers

      • newInGroupUnsafe

        public static <E> ProofListIndexProxy<E> newInGroupUnsafe​(java.lang.String groupName,
                                                          byte[] listId,
                                                          View view,
                                                          com.exonum.binding.common.serialization.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:
        java.lang.IllegalStateException - if the view is not valid
        java.lang.IllegalArgumentException - if the name or index id is empty
        See Also:
        StandardSerializers

      • getProof

        public com.exonum.binding.common.proofs.list.UncheckedListProof getProof​(long index)
        Returns a proof that an element exists 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

      • getRangeProof

        public com.exonum.binding.common.proofs.list.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:
        java.lang.IndexOutOfBoundsException - if the range is not valid
        java.lang.IllegalStateException - if this list is not valid

      • getRootHash

        public com.exonum.binding.common.hash.HashCode getRootHash()
        Returns the root hash of the proof list.
        Throws:
        java.lang.IllegalStateException - if this list is not valid

      • getName

        public abstract java.lang.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​(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

      • 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.

        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 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.

        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 java.lang.String getName()
        Returns the name of this index.

      • toString

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