Package convex.core.data

Class Blob

java.lang.Object

convex.core.data.AObject

convex.core.data.ACell

convex.core.data.ACountable<CVMByte>

convex.core.data.ABlob

convex.core.data.AArrayBlob

convex.core.data.Blob

All Implemented Interfaces:

IValidated, IWriteable, Comparable<ABlob>

public class Blob
extends AArrayBlob

General purpose immutable wrapper for byte array data. Can be serialised directly if 4096 bytes or less, otherwise needs to be structures as a BlobTree. Encoding format is: - Tag.BLOB tag byte - VLC encoded Blob length in bytes (one or two bytes describing a length in range 0..4096) - Byte data of the given length

Field Summary

Fields

Modifier and Type	Field	Description
static int	CHUNK_LENGTH
static Blob	EMPTY
static int	MAX_ENCODING_LENGTH	Maximum encoding size for a regular Blob
static Blob	NULL_ENCODING

Fields inherited from class convex.core.data.AArrayBlob

length, offset, store

Fields inherited from class convex.core.data.ABlob

contentHash

Fields inherited from class convex.core.data.ACell

cachedRef, EMPTY_ARRAY

Fields inherited from class convex.core.data.AObject

encoding

Method Summary

Modifier and Type	Method	Description
void	attachContentHash(Hash hash)
static Blob	create(byte[] data)	Creates a new data object using a copy of the specified byte array.
static Blob	create(byte[] data, int offset, int length)	Creates a new data object using a copy of the specified byte range
static Blob	createRandom(Random random, long length)	Creates a Blob of random bytes of the given length
int	encode(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, including a tag byte which will be written first.
boolean	equals(AArrayBlob other)	Equality for array Blob objects Implemented by testing equality of byte data
boolean	equals(ABlob a)	Determines if this Blob is equal to another Blob.
boolean	equals(Blob b)
int	estimatedEncodingSize()	Estimate the encoded data size for this Cell.
static Blob	fromByteBuffer(ByteBuffer bb)	Constructs a Blob object from all remaining bytes in a ByteBuffer
static Blob	fromHex(String hexString)	Constructs a Blob object from a hex string
ByteBuffer	getByteBuffer()	Gets a byte buffer containing this Blob's data.
Blob	getChunk(long i)	Gets a chunk of this Blob, as a canonical Blob up to the maximum chunk size.
byte	getTag()	Gets the tag byte for this cell.
boolean	isCanonical()	Returns true if this Cell is in a canonical representation for message writing.
boolean	isRegularBlob()	Returns true if this object is a regular blob (i.e.
static AArrayBlob	read(Blob source, long len)	Fast read of a Blob from its representation insider another Blob object, Main benefit is to avoid reconstructing via ByteBuffer allocation, enabling retention of source Blob object as encoded data.
Blob	slice(long start, long length)	Gets a contiguous slice of this blob, as a new Blob.
ABlob	toCanonical()	Converts this Cell to its canonical version.
Blob	toFlatBlob()	Converts this object to a flat array-backed Blob instance.
static Blob	wrap(byte[] data)	Wraps the specified bytes as a Data object Warning: underlying bytes are used directly.
static Blob	wrap(byte[] data, int offset, int length)	Wraps the specified bytes as a Data object Warning: underlying bytes are used directly.

Methods inherited from class convex.core.data.AArrayBlob

append, appendHexString, appendSmall, byteAt, commonHexPrefixLength, compareTo, compareTo, count, encodeRaw, encodeRawData, equalsBytes, equalsBytes, getBytes, getHexDigit, getInternalArray, getInternalOffset, getRefCount, getUnchecked, hexMatches, hexMatchLength, longValue, rangeMatches, rangeMatches, toLong, updateDigest, validate, validateCell, writeToBuffer, writeToBuffer

Methods inherited from class convex.core.data.ABlob

computeHash, empty, equals, get, getBytes, getContentHash, getElementRef, getType, hashCode, hexEquals, hexEquals, hexLength, isCVMValue, print, slice, toByteBuffer, toCVMString, toHexString, toHexString, toHexString

Methods inherited from class convex.core.data.ACountable

isEmpty, size

Methods inherited from class convex.core.data.ACell

announce, announce, attachMemorySize, attachRef, cachedEncoding, cachedHash, calcMemorySize, createAnnounced, createEncoding, createPersisted, createPersisted, createRef, equals, getCanonical, getChildRefs, getEncoding, getEncodingLength, getHash, getMemorySize, getRef, getRef, isCompletelyEncoded, isEmbedded, mark, mark, toString, updateRefs, write

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

Field Details

EMPTY

public static final Blob EMPTY

NULL_ENCODING

public static final Blob NULL_ENCODING

CHUNK_LENGTH

public static final int CHUNK_LENGTH

See Also:

Constant Field Values

MAX_ENCODING_LENGTH

public static final int MAX_ENCODING_LENGTH

Maximum encoding size for a regular Blob

Method Details

create

public static Blob create(byte[] data,
 int offset,
 int length)

Creates a new data object using a copy of the specified byte range

Parameters:

data - Byte array

offset - Start offset in the byte array

length - Number of bytes to take from data array

Returns:

The new Data object

create

public static Blob create(byte[] data)

Creates a new data object using a copy of the specified byte array.

Parameters:

data - Byte array

Returns:

Blob with the same byte contents as the given array

wrap

public static Blob wrap(byte[] data)

Wraps the specified bytes as a Data object Warning: underlying bytes are used directly. Use only if no other references to the byte array are kept which might be mutated.

Parameters:

data - Byte array

Returns:

Blob wrapping the given data

wrap

public static Blob wrap(byte[] data,
 int offset,
 int length)

Wraps the specified bytes as a Data object Warning: underlying bytes are used directly. Use only if no other references to the byte array are kept which might be mutated.

Parameters:

data - Byte array

offset - Offset into byte array

length - Length of byte array to wrap

Returns:

Blob wrapping the given byte array segment

toFlatBlob

public Blob toFlatBlob()

Description copied from class: ABlob

Converts this object 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 AArrayBlob

Returns:

A Blob instance containing the same data as this Blob.

slice

public Blob slice(long start,
 long length)

Description copied from class: ABlob

Gets a contiguous slice of this blob, as a new Blob. Shares underlying backing data where possible

Overrides:

slice in class AArrayBlob

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.

equals

public boolean equals(ABlob a)

Description copied from class: ABlob

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

Specified by:

equals in class ABlob

Parameters:

a - Blob to compare with

Returns:

true if Blobs are equal, false otherwise

equals

public boolean equals(Blob b)

equals

public boolean equals(AArrayBlob other)

Equality for array Blob objects Implemented by testing equality of byte data

Parameters:

other - Blob to comapre with

Returns:

true if blobs are equal, false otherwise.

fromHex

public static Blob fromHex(String hexString)

Constructs a Blob object from a hex string

Parameters:

hexString - Hex String to read

Returns:

Blob with the provided hex value, or null if not a valid blob

fromByteBuffer

public static Blob fromByteBuffer(ByteBuffer bb)

Constructs a Blob object from all remaining bytes in a ByteBuffer

Parameters:

bb - ByteBuffer

Returns:

Blob containing the contents read from the ByteBuffer

getByteBuffer

public ByteBuffer getByteBuffer()

Description copied from class: ABlob

Gets a byte buffer containing this Blob's data. Will have remaining bytes equal to this Blob's size.

Overrides:

getByteBuffer in class AArrayBlob

Returns:

A ByteBuffer containing the Blob's data.

read

public static AArrayBlob read(Blob source,
 long len)
                       throws BadFormatException

Fast read of a Blob from its representation insider another Blob object, Main benefit is to avoid reconstructing via ByteBuffer allocation, enabling retention of source Blob object as encoded data.

Parameters:

source - Source Blob object.

len - Length in bytes to take from the source Blob

Returns:

Blob read from the source

Throws:

BadFormatException - If encoding is invalid

encode

public 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

estimatedEncodingSize

public int estimatedEncodingSize()

Description copied from interface: IWriteable

Estimate the encoded data size for this Cell. Used for quickly sizing buffers. Implementations should try to return a size that is likely to contain the entire object when represented in binary format, including the tag byte.

Returns:

The estimated size for the binary representation of this object.

isCanonical

public boolean isCanonical()

Description copied from class: ACell

Returns true if this Cell is in a canonical representation for message writing. Non-canonical objects may be used on a temporary internal basis, they must always be converted to canonical representations for external use (e.g. Encoding).

Specified by:

isCanonical in class ACell

Returns:

true if the object is in canonical format, false otherwise

createRandom

public static Blob createRandom(Random random,
 long length)

Creates a Blob of random bytes of the given length

Parameters:

random - Any Random generator instance

length - Length of Blob to generate in bytes

Returns:

Blob with the specified number of random bytes

getChunk

public Blob getChunk(long i)

Description copied from class: ABlob

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

Specified by:

getChunk in class ABlob

Parameters:

i - Index of chunk

Returns:

A Blob containing the specified chunk data.

attachContentHash

public void attachContentHash(Hash hash)

isRegularBlob

public boolean isRegularBlob()

Description copied from class: ABlob

Returns true if this object is a regular blob (i.e. not a special blob type like Address)

Overrides:

isRegularBlob in class ABlob

Returns:

True if a regular blob

getTag

public byte getTag()

Description copied from class: ACell

Gets the tag byte for this cell. The tag byte is always written as the first byte of the Cell's Encoding

Specified by:

getTag in class ACell

Returns:

Tag byte for this Cell

toCanonical

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

Returns:

Canonical version of Cell