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 element 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 element 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()
      Description copied from class: ACountable
      Returns a canonical, singleton empty instance of the same type as this Countable value.
      Specified by:
      empty in class ACountable<CVMByte>
      Returns:
      An empty Countable value

    • toHexString

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

    • toHexString

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

    • appendHex

      protected abstract boolean appendHex(BlobBuilder bb, long length)
      Append hex string up to the given length in hex digits (a multiple of two)
      Parameters:
      bb - BlobBuilder instance to append to
      length - Length in Hex digits to append
      Returns:
      true if Blob fully appended, false if more more hex digits remain

    • toByteBuffer

      public ByteBuffer toByteBuffer()
      Converts this blob to a readable byte buffer. WARNING: may be large. May refer to underlying byte array so should not be mutated
      Returns:
      ByteBuffer with position zero (ready to read)

    • slice

      public abstract ABlob slice(long start, long end)
      Gets a contiguous slice of this Blob, as a new Blob. Shares underlying backing data where possible
      Specified by:
      slice in class ACountable<CVMByte>
      Parameters:
      start - Start position for the created slice (inclusive)
      end - End of the slice (exclusive)
      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
      Overrides:
      slice in class ACountable<CVMByte>
      Parameters:
      start - Start position to slice from
      Returns:
      Slice of Blob

    • toFlatBlob

      public abstract Blob toFlatBlob()
      Converts this object to a flat array-backed Blob instance. Warning: might be O(n) in size of Blob, may not be canonical etc.
      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. WARNING: Result is undefined if index is out of bounds, but probably an IndexOutOfBoundsException.
      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 Blob.
      Returns:
      A new byte array containing the contents of this blob.

    • append

      public abstract ABlob append(ABlob d)
      Append an additional Blob to this, creating a new Blob as needed. New Blob will be canonical.
      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 Cell if already canonical, may be O(n) in size of value otherwise.
      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 lexicographic order sorting by first bytes (unsigned). Note: This means that compareTo does not precisely match equality, because specialised 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. May be big!
      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. Returns empty Blob if and only if referencing the end of a Blob with fully packed chunks
      Parameters:
      i - Index of chunk
      Returns:
      A Blob containing the specified chunk data.

    • print

      public boolean print(BlobBuilder bb, long limit)
      Prints this Blob in a readable Hex representation, typically in the format "0x01abcd...." Subclasses may override this if they require a different representation.
      Specified by:
      print in class AObject
      Parameters:
      bb - BlobBuilder to append to
      limit - Limit of printing in string bytes
      Returns:
      True if fully printed within limit, false otherwise

    • getByteBuffer

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

    • 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 Value 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)
      Checks for Hex equality of two ABlobs. *ignores* type, i.e. only considers hex contents.
      Parameters:
      b - ABlob to compare with
      Returns:
      True if all hex digits are equal, false otherwise

    • hexEquals

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

    • hexLength

      public long hexLength()

    • encodeRaw

      public abstract int encodeRaw(byte[] bs, int pos)
      Writes this Blob's encoding to a byte array, excluding the tag byte
      Specified by:
      encodeRaw in class ACell
      Parameters:
      bs - A byte array to which to write the encoding
      pos - The offset into the byte array
      Returns:
      New position after writing

    • 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 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 Address)
      Returns:
      True if a regular blob

    • isCVMValue

      public final boolean isCVMValue()
      Description copied from class: ACell
      Returns true if this Cell represents a first class CVM Value. Sub-structural cells that are not themselves first class values should return false, pretty much everything else should return true. Note: CVM values might not be in a canonical format, e.g. temporary data structures
      Specified by:
      isCVMValue in class ACell
      Returns:
      true if the object is a CVM Value, false otherwise

    • 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

    • encodeRawData

      public int encodeRawData(byte[] bs, int pos)
      Encodes the raw data of this Blob. Assumes buffer has enough space for (length) bytes.
      Parameters:
      bs - Byte array to write to
      pos - Position to write at
      Returns:
      Updates position