Package convex.core.data

Class RefDirect<T extends ACell>

java.lang.Object

convex.core.data.AObject

convex.core.data.Ref<T>

convex.core.data.RefDirect<T>

Type Parameters:

T - Type of Value referenced

All Implemented Interfaces:

IValidated, IWriteable, Comparable<Ref<T>>

public class RefDirect<T extends ACell>
extends Ref<T>

Ref subclass for direct in-memory references. Direct Refs store the underlying value directly with a regular Java strong reference.

Care must be taken to ensure recursive structures do not exceed reasonable memory bounds. In smart contract execution, juice limits serve this purpose.

Field Summary

Fields inherited from class convex.core.data.Ref

ANNOUNCED, BAD_MASK, EMBEDDING_MASK, FALSE_VALUE, flags, hash, INDIRECT_ENCODING_LENGTH, INTERNAL, INTERNAL_FLAGS, INVALID, KNOWN_EMBEDDED_MASK, MARKED, MAX_STATUS, NON_EMBEDDED_MASK, NULL_VALUE, PERSISTED, STATUS_MASK, STORED, TRUE_VALUE, UNKNOWN, VALIDATED, VERIFICATION_MASK, VERIFIED_MASK

Fields inherited from class convex.core.data.AObject

encoding

Method Summary

Modifier and Type	Method	Description
static <T extends ACell> RefDirect<T>	create(T value)	Creates a new Direct ref to the given value.
static <T extends ACell> RefDirect<T>	create(T value, Hash hash)	Creates a direct Ref to the given value
static <T extends ACell> RefDirect<T>	create(T value, Hash hash, int status)	Construction function for a Direct Ref
boolean	equalsValue(Ref<T> a)	Checks if two Ref Values are equal.
int	estimatedEncodingSize()	Estimate the encoded data size for this Cell.
Hash	getHash()	Gets the Hash of this ref's value.
T	getValue()	Gets the value from this Ref.
boolean	isDirect()	Return true if this Ref is a direct reference, i.e.
boolean	isMissing()	Checks if this Ref refers to missing data, i.e.
Ref<T>	toDirect()	Converts this Ref to a RefDirect
void	validate()	Validates the complete structure of this object.
RefDirect<T>	withFlags(int newFlags)	Create a new Ref of the same type with updated flags
Ref<T>	withValue(T newValue)	Updates the value stored within this Ref.

Methods inherited from class convex.core.data.Ref

accumulateRefSet, addAllToSet, cachedHash, compareTo, createArray, createEncoding, encode, equals, findMissing, flagsWithStatus, forHash, get, get, getEncodingLength, getFlags, getMemorySize, getStatus, hashCode, isEmbedded, isMarked, isPersisted, markEmbedded, mergeFlags, persist, persist, persistShallow, persistShallow, print, readRaw, setFlags, toString, updateRefs, withMinimumStatus, write

Methods inherited from class convex.core.data.AObject

attachEncoding, getEncoding, print

Methods inherited from class java.lang.Object

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

Method Details

create

public static <T extends ACell> RefDirect<T> create(T value,
 Hash hash,
 int status)

Construction function for a Direct Ref

Type Parameters:

T - Type of value

Parameters:

value - Value for the Ref

hash - Hash (may be null)

status - Status for the Ref

Returns:

New Direct Ref

create

public static <T extends ACell> RefDirect<T> create(T value,
 Hash hash)

Creates a direct Ref to the given value

Type Parameters:

T - Type of value

Parameters:

value - Any value (may be embedded or otherwise, but should not be null)

hash - Hash of value's encoding, or null if not known

Returns:

Direct Ref to Value

create

public static <T extends ACell> RefDirect<T> create(T value)

Creates a new Direct ref to the given value. Does not compute hash.

Type Parameters:

T - Type of Value

Parameters:

value - Value

Returns:

Direct Ref to Value

getValue

public T getValue()

Description copied from class: Ref

Gets the value from this Ref. Important notes: - May throw a MissingDataException if the data does not exist in available storage - Will return null if and only if the Ref refers to the null value

Specified by:

getValue in class Ref<T extends ACell>

Returns:

The value contained in this Ref

isDirect

public boolean isDirect()

Description copied from class: Ref

Return true if this Ref is a direct reference, i.e. the value is pinned in memory and cannot be garbage collected

Specified by:

isDirect in class Ref<T extends ACell>

Returns:

true if this Ref is direct, false otherwise

getHash

public Hash getHash()

Description copied from class: Ref

Gets the Hash of this ref's value.

Specified by:

getHash in class Ref<T extends ACell>

Returns:

Hash of the value

toDirect

public Ref<T> toDirect()

Description copied from class: Ref

Converts this Ref to a RefDirect

Overrides:

toDirect in class Ref<T extends ACell>

Returns:

Direct Ref

equalsValue

public boolean equalsValue(Ref<T> a)

Description copied from class: Ref

Checks if two Ref Values are equal. Equality is defined as referring to the same data, i.e. have an identical hash.

Specified by:

equalsValue in class Ref<T extends ACell>

Parameters:

a - The Ref to compare with

Returns:

true if Refs have the same value, false otherwise

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 Ref<T extends ACell>

Throws:

InvalidDataException - If the data Valie is invalid in any way

withValue

public Ref<T> withValue(T newValue)

Description copied from class: Ref

Updates the value stored within this Ref. New value must be equal in value to the old value (identical hash), but may have updated internal refs etc.

Specified by:

withValue in class Ref<T extends ACell>

Parameters:

newValue - New value

Returns:

Updated Ref

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.

isMissing

public boolean isMissing()

Description copied from class: Ref

Checks if this Ref refers to missing data, i.e. a Cell that does not exist in the currect store.

Specified by:

isMissing in class Ref<T extends ACell>

Returns:

true if this specific Ref has missing data, false otherwise.

withFlags

public RefDirect<T> withFlags(int newFlags)

Description copied from class: Ref

Create a new Ref of the same type with updated flags

Specified by:

withFlags in class Ref<T extends ACell>

Parameters:

newFlags - New flags to set

Returns:

Updated Ref