Package convex.core.data

Class ACell

java.lang.Object

convex.core.data.AObject

convex.core.data.ACell

All Implemented Interfaces:

IValidated, IWriteable

Direct Known Subclasses:

ACountable, AFn, AOp, APrimitive, Syntax

public abstract class ACell
extends AObject
implements IWriteable, IValidated

Abstract base class for Cells. Cells may contain Refs to other Cells, which can be tested with getRefCount() All data objects intended for on-chain usage / serialisation should extend this. "It is better to have 100 functions operate on one data structure than to have 10 functions operate on 10 data structures." - Alan Perlis

Field Summary

Fields

Modifier and Type	Field	Description
protected Ref<ACell>	cachedRef	Cached Ref.
protected long	memorySize	We cache the computed memorySize.

Fields inherited from class convex.core.data.AObject

encoding

Constructor Summary

Constructors

Constructor	Description
ACell()

Method Summary

Modifier and Type	Method	Description
void	attachMemorySize(long memorySize)	Updates the memorySize of this Cell Not valid for embedded Cells, may throw IllegalOperationException()
void	attachRef(Ref<?> ref)	Updates the cached ref of this Cell
Blob	cachedEncoding()	Gets the cached blob representing this Cell's Encoding in binary format, if it exists.
protected final Hash	cachedHash()	Gets the Hash if already computed, or null if not yet available
protected long	calcMemorySize()	Calculates the Memory Size for this Cell.
protected final Blob	createEncoding()	Creates the encoding for this cell.
protected <R extends ACell> Ref<R>	createRef()	Creates a new Ref for this Cell
abstract int	encode(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, including a tag byte which will be written first.
protected abstract int	encodeRaw(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, excluding the tag byte.
abstract boolean	equals(ACell a)	Checks for equality with another Cell.
boolean	equals(Object a)
protected static boolean	genericEquals(ACell a, ACell b)	Generic Cell equality, use only if better implementation not available.
final <T extends ACell> T	getCanonical()	Gets the canonical representation of this Cell.
<R extends ACell> Ref<R>[]	getChildRefs()	Gets an array of child Refs for this Cell, in the same order as order accessible by getRef.
final Blob	getEncoding()	Gets the canonical encoded byte representation of this cell.
int	getEncodingLength()	Method to calculate the encoding length of a Cell.
final Hash	getHash()	Hash of data Encoding of this cell, equivalent to the Value ID.
final long	getMemorySize()	Gets the Memory Size of this Cell, computing it if required.
static long	getMemorySize(ACell a)	Gets the Memory Size of a Cell, computing it if required.
final <R extends ACell> Ref<R>	getRef()	Gets the Ref for this Cell, creating a new direct reference if necessary
<R extends ACell> Ref<R>	getRef(int i)	Gets a numbered child Ref from within this Cell.
int	getRefCount()	Gets the number of Refs contained within this Cell.
abstract byte	getTag()	Gets the tag byte for this cell.
AType	getType()	Gets the most specific known runtime Type for this Cell.
int	hashCode()	Gets the Java hashCode for this cell.
abstract boolean	isCanonical()	Returns true if this Cell is in a canonical representation.
abstract boolean	isCVMValue()	Returns true if this cell is a first class CVM Value allowable in the CVM state Sub-structural cells that are not themselves first class values should return false Records and types that are not permissible on the CVM should return false.
abstract boolean	isDataValue()	Returns true if this cell instance is a first class value, i.e.
boolean	isEmbedded()	Determines if this Cell Represents an embedded object.
protected abstract ACell	toCanonical()	Converts this Cell to a canonical version.
AString	toCVMString(long limit)	Returns the CVM String representation of this Cell.
String	toString()	Returns the Java String representation of this Cell.
ACell	updateRefs(IRefFunction func)	Updates all Refs in this object using the given function.
void	validate()	Validates the complete structure of this object.
abstract void	validateCell()	Validates the local structure and invariants of this cell.

Methods inherited from class convex.core.data.AObject

attachEncoding, print, print, print

Methods inherited from class java.lang.Object

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

Methods inherited from interface convex.core.data.IWriteable

estimatedEncodingSize

Field Details

memorySize

protected long memorySize

We cache the computed memorySize. May be 0 for embedded objects -1 is initial value for when size is not calculated

cachedRef

protected Ref<ACell> cachedRef

Cached Ref. This is useful to manage persistence. Also cached Ref MUST refer to canonical value

Constructor Details

ACell

public ACell()

Method Details

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

Throws:

InvalidDataException - If the data Value is invalid in any way

validateCell

public abstract void validateCell()
                           throws InvalidDataException

Validates the local structure and invariants of this cell. Called by validate() super implementation. Should validate directly contained data, but should not validate all other structure of this cell. In particular, should not traverse potentially missing child Refs.

Throws:

InvalidDataException - If the Cell is invalid

getHash

public final Hash getHash()

Hash of data Encoding of this cell, equivalent to the Value ID. Calling this method may force hash computation if needed.

Returns:

The Hash of this cell's encoding.

getTag

public abstract byte getTag()

Gets the tag byte for this cell. The tag byte is always equal to the first byte of the Cell's canonical Encoding, and is sufficient to distinguish how to read the rest of the encoding.

Returns:

Tag byte for this Cell

cachedHash

protected final Hash cachedHash()

Gets the Hash if already computed, or null if not yet available

Returns:

Cached Hash value, or null if not available

hashCode

public int hashCode()

Gets the Java hashCode for this cell. Must be consistent with equals. Default is the hashCode of the Encoding blob, since this is consistent with encoding-based equality. However, different Types may provide more efficient hashcodes provided that the usual invariants are preserved

Overrides:

hashCode in class Object

Returns:

integer hash code.

equals

public boolean equals(Object a)

Overrides:

equals in class Object

getEncoding

public final Blob getEncoding()

Gets the canonical encoded byte representation of this cell.

Overrides:

getEncoding in class AObject

Returns:

A Blob representing this cell in encoded form

getCanonical

public final <T extends ACell> T getCanonical()

Gets the canonical representation of this Cell. O(1) if canonical representation is already generated, may be O(n) otherwise.

Returns:

Canonical version of this cell in encoded form

equals

public abstract boolean equals(ACell a)

Checks for equality with another Cell. In general, Cells are considered equal if they have the same canonical representation, i.e. an identical encoding with the same hash value. Subclasses SHOULD override this if they have a more efficient equals implementation. MUST NOT require reads from Store.

Parameters:

a - Cell to compare with. May be null.

Returns:

True if this cell is equal to the other object

genericEquals

protected static boolean genericEquals(ACell a,
 ACell b)

Generic Cell equality, use only if better implementation not available.

Parameters:

a - First cell to compare

b - Second cell to compare

Returns:

True if cells are equal, false otherwise

encode

public abstract int encode(byte[] bs,
 int pos)

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

Parameters:

bs - A byte array to which to write the encoding

pos - The offset into the byte array

Returns:

New position after writing

encodeRaw

protected abstract int encodeRaw(byte[] bs,
 int pos)

Writes this Cell's encoding to a byte array, excluding the tag byte.

Parameters:

bs - A byte array to which to write the encoding

pos - The offset into the byte array

Returns:

New position after writing

createEncoding

protected final Blob createEncoding()

Creates the encoding for this cell. Cell must be canonical, or else an error may occur. The encoding itself is a raw Blob, which may be non-canonical.

Specified by:

createEncoding in class AObject

Returns:

Blob Encoding of Object

toString

public String toString()

Returns the Java String representation of this Cell. The String representation is intended to be a easy-to-read textual representation of the Cell's data content.

Overrides:

toString in class Object

toCVMString

public AString toCVMString(long limit)

Returns the CVM String representation of this Cell. Normally, this is as printed, but may be different for some types. SHOULD return null in O(1) time if the length of the CVM String can be proved to exceed the limit. MUST complete in O(limit) time and space otherwise The String representation is intended to be a easy-to-read textual representation of the Cell's data content.

Parameters:

limit - Limit of CVM String length in UTF-8 bytes

Returns:

CVM String, or null if limit exceeded

cachedEncoding

public Blob cachedEncoding()

Gets the cached blob representing this Cell's Encoding in binary format, if it exists.

Returns:

The cached blob for this cell, or null if not yet available.

calcMemorySize

protected long calcMemorySize()

Calculates the Memory Size for this Cell. Assumes not already calculated Requires any child Refs to be either direct or of persisted in store at minimum, or you might get a MissingDataException

Returns:

Memory Size of this Cell

getEncodingLength

public int getEncodingLength()

Method to calculate the encoding length of a Cell. May be overridden to avoid creating encodings during memory size calculations. This reduces hashing!

Returns:

Exact encoding length of this Cell

getMemorySize

public final long getMemorySize()

Gets the Memory Size of this Cell, computing it if required. The memory size is the total storage requirement for this cell. Embedded cells do not require storage for their own encoding, but may require storage for nested branches.

Returns:

Memory Size of this Cell

getMemorySize

public static long getMemorySize(ACell a)

Gets the Memory Size of a Cell, computing it if required. The memory size is the total storage requirement for this cell. Embedded cells do not require storage for their own encoding, but may require storage for nested branches.

Returns:

Memory Size of this Cell

isEmbedded

public boolean isEmbedded()

Determines if this Cell Represents an embedded object. Embedded objects are encoded directly into the encoding of the containing Cell (avoiding the need for a hashed reference). Subclasses should override this if they have a cheap O(1) way to determine if they are embedded or otherwise.

Returns:

true if Cell is embedded, false otherwise

isCanonical

public abstract boolean isCanonical()

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.

Returns:

true if the object is in canonical format, false otherwise

toCanonical

protected abstract ACell toCanonical()

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

Returns:

Canonical version of Cell

isCVMValue

public abstract boolean isCVMValue()

Returns true if this cell is a first class CVM Value allowable in the CVM state Sub-structural cells that are not themselves first class values should return false Records and types that are not permissible on the CVM should return false. Pretty much everything else should return true. Note: CVM values might not be in a canonical format, e.g. temporary data structures

Returns:

true if the object is a CVM Value, false otherwise

isDataValue

public abstract boolean isDataValue()

Returns true if this cell instance is a first class value, i.e. not a component of a larger data structure Sub-structural cells that are not themselves first class values should return false Everything else should return true.

Returns:

true if the object is a Value, false otherwise

getRef

public final <R extends ACell> Ref<R> getRef()

Gets the Ref for this Cell, creating a new direct reference if necessary

Type Parameters:

R - Type of Cell

Returns:

Ref for this Cell

createRef

protected <R extends ACell> Ref<R> createRef()

Creates a new Ref for this Cell

Type Parameters:

R - Type of Cell

Returns:

New Ref instance

getRefCount

public int getRefCount()

Gets the number of Refs contained within this Cell. This number is final / immutable for any given instance and is defined by the Cell encoding rules. Contained Refs may be either external or embedded.

Returns:

The number of Refs in this Cell

getRef

public <R extends ACell> Ref<R> getRef(int i)

Gets a numbered child Ref from within this Cell. WARNING: May need to convert to a canonical instance

Type Parameters:

R - Type of referenced Cell

Parameters:

i - Index of ref to get

Returns:

The Ref at the specified index

Throws:

IndexOutOfBoundsException - if the Ref index is invalid

updateRefs

public ACell updateRefs(IRefFunction func)

Updates all Refs in this object using the given function. The function *must not* change the hash value of Refs, in order to ensure structural integrity of modified data structures. The implementation *should* re-attach any original encoding in order to prevent re-encoding or surplus hashing This is a building block for a very sneaky trick that enables use to do a lot of efficient operations on large trees of smart references. Must return the same object if no Refs are altered.

Parameters:

func - Ref update function

Returns:

Cell with updated Refs

getChildRefs

public <R extends ACell> Ref<R>[] getChildRefs()

Gets an array of child Refs for this Cell, in the same order as order accessible by getRef. Concrete implementations may override this to optimise performance.

Type Parameters:

R - Type of referenced Cell

Returns:

Array of Refs

getType

public AType getType()

Gets the most specific known runtime Type for this Cell.

Returns:

The Type of this Call

attachMemorySize

public void attachMemorySize(long memorySize)

Updates the memorySize of this Cell Not valid for embedded Cells, may throw IllegalOperationException()

Parameters:

memorySize - Memory size to assign

attachRef

public void attachRef(Ref<?> ref)

Updates the cached ref of this Cell

Parameters:

ref - Ref to assign