Package convex.core.data

Class RefSoft<T extends ACell>

java.lang.Object

convex.core.data.AObject

convex.core.data.Ref<T>

convex.core.data.RefSoft<T>

Type Parameters:

T - Type of referenced Cell

All Implemented Interfaces:

IValidated, IWriteable, Comparable<Ref<T>>

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

Reference class implemented via a soft reference and store lookup. Ref makes use of a soft reference to values, allowing memory to be reclaimed by the garbage collector when not required. A MissingDataException will occur with any attempt to deference this Ref when the value is not present and not stored in the current store. Instances of this class should usually be be STORED, otherwise data loss may occur due to garbage collection. However UNKNOWN RefSoft may exist temporarily (e.g. reading Refs from external messages) RefSoft must always have a non-null hash, to ensure lookup capability in store. RefSoft must always store a canonical value, if any

Field Summary

Fields

Modifier and Type	Field	Description
protected SoftReference<T>	softRef	SoftReference to value.
protected final AStore	store	SoftReference to value.

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

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	RefSoft(AStore store, Hash hash)
protected	RefSoft(AStore store, SoftReference<T> ref, Hash hash, int flags)
protected	RefSoft(AStore store, T value, Hash hash, int flags)

Method Summary

Modifier and Type	Method	Description
static <T extends ACell> RefSoft<T>	create(AStore store, T value, int flags)
static <T extends ACell> RefSoft<T>	createForHash(Hash hash)	Create a RefSoft with a Hash reference.
Ref<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.
AStore	getStore()
T	getValue()	Gets the value from this Ref.
boolean	hasReference()	Checks if this Ref still has a local reference
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.
RefSoft<T>	withFlags(int newFlags)	Create a new Ref of the same type with updated flags
RefSoft<T>	withStore(AStore store)
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

Field Details

softRef

protected SoftReference<T extends ACell> softRef

SoftReference to value. Might get updated to a fresh instance.

store

protected final AStore store

SoftReference to value. Might get updated to a fresh instance.

Constructor Details

RefSoft

protected RefSoft(AStore store,
 SoftReference<T> ref,
 Hash hash,
 int flags)

RefSoft

protected RefSoft(AStore store,
 T value,
 Hash hash,
 int flags)

RefSoft

protected RefSoft(AStore store,
 Hash hash)

Method Details

withFlags

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

create

public static <T extends ACell> RefSoft<T> create(AStore store,
 T value,
 int flags)

createForHash

public static <T extends ACell> RefSoft<T> createForHash(Hash hash)

Create a RefSoft with a Hash reference. Attempts to get the value will trigger a store lookup, which may in turn cause a MissingDataException if not found.

Type Parameters:

T - Type of value

Parameters:

hash - Hash ID of value.

Returns:

New RefSoft instance

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

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.

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

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

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

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

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

withStore

public RefSoft<T> withStore(AStore store)

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.

ensureCanonical

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

getStore

public AStore getStore()

hasReference

public boolean hasReference()

Checks if this Ref still has a local reference

Returns:

True if an in memory reference exists