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<Keyword,ACell>

convex.core.cvm.ACVMRecord

convex.core.cvm.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

Modifier and Type	Field	Description
static final Result	BAD_FORMAT
static final Result	CLOSED_CONNECTION
static final Result	FULL_CLIENT_BUFFER
static final Result	SENT_MESSAGE

Fields inherited from class convex.core.cvm.ARecordGeneric

format, values

Fields inherited from class convex.core.data.ARecord

DEFAULT_VALUE, tag

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)	Build a Result from a vector.
static Result	create(ACell id, ACell value)	Create a Result
static Result	create(ACell id, ACell value, ACell errorCode)	Create a Result
static Result	create(ACell id, ACell value, ACell errorCode, AHashMap<Keyword,ACell> info)	Create a Result
static Result	create(ACell id, ACell value, ACell errorCode, AVector<AVector<ACell>> log, AHashMap<Keyword,ACell> info)	Create a Result
static Result	error(Keyword errorCode, AString message)
static Result	error(Keyword errorCode, String message)
static Result	fromContext(Context ctx)	Constructs a Result from a Context.
static Result	fromContext(ACell id, ResultContext rc)	Constructs a Result from a Context
static Result	fromData(ACell data)	Construct a result from a cell of data
static Result	fromException(Throwable e)	Constructs a result from a caught exception
static Result	fromJSON(Object json)	Construct a result from a JSON structure.
ACell	getErrorCode()	Returns the Error Code from this Result.
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).
AVector<AString>	getTrace()	Returns the stack trace for this result.
<T extends ACell> T	getValue()	Returns the value for this result.
boolean	isError()	Tests is the Result represents an Error
static ACell	peekResultID(Blob messageData, int i)
boolean	print(BlobBuilder sb, long limit)	Prints this Object to a readable String Representation.
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	validate()	Validates the complete structure of this object.
void	validateCell()	Validates the local structure and invariants of this cell.
static Result	value(ACell value)
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.cvm.ARecordGeneric

encode, encodeRaw, entryAt, equals, equals, estimatedEncodingSize, get, getFormat, getRef, getRefCount, updateRefs, validateStructure

Methods inherited from class convex.core.cvm.ACVMRecord

get, getKeys, isCVMValue, keySet

Methods inherited from class convex.core.data.ARecord

accumulateEntries, accumulateKeySet, accumulateValues, assoc, assocEntry, containsKey, containsValue, dissoc, dissoc, empty, entrySet, forEach, get, getEntry, getEntryByHash, getKeyRefEntry, getTag, getType, getValuesArray, isCanonical, reduceEntries, reduceValues, toCanonical, toHashMap

Methods inherited from class convex.core.data.AMap

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

Methods inherited from class convex.core.data.ADataStructure

checkIndex, conjAll, count, isEmpty, size, toCVMString

Methods inherited from class convex.core.data.ACell

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

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

Field Details

CLOSED_CONNECTION

public static final Result CLOSED_CONNECTION

SENT_MESSAGE

public static final Result SENT_MESSAGE

FULL_CLIENT_BUFFER

public static final Result FULL_CLIENT_BUFFER

BAD_FORMAT

public static final Result BAD_FORMAT

Method Details

buildFromVector

public static Result buildFromVector(AVector<ACell> values)

Build a Result from a vector. WARNING: does not validate values

Parameters:

values -

Returns:

Result instance

create

public static Result create(ACell 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(ACell 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(ACell 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(ACell 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)

value

public static Result value(ACell value)

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 (or null if values not valid)

validateCell

public void validateCell()
                  throws InvalidDataException

Description copied from class: ACell

Validates the local structure and invariants of this cell. 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

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 ACell

Throws:

InvalidDataException - If the data Value is invalid in any way

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(ACell 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

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)

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

print

public boolean print(BlobBuilder sb,
 long limit)

Description copied from class: AObject

Prints this Object to a readable String Representation. SECURITY: Must halt and return false in O(1) time when limit of printing is exceeded otherwise DoS attacks may be possible.

Overrides:

print in class ARecord<Keyword,ACell>

Parameters:

sb - BlobBuilder to append to. May be partially written if print limit exceeded

limit - Limit of printing in string bytes

Returns:

True if fully printed within limit, false otherwise

fromData

public static Result fromData(ACell data)

Construct a result from a cell of data

Parameters:

data - Result or Map including Result fields

Returns:

Result value

Throws:

IllegalArgumentException - if data is of incorrect type

fromJSON

public static Result fromJSON(Object json)

Construct a result from a JSON structure. WARNING: some data may be lost

Parameters:

json - Result as represented in JSON

Returns:

Result containing key fields

Throws:

IllegalArgumentException - if data is of incorrect type

peekResultID

public static ACell peekResultID(Blob messageData,
 int i)
                          throws BadFormatException

Throws:

BadFormatException