Package convex.core.data

Class ABlob

java.lang.Object
convex.core.data.AObject
convex.core.data.ACell
convex.core.data.ACountable<CVMByte>
convex.core.data.ABlob
All Implemented Interfaces:
IValidated, IWriteable, Comparable<ABlob>
Direct Known Subclasses:
AArrayBlob, ALongBlob, BlobTree
public abstract class ABlob extends ACountable<CVMByte> implements Comparable<ABlob>
Abstract base class for data objects containing immutable chunks of binary data. Representation is equivalent to a fixed size immutable byte sequence. Rationale: - Allow data to be encapsulated as an immutable object - Provide specialised methods for processing byte data - Provide a cached Hash value, lazily computed on demand

  • Field Details

    • contentHash

      protected Hash contentHash
      Cached hash of the Blob data. Might be null.

  • Constructor Details

    • ABlob

      public ABlob()

  • Method Details

    • getType

      public AType getType()
      Description copied from class: ACell
      Gets the most specific known runtime Type for this Cell.
      Overrides:
      getType in class ACell
      Returns:
      The Type of this Call

    • getBytes

      public abstract void getBytes​(byte[] dest, int destOffset)
      Copies the bytes from this blob to a given destination
      Parameters:
      dest - Destination array
      destOffset - Offset into destination array

    • count

      public abstract long count()
      Gets the length of this Blob
      Specified by:
      count in class ACountable<CVMByte>
      Returns:
      The length in bytes of this data object

    • get

      public CVMByte get​(long ix)
      Description copied from class: ACountable
      Gets the element at the specified index in this collection
      Specified by:
      get in class ACountable<CVMByte>
      Parameters:
      ix - Index of element to get
      Returns:
      Element at the specified index

    • getElementRef

      public Ref<CVMByte> getElementRef​(long index)
      Description copied from class: ACountable
      Gets a Ref to the element at the specified index in this collection
      Specified by:
      getElementRef in class ACountable<CVMByte>
      Parameters:
      index - Index of element to get
      Returns:
      Element at the specified index

    • empty

      public Blob empty()

    • toHexString

      public abstract String toHexString()
      Converts this data object to a lowercase hex string representation
      Returns:
      Hex String representation

    • toByteBuffer

      public ByteBuffer toByteBuffer()
      Converts this blob to a readable byte buffer
      Returns:
      ByteBuffer with position zero (ready to read)

    • toHexString

      public String toHexString​(int length)
      Converts this data object to a hex string representation of the given length. Equivalent to truncating the full String representation.
      Parameters:
      length - Length to truncate String to (in hex characters)
      Returns:
      String representation of hex values in Blob

    • slice

      public abstract ABlob slice​(long start, long length)
      Gets a contiguous slice of this blob, as a new Blob. Shares underlying backing data where possible
      Parameters:
      start - Start position for the created slice
      length - Length of the slice
      Returns:
      A blob of the specified length, representing a slice of this blob.

    • slice

      public ABlob slice​(long start)
      Gets a slice of this blob, as a new blob, starting from the given offset and extending to the end of the blob. Shares underlying backing data where possible. Returned Blob may not be the same type as the original Blob
      Parameters:
      start - Start position to slice from
      Returns:
      Slice of Blob

    • toBlob

      public abstract Blob toBlob()
      Converts this object to a Blob instance
      Returns:
      A Blob instance containing the same data as this Blob.

    • commonHexPrefixLength

      public abstract long commonHexPrefixLength​(ABlob b)
      Computes the length of the longest common hex prefix between two blobs
      Parameters:
      b - Blob to compare with
      Returns:
      The length of the longest common prefix in hex digits

    • getContentHash

      public final Hash getContentHash()
      Computes the hash of the byte data stored in this Blob, using the default MessageDigest. This is the correct hash ID for a data value if this blob contains the data value's encoding
      Returns:
      The Hash

    • computeHash

      public final Hash computeHash​(MessageDigest digest)
      Computes the hash of the byte data stored in this Blob, using the given MessageDigest.
      Parameters:
      digest - MessageDigest instance
      Returns:
      The hash

    • updateDigest

      protected abstract void updateDigest​(MessageDigest digest)

    • byteAt

      public byte byteAt​(long i)
      Gets the byte at the specified position in this blob
      Parameters:
      i - Index of the byte to get
      Returns:
      The byte at the specified position

    • getUnchecked

      public abstract byte getUnchecked​(long i)
      Gets the byte at the specified position in this data object, without bounds checking. Only safe if index is known to be in bounds, otherwise result is undefined.
      Parameters:
      i - Index of the byte to get
      Returns:
      The byte at the specified position

    • getHexDigit

      public int getHexDigit​(long digitPos)
      Gets the specified hex digit from this data object. Result is undefined if index is out of bounds.
      Parameters:
      digitPos - The position of the hex digit
      Returns:
      The value of the hex digit, in the range 0-15 inclusive

    • getBytes

      public byte[] getBytes()
      Gets a byte array containing a copy of this data object.
      Returns:
      A new byte array containing the contents of this blob.

    • append

      public abstract ABlob append​(ABlob d)
      Append an additional data object to this, creating a new data object.
      Parameters:
      d - Blob to append
      Returns:
      A new blob, containing the additional data appended to this blob.

    • equals

      public final boolean equals​(ACell o)
      Determines if this Blob is equal to another Object. Blobs are defined to be equal if they have the same on-chain representation, i.e. if and only if all of the following are true: - Blob is of the same general type - Blobs are of the same length - All byte values are equal
      Overrides:
      equals in class ACell
      Parameters:
      o - Cell to compare with. May be null??
      Returns:
      True if this cell is equal to the other object

    • equals

      public abstract boolean equals​(ABlob o)
      Determines if this Blob is equal to another Blob. Blobs are defined to be equal if they have the same on-chain representation, i.e. if and only if all of the following are true: - Blob is of the same general type - Blobs are of the same length - All byte values are equal
      Parameters:
      o - Blob to compare with
      Returns:
      true if Blobs are equal, false otherwise

    • toCanonical

      public abstract ABlob toCanonical()
      Description copied from class: ACell
      Converts this Cell to its canonical version. Returns this if already canonical
      Specified by:
      toCanonical in class ACell
      Returns:
      Canonical version of Cell

    • equalsBytes

      public abstract boolean equalsBytes​(byte[] bytes, int byteOffset)
      Tests if this Blob is equal to a subset of a byte array
      Parameters:
      bytes - Byte array to compare with
      byteOffset - Offset into byte array
      Returns:
      true if exactly equal, false otherwise

    • compareTo

      public int compareTo​(ABlob b)
      Compares this blob to another blob, in lexographic order sorting by first bytes. Note: This means that compareTo does not precisely match equality, because different blob types may be lexicographically equal but represent different values.
      Specified by:
      compareTo in interface Comparable<ABlob>

    • writeToBuffer

      public abstract ByteBuffer writeToBuffer​(ByteBuffer bb)
      Writes the raw byte contents of this blob to a ByteBuffer.
      Parameters:
      bb - ByteBuffer to write to
      Returns:
      The passed ByteBuffer, after writing byte content

    • writeToBuffer

      public abstract int writeToBuffer​(byte[] bs, int pos)
      Writes the raw byte contents of this blob to a byte array
      Parameters:
      bs - Byte array to write to
      pos - Starting position in byte array to write to
      Returns:
      The position in the array after writing

    • getChunk

      public abstract Blob getChunk​(long i)
      Gets a chunk of this Blob, as a canonical Blob up to the maximum chunk size
      Parameters:
      i - Index of chunk
      Returns:
      A Blob containing the specified chunk data.

    • print

      public void print​(StringBuilder sb)
      Description copied from class: AObject
      Prints this Object to a readable String Representation
      Specified by:
      print in class AObject
      Parameters:
      sb - StringBuilder to append to

    • getByteBuffer

      public abstract ByteBuffer getByteBuffer()
      Gets a byte buffer containing this Blob's data. Will have remaining bytes equal to this Blob's size.
      Returns:
      A ByteBuffer containing the Blob's data.

    • toHexString

      public abstract void toHexString​(StringBuilder sb)

    • validate

      public void validate() throws InvalidDataException
      Description copied from interface: IValidated
      Validates the complete structure of this object. It is necessary to ensure all child Refs are validated, so the general contract for validate is:
      1. Call super.validate() - which will indirectly call validateCell()
      2. Call validate() on any contained cells in this class
      Specified by:
      validate in interface IValidated
      Overrides:
      validate in class ACell
      Throws:
      InvalidDataException - If the data Valie is invalid in any way

    • validateCell

      public void validateCell() throws InvalidDataException
      Description copied from class: ACell
      Validates the local structure and invariants of this cell. Called by validate() super implementation. Should validate directly contained data, but should not validate all other structure of this cell. In particular, should not traverse potentially missing child Refs.
      Specified by:
      validateCell in class ACell
      Throws:
      InvalidDataException - If the Cell is invalid

    • hexMatchLength

      public abstract long hexMatchLength​(ABlob b, long start, long length)
      Returns the number of matching hex digits in the given hex range of another blob. Assumes range is valid for both blobs. Returns length if this Blob is exactly equal to the specified hex range.
      Parameters:
      start - Start position (in hex digits)
      length - Length to compare (in hex digits)
      b - Blob to compare with
      Returns:
      The number of matching hex characters

    • hexEquals

      public boolean hexEquals​(ABlob b)

    • hexEquals

      public boolean hexEquals​(ABlob b, long start, long length)

    • hexLength

      public long hexLength()

    • toLong

      public abstract long toLong()
      Converts this Blob to the corresponding long value. Assumes big-endian format, as if the entire blob is interpreted as a signed big integer. Higher bytes outside the Long range will be ignored.
      Returns:
      long value of this blob

    • hashCode

      public int hashCode()
      Description copied from class: ACell
      Gets the Java hashCode for this cell. Must be consistent with equals. Default is the first bytes (big-endian) of the Cell Encoding's hash, since this is consistent with encoding-based equality. However, different Types may provide more efficient hashcodes provided that the usual invariants are preserved
      Overrides:
      hashCode in class ACell
      Returns:
      integer hash code.

    • longValue

      public abstract long longValue()
      Gets the long value of this Blob if the length is exactly 8 bytes, otherwise throws an Exception
      Returns:
      The long value represented by the Blob

    • isRegularBlob

      public boolean isRegularBlob()
      Returns true if this object is a regular blob (i.e. not a special blob type like Hash or Address)
      Returns:
      True if a regular blob

    • equalsBytes

      public abstract boolean equalsBytes​(ABlob b)
      Tests if this Blob has exactly the same bytes as another Blob
      Parameters:
      b - Blob to compare with
      Returns:
      True if byte content is exactly equal, false otherwise