Package convex.core.data

Class ABlob

java.lang.Object

convex.core.data.AObject

convex.core.data.ACell

convex.core.data.ACountable<CVMLong>

convex.core.data.ABlobLike<CVMLong>

convex.core.data.ABlob

All Implemented Interfaces:

IValidated, IWriteable, Comparable<ABlobLike<?>>

Direct Known Subclasses:

AArrayBlob, ADerivedBlob, ALongBlob, BlobTree

public abstract class ABlob
extends ABlobLike<CVMLong>

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 Summary

Fields

Modifier and Type	Field	Description
protected final long	count

Fields inherited from class convex.core.data.ACell

cachedRef, memorySize

Fields inherited from class convex.core.data.AObject

encoding

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ABlob(long count)

Method Summary

Modifier and Type	Method	Description
abstract ABlob	append(ABlob d)	Append an additional Blob to this, creating a new Blob as needed.
byte	byteAt(long i)	Gets the byte at the specified position
int	compareTo(ABlobLike<?> b)	Compares this Blob to another Blob, in lexicographic order sorting by first bytes (unsigned).
final Hash	computeHash(MessageDigest digest)	Computes the hash of the byte data stored in this Blob, using the given MessageDigest.
final long	count()	Gets the length of this Blob
final Blob	empty()	Returns a canonical, singleton empty instance of the same type as this Countable value.
final int	encode(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, including a tag byte which will be written first.
abstract int	encodeRaw(byte[] bs, int pos)	Writes this Blob's encoding to a byte array, excluding the tag byte
abstract boolean	equals(ABlob o)	Determines if this Blob is equal to another Blob.
boolean	equals(ACell o)	Determines if this Blob is equal to another Object.
abstract boolean	equalsBytes(byte[] bytes, long offset)	Tests if the byte contents of this instance are equal to a subset of a byte array
abstract boolean	equalsBytes(ABlob b)	Tests if this Blob has exactly the same bytes as another Blob
CVMLong	get(long ix)	Gets the element at the specified element index in this value
abstract ByteBuffer	getByteBuffer()	Gets a byte buffer containing this Blob's raw data.
abstract Blob	getChunk(long i)	Gets a chunk of this Blob, as a canonical flat Blob up to the maximum Blob chunk size.
Hash	getContentHash()	Computes the hash of the byte data stored in this Blob, using the default MessageDigest.
Ref<CVMLong>	getElementRef(long index)	Gets a Ref to the element at the specified element index in this collection
final byte	getTag()	Gets the tag byte for this cell.
final AType	getType()	Gets the most specific known runtime Type for this Cell.
int	hashCode()	Gets the Java hashCode for this cell.
boolean	isChunkPacked()	Returns true if this Blob is a fully packed set of chunks
final boolean	isCVMValue()	Returns true if this cell is a first class CVM Value allowable in the CVM state Sub-structural cells that are not themselves first class values should return false Records and types that are not permissible on the CVM should return false.
abstract boolean	isFullyPacked()	Returns true if this is a fully packed set of chunks
boolean	print(BlobBuilder bb, long limit)	Prints this Object to a readable String Representation.
abstract int	read(long offset, long count, ByteBuffer dest)	Gets bytes from this Blob into a ByteBuffer
int	read(long offset, ByteBuffer dest)	Gets bytes from this Blob into a ByteBuffer
ABlob	replaceSlice(long position, ABlob b)	Replaces a slice of this Blob, returning a new Blob
short	shortAt(long i)
final int	size()	Gets the size of this data structure as an int.
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.
abstract ABlob	slice(long start, long end)	Gets a contiguous slice of this Blob, as a new Blob.
final ABlob	toBlob()	Convert this BlobLike object to an ABlob instance, in the most efficient way.
ByteBuffer	toByteBuffer()	Converts this blob to a readable byte buffer.
protected abstract ABlob	toCanonical()	Converts this Cell to a canonical version.
abstract Blob	toFlatBlob()	Converts the contents of this value to a flat array-backed Blob instance.
protected abstract void	updateDigest(MessageDigest digest)
void	validate()	Validates the complete structure of this object.
void	validateCell()	Validates the local structure and invariants of this cell.

Methods inherited from class convex.core.data.ABlobLike

appendHex, byteAtUnchecked, getBytes, getBytes, getHexDigit, hexEquals, hexLength, hexMatch, hexMatch, isDataValue, longValue, toHexString, toHexString

Methods inherited from class convex.core.data.ACountable

isEmpty

Methods inherited from class convex.core.data.ACell

attachMemorySize, attachRef, cachedEncoding, cachedHash, calcMemorySize, createEncoding, createRef, equals, genericEquals, getCanonical, getChildRefs, getEncoding, getEncodingLength, getHash, getMemorySize, getMemorySize, getRef, getRef, getRefCount, isCanonical, isEmbedded, toCVMString, toString, updateRefs

Methods inherited from class convex.core.data.AObject

attachEncoding, print, print

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface convex.core.data.IWriteable

estimatedEncodingSize

Field Details

count

protected final long count

Constructor Details

ABlob

protected ABlob(long count)

Method Details

isChunkPacked

public boolean isChunkPacked()

Returns true if this Blob is a fully packed set of chunks

Returns:

True if fully packed, false otherwise

isFullyPacked

public abstract boolean isFullyPacked()

Returns true if this is a fully packed set of chunks

Returns:

True if fully packed, false otherwise

size

public final int size()

Description copied from class: ACountable

Gets the size of this data structure as an int. Returns Integer.MAX_SIZE if the count is larger than can fit in an int. If this might be a problem, use count() instead.

Overrides:

size in class ACountable<CVMLong>

Returns:

Number of elements in this collection.

getType

public final 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

count

public final long count()

Gets the length of this Blob

Specified by:

count in class ACountable<CVMLong>

Returns:

The length in bytes of this data object

get

public CVMLong get(long ix)

Description copied from class: ACountable

Gets the element at the specified element index in this value

Specified by:

get in class ACountable<CVMLong>

Parameters:

ix - Index of element to get

Returns:

Element at the specified index

getElementRef

public Ref<CVMLong> getElementRef(long index)

Description copied from class: ACountable

Gets a Ref to the element at the specified element index in this collection

Overrides:

getElementRef in class ABlobLike<CVMLong>

Parameters:

index - Index of element to get

Returns:

Element at the specified index

empty

public final 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 ABlobLike<CVMLong>

Returns:

An empty Countable value, or null if there is no empty instance

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

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, or null if the slice is invalid

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

Parameters:

start - Start position to slice from

Returns:

Slice of Blob

toFlatBlob

public abstract Blob toFlatBlob()

Description copied from class: ABlobLike

Converts the contents of this value to a flat array-backed Blob instance. Warning: might be O(n) in size of Blob, may not be canonical etc.

Overrides:

toFlatBlob in class ABlobLike<CVMLong>

Returns:

A Blob instance containing the same data as this value. Might be `this` if already a flat Blob.

toBlob

public final ABlob toBlob()

Description copied from class: ABlobLike

Convert this BlobLike object to an ABlob instance, in the most efficient way. May return `this`.

Specified by:

toBlob in class ABlobLike<CVMLong>

Returns:

Blob instance

getContentHash

public 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

Specified by:

byteAt in class ABlobLike<CVMLong>

Parameters:

i - Index of the byte to get

Returns:

The byte at the specified position

append

public abstract ABlob append(ABlob d)

Append an additional Blob to this, creating a new Blob as needed.

Parameters:

d - Blob to append

Returns:

A new Blob, containing the additional data appended to this blob.

equals

public 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

Specified by:

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 encoded representation, i.e. if and only if all of the following are true: - 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

protected abstract ABlob toCanonical()

Description copied from class: ACell

Converts this Cell to a canonical version. Must return this Cell if already canonical, may be O(n) in size of value otherwise. Callers should usually use getCanonical(), which caches canonical instances once created

Specified by:

toCanonical in class ACell

Returns:

Canonical version of Cell

equalsBytes

public abstract boolean equalsBytes(byte[] bytes,
 long offset)

Tests if the byte contents of this instance are equal to a subset of a byte array

Parameters:

bytes - Byte array to compare with

offset - Offset into byte array from which to start comparison

Returns:

true if exactly equal, false otherwise

compareTo

public int compareTo(ABlobLike<?> 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<ABlobLike<?>>

Specified by:

compareTo in class ABlobLike<CVMLong>

getChunk

public abstract Blob getChunk(long i)

Gets a chunk of this Blob, as a canonical flat Blob up to the maximum Blob 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)

Description copied from class: AObject

Prints this Object to a readable String Representation. SECURITY: Must halt and return false in O(1) time when limit of printing is exceeded otherwise DoS attacks may be possible.

Specified by:

print in class AObject

Parameters:

bb - BlobBuilder to append to. May be partially written if print limit exceeded

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

encode

public final int encode(byte[] bs,
 int pos)

Description copied from class: ACell

Writes this Cell's encoding to a byte array, including a tag byte which will be written first. Cell must be canonical, or else an error may occur.

Specified by:

encode in interface IWriteable

Specified by:

encode 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

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

hashCode

public int hashCode()

Description copied from class: ACell

Gets the Java hashCode for this cell. Must be consistent with equals. Default is the hashCode of the Encoding blob, 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.

isCVMValue

public final boolean isCVMValue()

Description copied from class: ACell

Returns true if this cell is a first class CVM Value allowable in the CVM state Sub-structural cells that are not themselves first class values should return false Records and types that are not permissible on the CVM 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

getTag

public final byte getTag()

Description copied from class: ACell

Gets the tag byte for this cell. The tag byte is always equal to the first byte of the Cell's canonical Encoding, and is sufficient to distinguish how to read the rest of the encoding.

Specified by:

getTag in class ACell

Returns:

Tag byte for this Cell

equalsBytes

public abstract boolean equalsBytes(ABlob b)

Tests if this Blob has exactly the same bytes as another Blob

Specified by:

equalsBytes in class ABlobLike<CVMLong>

Parameters:

b - Blob to compare with

Returns:

True if byte content is exactly equal, false otherwise

shortAt

public short shortAt(long i)

read

public int read(long offset,
 ByteBuffer dest)

Gets bytes from this Blob into a ByteBuffer

Parameters:

offset - Offset into this Blob to read from

dest - Destination byte buffer

Returns:

Number of bytes read

read

public abstract int read(long offset,
 long count,
 ByteBuffer dest)

Gets bytes from this Blob into a ByteBuffer

Parameters:

offset - Offset into this Blob to read from

count - Number of bytes to read. Must be in bounds

dest - Destination byte buffer

Returns:

Number of bytes read

replaceSlice

public ABlob replaceSlice(long position,
 ABlob b)

Replaces a slice of this Blob, returning a new Blob

Parameters:

position - Position at which to replace

b - Blob to replace

Returns:

Updated Blob