Package com.exonum.binding.storage.indices

Class ValueSetIndexProxy<E>

  • Type Parameters:
    E - the type of elements in this set
    All Implemented Interfaces:
    java.lang.Iterable<ValueSetIndexProxy.Entry<E>>
    public final class ValueSetIndexProxy<E>
extends AbstractNativeProxy
implements java.lang.Iterable<ValueSetIndexProxy.Entry<E>>
    A value set is an index that contains no duplicate elements (values). This implementation does not permit null elements.

    The elements are stored in the underlying database as values, whereas their cryptographic hashes are used as keys, making this set implementation more suitable for storing large elements. If your application has small elements and does not need to perform set operations by hashes of the elements, consider using a KeySetIndexProxy.

    The "destructive" methods of the set, i.e., the ones that change its contents, are specified to throw UnsupportedOperationException if the set 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 set is destroyed. Subsequent use of the closed set is prohibited and will result in IllegalStateException.

    See Also:
    KeySetIndexProxy, View

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  ValueSetIndexProxy.Entry<E>
      An entry of a value set index: a hash-value pair.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(E e)
      Adds a new element to the set.
      void clear()
      Removes all of the elements from this set.
      boolean contains​(E e)
      Returns true if this set contains the specified element.
      boolean containsByHash​(com.exonum.binding.common.hash.HashCode elementHash)
      Returns true if this set contains an element with the specified hash.
      java.lang.String getName()
      Returns the name of this index.
      java.util.Iterator<com.exonum.binding.common.hash.HashCode> hashes()
      Creates an iterator over the hashes of the elements in this set.
      java.util.Iterator<ValueSetIndexProxy.Entry<E>> iterator()
      Returns an iterator over the entries of this set.
      static <E> ValueSetIndexProxy<E> newInGroupUnsafe​(java.lang.String groupName, byte[] indexId, View view, com.exonum.binding.common.serialization.Serializer<E> serializer)
      Creates a new value set in a collection group with the given name.
      static <E> ValueSetIndexProxy<E> newInstance​(java.lang.String name, View view, com.exonum.binding.common.serialization.Serializer<E> serializer)
      Creates a new value set.
      static <E extends com.google.protobuf.MessageLite>
      ValueSetIndexProxy<E>      		 newInstance​(java.lang.String name, View view, java.lang.Class<E> valueType)
      Creates a new value set storing protobuf messages.
      void remove​(E e)
      Removes the element from this set.
      void removeByHash​(com.exonum.binding.common.hash.HashCode elementHash)
      Removes an element from this set by its hash.
      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> ValueSetIndexProxy<E> newInstance​(java.lang.String name,
                                                                                            View view,
                                                                                            java.lang.Class<E> valueType)
        Creates a new value set storing protobuf messages.
        Type Parameters:
        E - the type of values in this set; must be a protobuf message that has a public static #parseFrom(byte[]) method
        Parameters:
        name - a unique alphanumeric non-empty identifier of this set 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.
        valueType - the class of values-protobuf messages
        Throws:
        java.lang.IllegalStateException - if the view is not valid
        java.lang.IllegalArgumentException - if the name is empty

      • newInstance

        public static <E> ValueSetIndexProxy<E> newInstance​(java.lang.String name,
                                                    View view,
                                                    com.exonum.binding.common.serialization.Serializer<E> serializer)
        Creates a new value set.
        Type Parameters:
        E - the type of values in this set
        Parameters:
        name - a unique alphanumeric non-empty identifier of this set 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 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 <E> ValueSetIndexProxy<E> newInGroupUnsafe​(java.lang.String groupName,
                                                         byte[] indexId,
                                                         View view,
                                                         com.exonum.binding.common.serialization.Serializer<E> serializer)
        Creates a new value set in a collection group with the given name.

        See a caveat on index identifiers.

        Type Parameters:
        E - the type of values in this set
        Parameters:
        groupName - a name of the collection group
        indexId - an identifier of this collection in the group, see the caveats
        view - a database view
        serializer - a serializer of set values
        Returns:
        a new value set
        Throws:
        java.lang.IllegalStateException - if the view is not valid
        java.lang.IllegalArgumentException - if the name or index id is empty
        See Also:
        StandardSerializers

      • add

        public void add​(E e)
        Adds a new element to the set. The method has no effect if the set already contains such element.
        Parameters:
        e - an element to add
        Throws:
        java.lang.IllegalStateException - if this set is not valid
        java.lang.UnsupportedOperationException - if this set is read-only

      • clear

        public void clear()
        Removes all of the elements from this set. The set will be empty after this method returns.
        Throws:
        java.lang.IllegalStateException - if this set is not valid
        java.lang.UnsupportedOperationException - if this set is read-only

      • contains

        public boolean contains​(E e)
        Returns true if this set contains the specified element.
        Throws:
        java.lang.IllegalStateException - if this set is not valid
        See Also:
        containsByHash(HashCode)

      • containsByHash

        public boolean containsByHash​(com.exonum.binding.common.hash.HashCode elementHash)
        Returns true if this set contains an element with the specified hash.
        Parameters:
        elementHash - a hash of an element
        Throws:
        java.lang.IllegalStateException - if this set is not valid

      • hashes

        public java.util.Iterator<com.exonum.binding.common.hash.HashCode> hashes()
        Creates an iterator over the hashes of the elements in this set. The hashes are ordered lexicographically.

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

        Returns:
        an iterator over the hashes of the elements in this set
        Throws:
        java.lang.IllegalStateException - if this set is not valid

      • iterator

        public java.util.Iterator<ValueSetIndexProxy.Entry<E>> iterator()
        Returns an iterator over the entries of this set. An entry is a hash-value pair. The entries are ordered by keys lexicographically.

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

        Specified by:
        iterator in interface java.lang.Iterable<E>
        Returns:
        an iterator over the entries of this set
        Throws:
        java.lang.IllegalStateException - if this set is not valid

      • remove

        public void remove​(E e)
        Removes the element from this set. If it's not in the set, does nothing.
        Parameters:
        e - an element to remove.
        Throws:
        java.lang.IllegalStateException - if this set is not valid
        java.lang.UnsupportedOperationException - if this set is read-only

      • removeByHash

        public void removeByHash​(com.exonum.binding.common.hash.HashCode elementHash)
        Removes an element from this set by its hash. If there is no such element in the set, does nothing.
        Parameters:
        elementHash - the hash of an element to remove.
        Throws:
        java.lang.IllegalStateException - if this set is not valid
        java.lang.UnsupportedOperationException - if this set is read-only

      • 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