Class Builder

java.lang.Object
io.crums.util.mrkl.Builder
Direct Known Subclasses:
FixedLeafBuilder
public class Builder extends Object
Collects items (byte arrays) and builds a Merkle tree. If all the items (the leaves of the tree) added are fixed-width (and the tree's data fits under 1GB memory), then the instance builds a FixedLeafTree; otherwise, it builds a FreeLeafTree instance.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final boolean
    copyOnWrite
     
    protected final List<List<byte[]>>
    data
    Breadth-first view of the nodes' data.
    protected final MessageDigest
    digest
     
    protected final Object
    lock
    Synchronization lock.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Builder(Builder copy)
    Copy constructor.
     
    Builder(String algo)
    Creates a new copy-on-write (copy-on-add) instance with a dedicated MessageDigest using the given hashing algorithm.
     
    Builder(String algo, boolean copyOnWrite)
    Creates a new instance with a dedicated MessageDigest using the given hashing algorithm.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    add(byte[] item)
    Adds the specified item as the next leaf node are returns its leaf index.
    int
    add(byte[] item, int off, int len)
    Adds the specified item as the next leaf node are returns its leaf index.
    Tree
    build()
    Builds and returns the tree.
    void
    clear()
    Clears the state of the instance, as if new.
    protected void
    completeTree()
     
    final int
    count()
    Returns the number of items added.
    final String
    getHashAlgo()
     
    byte[]
    hash(byte[] data)
    Convenience method to hash using this instance's digest algo.
    final int
    hashWidth()
     
    byte[]
    item(int index)
    Returns (a copy of) of the item at the given index.
    int
    leafWidth()
    Returns the leaf width if fixed; -1 if variable; -2 if not set.
    protected final List<byte[]>
    level(int index)
     
    protected final int
    levelSize(int level)
     
    protected List<byte[]>
    newByteArrayList(int level)
     
    protected Tree
    packageTree()
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • lock

      protected final Object lock
      Synchronization lock.

    • data

      protected final List<List<byte[]>> data
      Breadth-first view of the nodes' data.

    • digest

      protected final MessageDigest digest

    • copyOnWrite

      protected final boolean copyOnWrite

  • Constructor Details

    • Builder

      public Builder(String algo) throws IllegalArgumentException
      Creates a new copy-on-write (copy-on-add) instance with a dedicated MessageDigest using the given hashing algorithm.
      Parameters:
      algo - the digest algorithm (e.g. MD5, SHA-1, SHA-256)
      Throws:
      IllegalArgumentException - in lieu of checked NoSuchAlgorithmException

    • Builder

      public Builder(String algo, boolean copyOnWrite) throws IllegalArgumentException
      Creates a new instance with a dedicated MessageDigest using the given hashing algorithm.
      Parameters:
      algo - the digest algorithm (e.g. MD5, SHA-1, SHA-256)
      copyOnWrite - if true, then every add(byte[]) is argument is copied (the argument's value is considered volatile). When you know you won't be modifying the input arguments set this to false
      Throws:
      IllegalArgumentException - in lieu of checked NoSuchAlgorithmException

    • Builder

      protected Builder(Builder copy)
      Copy constructor. The new instance shares the same fields as this instance.
      Parameters:
      copy -

  • Method Details

    • add

      public int add(byte[] item)
      Adds the specified item as the next leaf node are returns its leaf index.
      Parameters:
      item - the item's data (copied)
      Returns:
      the item's leaf node index in the to-be built tree
      See Also:

    • hash

      public byte[] hash(byte[] data)
      Convenience method to hash using this instance's digest algo. Does not affect the state of the builder.
      Parameters:
      data - to be hashed
      Returns:
      a new array containing the hash

    • hashWidth

      public final int hashWidth()

    • add

      public int add(byte[] item, int off, int len) throws IndexOutOfBoundsException
      Adds the specified item as the next leaf node are returns its leaf index.
      Parameters:
      item - the item's data (copied)
      off - starting offset into item
      len - the number of bytes following off
      Returns:
      the item's leaf node index in the to-be built tree
      Throws:
      IndexOutOfBoundsException

    • build

      public Tree build()
      Builds and returns the tree. On return the builder is cleared.
      See Also:

    • completeTree

      protected void completeTree()

    • packageTree

      protected Tree packageTree()

    • leafWidth

      public int leafWidth()
      Returns the leaf width if fixed; -1 if variable; -2 if not set.
      Returns:
      ≥ -2

    • clear

      public void clear()
      Clears the state of the instance, as if new.

    • count

      public final int count()
      Returns the number of items added.

    • item

      public byte[] item(int index) throws IndexOutOfBoundsException
      Returns (a copy of) of the item at the given index.
      Parameters:
      index - < count()
      Throws:
      IndexOutOfBoundsException

    • getHashAlgo

      public final String getHashAlgo()

    • levelSize

      protected final int levelSize(int level)

    • newByteArrayList

      protected List<byte[]> newByteArrayList(int level)

    • level

      protected final List<byte[]> level(int index)