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_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.
RefDirect<T>	ensureCanonical()	Ensures this Ref is canonical
boolean	equals(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.
RefDirect<T>	toDirect()	Converts this Ref to a RefDirect
RefSoft<T>	toSoft(AStore store)	Converts this Ref to a RefSoft.
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

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

Methods inherited from class convex.core.data.AObject

attachEncoding, getEncoding, print, 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)

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 RefDirect<T> toDirect()

Description copied from class: Ref

Converts this Ref to a RefDirect

Specified by:

toDirect in class Ref<T extends ACell>

Returns:

Direct Ref

toSoft

public RefSoft<T> toSoft(AStore store)

Description copied from class: Ref

Converts this Ref to a RefSoft. Does not perform any persistence: doing this may make MissingDataExceptions happen.

Specified by:

toSoft in class Ref<T extends ACell>

Parameters:

store - store to set

Returns:

Direct Ref

equals

public boolean equals(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:

equals 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 Value 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. May be identical if value unchanged

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.

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 current store. May cause a read to the 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

ensureCanonical

public RefDirect<T> ensureCanonical()

Description copied from class: Ref

Ensures this Ref is canonical

Specified by:

ensureCanonical in class Ref<T extends ACell>

Returns:

this Ref if already canonical, potentially a new Ref with canonical value otherwise