Package convex.core.data

Class Blob

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

convex.core.data.AArrayBlob

convex.core.data.Blob

All Implemented Interfaces:

IValidated, IWriteable, Comparable<ABlobLike<?>>

public class Blob
extends AArrayBlob

General purpose immutable wrapper for byte array data. Can be encoded fully as a single Cell 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 final int	CHUNK_LENGTH
static final Blob	EMPTY
static final Blob	EMPTY_CHUNK
static final int	MAX_ENCODING_LENGTH	Maximum encoding size for a regular Blob
static final Blob	NULL_ENCODING
static final Blob	ONE
static final Blob	ZERO

Fields inherited from class convex.core.data.AArrayBlob

contentHash, offset, store

Fields inherited from class convex.core.data.ABlob

count

Fields inherited from class convex.core.data.ACell

cachedRef, memorySize

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 Blob 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	encodeRaw(byte[] bs, int pos)	Encodes this Blob, excluding tag byte (will include count)
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	forByte(byte b)
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
Blob	getChunk(long i)	Gets a chunk of this Blob, as a canonical flat Blob up to the maximum Blob chunk size.
boolean	isCanonical()	Returns true if this Cell is in a canonical representation.
static Blob	parse(String data)	Parses String input as a Blob.
static Blob	read(Blob source, int pos, long count)	Fast read of a Blob from its encoding inside another Blob object,
Blob	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.
Blob	slice(long start, long end)	Gets a contiguous slice of this Blob, as a new Blob.
ABlob	toCanonical()	Converts this Cell to a canonical version.
Blob	toFlatBlob()	Converts the contents of this value 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, appendHex, appendSmall, byteAt, byteAtUnchecked, calcMemorySize, compareTo, compareTo, equalsBytes, equalsBytes, getByteBuffer, getBytes, getContentHash, getHexDigit, getInternalArray, getInternalOffset, getRef, getRefCount, hexMatch, hexMatch, hexMatches, isChunkPacked, isFullyPacked, longAt, longValue, rangeMatches, rangeMatches, read, shortAt, updateDigest, updateRefs, validate, validateCell

Methods inherited from class convex.core.data.ABlob

computeHash, count, empty, encode, equals, get, getElementRef, getTag, getType, hashCode, isCVMValue, print, read, replaceSlice, size, toBlob, toByteBuffer

Methods inherited from class convex.core.data.ABlobLike

getBytes, hexEquals, hexLength, isDataValue, toHexString, toHexString

Methods inherited from class convex.core.data.ACountable

isEmpty

Methods inherited from class convex.core.data.ACell

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

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

ZERO

public static final Blob ZERO

ONE

public static final Blob ONE

NULL_ENCODING

public static final Blob NULL_ENCODING

CHUNK_LENGTH

public static final int CHUNK_LENGTH

See Also:

• Constant Field Values

EMPTY_CHUNK

public static final Blob EMPTY_CHUNK

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

parse

public static Blob parse(String data)

Parses String input as a Blob. Converts from hex.

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: 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 AArrayBlob

Returns:

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

slice

public Blob slice(long start,
 long end)

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 (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 Blob slice(long start)

Description copied from class: ABlob

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 ABlob

Parameters:

start - Start position to slice from

Returns:

Slice of 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 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

Overrides:

equals in class AArrayBlob

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

forByte

public static Blob forByte(byte b)

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

read

public static Blob read(Blob source,
 int pos,
 long count)
                 throws BadFormatException

Fast read of a Blob from its encoding inside another Blob object,

Parameters:

source - Source Blob object.

pos - Position in source to start reading from (location of tag byte)

count - Length in bytes to take from the source Blob

Returns:

Blob read from the source

Throws:

BadFormatException - If encoding is invalid

encodeRaw

public int encodeRaw(byte[] bs,
 int pos)

Description copied from class: AArrayBlob

Encodes this Blob, excluding tag byte (will include count)

Overrides:

encodeRaw in class AArrayBlob

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 highly likely to contain the entire object when encoded, including the tag byte. Should not traverse soft Refs, i.e. must be usable on arbitrary partial data structures

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. Non-canonical objects may be used on a temporary internal basis, they should be converted to canonical representations for general purpose use.

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

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)

toCanonical

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

Returns:

Canonical version of Cell