Module convex.core

Package convex.core

Class Result

java.lang.Object

convex.core.data.AObject

convex.core.data.ACell

convex.core.data.ACountable<MapEntry<Keyword,ACell>>

convex.core.data.ADataStructure<MapEntry<Keyword,ACell>>

convex.core.data.AMap<Keyword,ACell>

convex.core.data.ARecord

convex.core.data.ARecordGeneric

convex.core.Result

All Implemented Interfaces:

IAssociative<Keyword,ACell>, IValidated, IWriteable, Map<Keyword,ACell>

public final class Result
extends ARecordGeneric

Class representing the result of a Convex interaction (typically a query or transaction). A Result is typically used to communicate the outcome of a query or a transaction from a peer to a client. Contains:

1. Message ID - used for message correlation
2. Result value - Any CVM value as the result (may be an error message)
3. Error Code - Error Code, or null if the Result was a success
4. Log Records
5. Additional info

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Field Summary

Fields inherited from class convex.core.data.ARecordGeneric

format, values

Fields inherited from class convex.core.data.ARecord

DEFAULT_VALUE

Fields inherited from class convex.core.data.ADataStructure

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
static Result	buildFromVector(AVector<ACell> values)
static Result	create(CVMLong id, ACell value)	Create a Result
static Result	create(CVMLong id, ACell value, ACell errorCode)	Create a Result
static Result	create(CVMLong id, ACell value, ACell errorCode, AHashMap<Keyword,ACell> info)	Create a Result
static Result	create(CVMLong id, ACell value, ACell errorCode, AVector<AVector<ACell>> log, AHashMap<Keyword,ACell> info)	Create a Result
int	encode(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, including a tag byte which will be written first.
static Result	error(Keyword errorCode, AString message)
static Result	error(Keyword errorCode, String message)
static Result	fromContext(CVMLong id, ResultContext rc)	Constructs a Result from a Context
static Result	fromContext(Context ctx)	Constructs a Result from a Context.
static Result	fromException(Throwable e)	Constructs a result from a caught exception
ACell	getErrorCode()	Returns the Error Code from this Result.
RecordFormat	getFormat()	Gets the RecordFormat instance that describes this Record's layout
ACell	getID()	Returns the message ID for this result.
AMap<Keyword,ACell>	getInfo()	Returns the info for this Result.
AVector<AVector<ACell>>	getLog()	Returns the log for this Result.
Keyword	getSource()	Returns the error source code from this Result (see CAD11).
byte	getTag()	Gets the tag byte for this record type.
AVector<AString>	getTrace()	Returns the stack trace for this result.
<T extends ACell> T	getValue()	Returns the value for this result.
static Result	interruptThread()	Returns a Result representing a thread interrupt, AND sets the interrupt status on the current thread
boolean	isError()	Tests is the Result represents an Error
static Result	read(Blob b, int pos)	Reads a Result from a Blob encoding.
HashMap<String,Object>	toJSON()	Converts this result to a JSON representation.
void	validateCell()	Validates the local structure and invariants of this cell.
AVector<ACell>	values()	Gets a vector of values for this Record, in format-determined order
Result	withExtraInfo(Map<Keyword,ACell> extInfo)
Result	withID(ACell id)	Updates result with a given message ID.
Result	withInfo(Keyword k, ACell v)	Returns this Result with extra info field
Result	withSource(Keyword source)
protected Result	withValues(AVector<ACell> newValues)	Updates the record with a new set of values.

Methods inherited from class convex.core.data.ARecordGeneric

encodeRaw, entryAt, equals, equals, get, getRef, getRefCount, updateRefs

Methods inherited from class convex.core.data.ARecord

accumulateEntrySet, accumulateKeySet, accumulateValues, assoc, assocEntry, containsKey, containsValue, dissoc, dissoc, empty, entrySet, estimatedEncodingSize, forEach, get, getEntry, getEntryByHash, getKeyRefEntry, getKeys, getType, getValuesArray, isCanonical, isCVMValue, keySet, reduceEntries, reduceValues, toCanonical, toHashMap

Methods inherited from class convex.core.data.AMap

clear, conj, containsKey, containsKeyRef, containsValue, entryVector, filterValues, get, get, get, getElementRef, merge, print, put, putAll, remove, slice, slice

Methods inherited from class convex.core.data.ADataStructure

checkIndex, conjAll, count, isDataValue, isEmpty, size, toCVMString

Methods inherited from class convex.core.data.ACell

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

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

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, equals, getOrDefault, hashCode, isEmpty, merge, putIfAbsent, remove, replace, replace, replaceAll, size

Method Details

buildFromVector

public static Result buildFromVector(AVector<ACell> values)

create

public static Result create(CVMLong id,
 ACell value,
 ACell errorCode,
 AHashMap<Keyword,ACell> info)

Create a Result

Parameters:

id - ID of Result message

value - Result Value

errorCode - Error Code (may be null for success)

info - Additional info

Returns:

Result instance

create

public static Result create(CVMLong id,
 ACell value,
 ACell errorCode,
 AVector<AVector<ACell>> log,
 AHashMap<Keyword,ACell> info)

Create a Result

Parameters:

id - ID of Result message

value - Result Value

errorCode - Error Code (may be null for success)

log - Log entries created during transaction

info - Additional info

Returns:

Result instance

create

public static Result create(CVMLong id,
 ACell value,
 ACell errorCode)

Create a Result

Parameters:

id - ID of Result message

value - Result Value

errorCode - Error Code (may be null for success)

Returns:

Result instance

create

public static Result create(CVMLong id,
 ACell value)

Create a Result

Parameters:

id - ID of Result message

value - Result Value

Returns:

Result instance

error

public static Result error(Keyword errorCode,
 AString message)

error

public static Result error(Keyword errorCode,
 String message)

getID

public ACell getID()

Returns the message ID for this result. Message ID is an arbitrary ID assigned by a client requesting a transaction.

Returns:

ID from this result

getValue

public <T extends ACell> T getValue()

Returns the value for this result. The value is the result of transaction execution (may be an error message if the transaction failed)

Type Parameters:

T - Type of Value

Returns:

ID from this result

getTrace

public AVector<AString> getTrace()

Returns the stack trace for this result. May be null

Returns:

Trace vector from this result

getInfo

public AMap<Keyword,ACell> getInfo()

Returns the info for this Result. May be null

Returns:

Info map from this result

withInfo

public Result withInfo(Keyword k,
 ACell v)

Returns this Result with extra info field

Parameters:

k - Information field key

v - Information field value

Returns:

Updated result

withSource

public Result withSource(Keyword source)

getLog

public AVector<AVector<ACell>> getLog()

Returns the log for this Result. May be an empty vector.

Returns:

Log Vector from this Result

getErrorCode

public ACell getErrorCode()

Returns the Error Code from this Result. Normally this should be a Keyword. Will be null if no error occurred.

Returns:

Error code from this result

getSource

public Keyword getSource()

Returns the error source code from this Result (see CAD11). This a Keyword. Will be null if :source info not available

Returns:

Source code keyword from this result,. or null if not present / invalid

values

public AVector<ACell> values()

Description copied from class: ARecord

Gets a vector of values for this Record, in format-determined order

Specified by:

values in interface Map<Keyword,ACell>

Overrides:

values in class ARecordGeneric

Returns:

Vector of Values

withValues

protected Result withValues(AVector<ACell> newValues)

Description copied from class: ARecordGeneric

Updates the record with a new set of values. Returns this if and only if values vector is identical.

Specified by:

withValues in class ARecordGeneric

Parameters:

newValues - New values to use

Returns:

Updated Record

validateCell

public void validateCell()
                  throws InvalidDataException

Description copied from class: ACell

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.

Overrides:

validateCell in class ARecordGeneric

Throws:

InvalidDataException - If the Cell is invalid

encode

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

Description copied from class: ACell

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

Specified by:

encode in class ACell

Parameters:

bs - A byte array to which to write the encoding

pos - The offset into the byte array

Returns:

New position after writing

read

public static Result read(Blob b,
 int pos)
                   throws BadFormatException

Reads a Result from a Blob encoding. Assumes tag byte already checked.

Parameters:

b - Blob to read from

pos - Start position in Blob (location of tag byte)

Returns:

New decoded instance

Throws:

BadFormatException - In the event of any encoding error

isError

public boolean isError()

Tests is the Result represents an Error

Returns:

True if error, false otherwise

fromContext

public static Result fromContext(CVMLong id,
 ResultContext rc)

Constructs a Result from a Context

Parameters:

id - Id for Result

rc - ResultContext instance from which to extract Result

Returns:

New Result instance

withExtraInfo

public Result withExtraInfo(Map<Keyword,ACell> extInfo)

fromContext

public static Result fromContext(Context ctx)

Constructs a Result from a Context. No ResultContext implies we are not in a top level transaction, so minimise work

Parameters:

ctx - Context

Returns:

New Result instance

withID

public Result withID(ACell id)

Updates result with a given message ID. Used to tag Results for return to Clients

Parameters:

id - New Result message ID

Returns:

Updated Result

getTag

public byte getTag()

Description copied from class: ARecord

Gets the tag byte for this record type. The Tag is the byte used to identify the record in the binary encoding.

Specified by:

getTag in class ARecordGeneric

Returns:

Record tag byte

getFormat

public RecordFormat getFormat()

Description copied from class: ARecord

Gets the RecordFormat instance that describes this Record's layout

Specified by:

getFormat in class ARecord

Returns:

RecordFormat instance

fromException

public static Result fromException(Throwable e)

Constructs a result from a caught exception

Parameters:

e - Exception caught

Returns:

Result instance representing the exception (will be an error)

interruptThread

public static Result interruptThread()

Returns a Result representing a thread interrupt, AND sets the interrupt status on the current thread

Returns:

Result instance representing an interruption

toJSON

public HashMap<String,Object> toJSON()

Converts this result to a JSON representation. WARNING: some information may be lost because JSON is a terrible format.

Returns:

JSON Object containing values from this Result