Package com.oracle.truffle.api.interop

Class InteropLibrary

java.lang.Object

com.oracle.truffle.api.nodes.Node

com.oracle.truffle.api.library.Library

com.oracle.truffle.api.interop.InteropLibrary

All Implemented Interfaces:

NodeInterface, Cloneable

public abstract class InteropLibrary
extends Library

Represents the library that specifies the interoperability message protocol between Truffle languages, tools and embedders. Every method represents one message specified by the protocol. In the following text we will abbreviate interoperability with interop.

The interop API differentiates between the source and the target language. The source language is the language that implements/exports the message implementations. The implementations map types of the source language to the interop protocol as it is specified by the protocol. For example, language values that represent arrays or array like structures should implement the messages for array based access. This allows the target language to call the protocol without knowledge of the concrete source language. The target language embeds the interop protocol semantics as part of their existing language semantics. For example, language operations that access array elements in the target language should call array access messages for interop values.

The interop protocol only allows interop values to be used as receivers, return values or parameters of messages. Allowed Java types of interop values are:

• TruffleObject: Any object that implements the TruffleObject interface is interpreted according to the interop messages it exports. Truffle objects are expected but not required to export interop library messages.
• String and Character are interpreted as string value.
• Boolean is interpreted as boolean value.
• Byte, Short, Integer, Long, Float and Double are interpreted as number values.

Note that null is never a valid interop value. Instead, use a TruffleObject which implements isNull(Object) message.

The following type combinations are mutually exclusive and cannot return true for the type check message of the same receiver value:

• Null
• Boolean
• String
• Number
• Date, Time or TimeZone
• Duration
• Exception
• Meta-Object
• Iterator

All receiver values may have none, one or multiple of the following traits:

• executable
• instantiable
• pointer
• members
• hash entries
• array elements
• buffer elements
• language
• associated metaobject
• metaobject parents as array elements
• declaring meta object
• source location
• identity
• scope parent
• executable name
• exception message
• exception cause
• exception stack trace
• iterator

Naive and aware dates and times

If a date or time value has a timezone then it is called aware , otherwise naive

An aware time and date has sufficient knowledge of applicable algorithmic and political time adjustments, such as time zone and daylight saving time information, to locate itself relative to other aware objects. An aware object is used to represent a specific moment in time that is not open to interpretation.

A naive time and date does not contain enough information to unambiguously locate itself relative to other date/time objects. Whether a naive object represents Coordinated Universal Time (UTC), local time, or time in some other timezone is purely up to the program, just like it is up to the program whether a particular number represents metres, miles, or mass. Naive objects are easy to understand and to work with, at the cost of ignoring some aspects of reality.

Interop messages throw checked exceptions to indicate error states. The target language is supposed to always catch those exceptions and translate them into guest language errors of the target language. Interop message contracts are verified only if assertions (-ea) are enabled.

Since:

19.0

See Also:

• Reference documentation of Truffle Libraries.

Nested Class Summary

Nested classes/interfaces inherited from class com.oracle.truffle.api.nodes.Node

Node.Child, Node.Children

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	InteropLibrary()

Method Summary

Modifier and Type	Method	Description
BigInteger	asBigInteger(Object receiver)	Returns the receiver value as Java BigInteger if the number fits without loss of precision.
boolean	asBoolean(Object receiver)	Returns the Java boolean value if the receiver represents a boolean like value.
byte	asByte(Object receiver)	Returns the receiver value as Java byte primitive if the number fits without loss of precision.
LocalDate	asDate(Object receiver)	Returns the receiver as date if this object represents a date.
double	asDouble(Object receiver)	Returns the receiver value as Java double primitive if the number fits without loss of precision.
Duration	asDuration(Object receiver)	Returns the receiver as duration if this object represents a duration.
float	asFloat(Object receiver)	Returns the receiver value as Java float primitive if the number fits without loss of precision.
Instant	asInstant(Object receiver)	Returns the receiver as instant if this object represents an instant.
int	asInt(Object receiver)	Returns the receiver value as Java int primitive if the number fits without loss of precision.
long	asLong(Object receiver)	Returns the receiver value as Java long primitive if the number fits without loss of precision.
long	asPointer(Object receiver)	Returns the pointer value as long value if the receiver represents a pointer like value.
protected final boolean	assertAdopted()	Utility for libraries to require adoption before cached versions of nodes can be executed.
short	asShort(Object receiver)	Returns the receiver value as Java short primitive if the number fits without loss of precision.
String	asString(Object receiver)	Returns the Java string value if the receiver represents a string like value.
LocalTime	asTime(Object receiver)	Returns the receiver as time if this object represents a time.
ZoneId	asTimeZone(Object receiver)	Returns the receiver as timestamp if this object represents a timezone.
TruffleString	asTruffleString(Object receiver)	Returns the TruffleString value if the receiver represents a string like value.
Object	execute(Object receiver, Object... arguments)	Executes an executable value with the given arguments.
boolean	fitsInBigInteger(Object receiver)	Returns true if the receiver represents a number and its value fits in a Java BigInteger without loss of precision, else false.
boolean	fitsInByte(Object receiver)	Returns true if the receiver represents a number and its value fits in a Java byte primitive without loss of precision, else false.
boolean	fitsInDouble(Object receiver)	Returns true if the receiver represents a number and its value fits in a Java double primitive without loss of precision, else false.
boolean	fitsInFloat(Object receiver)	Returns true if the receiver represents a number and its value fits in a Java float primitive without loss of precision, else false.
boolean	fitsInInt(Object receiver)	Returns true if the receiver represents a number and its value fits in a Java int primitive without loss of precision, else false.
boolean	fitsInLong(Object receiver)	Returns true if the receiver represents a number and its value fits in a Java long primitive without loss of precision, else false.
boolean	fitsInShort(Object receiver)	Returns true if the receiver represents a number and its value fits in a Java short primitive without loss of precision, else false.
long	getArraySize(Object receiver)	Returns the array size of the receiver.
long	getBufferSize(Object receiver)	Returns the buffer size of the receiver, in bytes.
Object	getDeclaringMetaObject(Object receiver)	Returns declaring meta object.
Object	getExceptionCause(Object receiver)	Returns the internal cause of the receiver.
int	getExceptionExitStatus(Object receiver)	Returns exception exit status of the receiver.
Object	getExceptionMessage(Object receiver)	Returns exception message of the receiver.
Object	getExceptionStackTrace(Object receiver)	Returns the exception stack trace of the receiver that is of type exception.
ExceptionType	getExceptionType(Object receiver)	Returns exception type of the receiver.
Object	getExecutableName(Object receiver)	Returns executable name of the receiver.
static LibraryFactory<InteropLibrary>	getFactory()	Returns the library factory for the interop library.
Object	getHashEntriesIterator(Object receiver)	Returns the hash entries iterator for the receiver.
Object	getHashKeysIterator(Object receiver)	Returns the hash keys iterator for the receiver.
long	getHashSize(Object receiver)	Returns the number of receiver entries.
Object	getHashValuesIterator(Object receiver)	Returns the hash values iterator for the receiver.
Object	getIterator(Object receiver)	Returns the iterator for the receiver.
Object	getIteratorNextElement(Object receiver)	Returns the next element in the iteration.
Class<? extends TruffleLanguage<?>>	getLanguage(Object receiver)	Returns the the original language of the receiver value.
final Object	getMembers(Object receiver)	Short-cut for getMembers(receiver, false).
Object	getMembers(Object receiver, boolean includeInternal)	Returns an array of member name strings.
Object	getMetaObject(Object receiver)	Returns the metaobject that is associated with this value.
Object	getMetaParents(Object receiver)	Returns an array like hasArrayElements(Object) of metaobjects that are direct parents (super types) of this metaobject.
Object	getMetaQualifiedName(Object metaObject)	Returns the qualified name of a metaobject as string.
Object	getMetaSimpleName(Object metaObject)	Returns the simple name of a metaobject as string.
Object	getScopeParent(Object receiver)	Returns the parent scope object if it has the parent.
SourceSection	getSourceLocation(Object receiver)	Returns the declared source location of the receiver value.
static InteropLibrary	getUncached()	Returns the uncached automatically dispatched version of the interop library.
static InteropLibrary	getUncached(Object v)	Returns the uncached manually dispatched version of the interop library.
boolean	hasArrayElements(Object receiver)	Returns true if the receiver may have array elements.
boolean	hasBufferElements(Object receiver)	Returns true if the receiver may have buffer elements.
boolean	hasDeclaringMetaObject(Object receiver)	Returns true if the receiver has a declaring meta object.
boolean	hasExceptionCause(Object receiver)	Returns true if the receiver is an exception with an attached internal cause.
boolean	hasExceptionMessage(Object receiver)	Returns true if the receiver is an exception that has an exception message.
boolean	hasExceptionStackTrace(Object receiver)	Returns true if the receiver is an exception and has a stack trace.
boolean	hasExecutableName(Object receiver)	Returns true if the receiver has an executable name.
boolean	hasHashEntries(Object receiver)	Returns true if the receiver may have hash entries.
final boolean	hasIdentity(Object receiver)	Returns true if and only if the receiver specifies identity, else false.
boolean	hasIterator(Object receiver)	Returns true if the receiver provides an iterator.
boolean	hasIteratorNextElement(Object receiver)	Returns true if the receiver is an iterator which has more elements, else false.
boolean	hasLanguage(Object receiver)	Returns true if the receiver originates from a language, else false .
boolean	hasMemberReadSideEffects(Object receiver, String member)	Returns true if reading a member may cause a side-effect.
boolean	hasMembers(Object receiver)	Returns true if the receiver may have members.
boolean	hasMemberWriteSideEffects(Object receiver, String member)	Returns true if writing a member may cause a side-effect, besides the write operation of the member.
boolean	hasMetaObject(Object receiver)	Returns true if the receiver value has a metaobject associated.
boolean	hasMetaParents(Object receiver)	Returns true if the receiver value is a metaobject which has parents (super types).
boolean	hasScopeParent(Object receiver)	Returns true if this scope has an enclosing parent scope, else false.
boolean	hasSourceLocation(Object receiver)	Returns true if the receiver value has a declared source location attached, else false.
int	identityHashCode(Object receiver)	Returns an identity hash code for the receiver if it has identity.
Object	instantiate(Object receiver, Object... arguments)	Instantiates the receiver value with the given arguments.
Object	invokeMember(Object receiver, String member, Object... arguments)	Invokes a member for a given receiver and arguments.
final boolean	isArrayElementExisting(Object receiver, long index)	Returns true if the array element is existing.
boolean	isArrayElementInsertable(Object receiver, long index)	Returns true if a given array element index is not existing and insertable.
boolean	isArrayElementModifiable(Object receiver, long index)	Returns true if a given array element index is existing and writable.
boolean	isArrayElementReadable(Object receiver, long index)	Returns true if a given array element is readable.
boolean	isArrayElementRemovable(Object receiver, long index)	Returns true if a given array element index is existing and removable.
final boolean	isArrayElementWritable(Object receiver, long index)	Returns true if the array element is modifiable or insertable.
boolean	isBoolean(Object receiver)	Returns true if the receiver represents a boolean like value, else false.
boolean	isBufferWritable(Object receiver)	Returns true if the receiver is a modifiable buffer.
boolean	isDate(Object receiver)	Returns true if this object represents a date, else false.
boolean	isDuration(Object receiver)	Returns true if this object represents a duration, else false.
boolean	isException(Object receiver)	Returns true if the receiver value represents a throwable exception/error}.
boolean	isExceptionIncompleteSource(Object receiver)	Returns true if receiver value represents an incomplete source exception.
boolean	isExecutable(Object receiver)	Returns true if the receiver represents an executable value, else false.
boolean	isHashEntryExisting(Object receiver, Object key)	Returns true if mapping for a given key is existing.
boolean	isHashEntryInsertable(Object receiver, Object key)	Returns true if mapping for the specified key does not exist and is writable.
boolean	isHashEntryModifiable(Object receiver, Object key)	Returns true if mapping for the specified key exists and is writable.
boolean	isHashEntryReadable(Object receiver, Object key)	Returns true if mapping for the specified key exists and is readable.
boolean	isHashEntryRemovable(Object receiver, Object key)	Returns true if mapping for the specified key exists and is removable.
boolean	isHashEntryWritable(Object receiver, Object key)	Returns true if mapping for the specified key is modifiable or insertable.
boolean	isIdentical(Object receiver, Object other, InteropLibrary otherInterop)	Returns true if two values represent the the identical value, else false.
protected TriState	isIdenticalOrUndefined(Object receiver, Object other)	Returns TRUE if the receiver is or FALSE if the receiver is not identical to the other value.
final boolean	isInstant(Object receiver)	Returns true if the receiver represents an instant.
boolean	isInstantiable(Object receiver)	Returns true if the receiver represents an instantiable value, else false.
boolean	isIterator(Object receiver)	Returns true if the receiver represents an iterator.
final boolean	isMemberExisting(Object receiver, String member)	Returns true if the member is existing.
boolean	isMemberInsertable(Object receiver, String member)	Returns true if a given member is not existing and writable.
boolean	isMemberInternal(Object receiver, String member)	Returns true if a member is internal.
boolean	isMemberInvocable(Object receiver, String member)	Returns true if a given member is invocable.
boolean	isMemberModifiable(Object receiver, String member)	Returns true if a given member is existing and writable.
boolean	isMemberReadable(Object receiver, String member)	Returns true if a given member is readable.
boolean	isMemberRemovable(Object receiver, String member)	Returns true if a given member is existing and removable.
final boolean	isMemberWritable(Object receiver, String member)	Returns true if the member is modifiable or insertable.
boolean	isMetaInstance(Object receiver, Object instance)	Returns true if the given instance is of the provided receiver metaobject, else false.
boolean	isMetaObject(Object receiver)	Returns true if the receiver value represents a metaobject.
boolean	isNull(Object receiver)	Returns true if the receiver represents a null like value, else false.
boolean	isNumber(Object receiver)	Returns true if the receiver represents a number value, else false.
boolean	isPointer(Object receiver)	Returns true if the receiver value represents a native pointer.
boolean	isScope(Object receiver)	Returns true if the value represents a scope object, else false.
boolean	isString(Object receiver)	Returns true if the receiver represents a string value, else false.
boolean	isTime(Object receiver)	Returns true if this object represents a time, else false.
boolean	isTimeZone(Object receiver)	Returns true if this object represents a timezone, else false.
static boolean	isValidProtocolValue(Object value)	Utility to check whether a value is a valid interop protocol value.
static boolean	isValidValue(Object receiver)	Utility to check whether a value is a valid interop value.
Object	readArrayElement(Object receiver, long index)	Reads the value of an array element by index.
void	readBuffer(Object receiver, long byteOffset, byte[] destination, int destinationOffset, int length)	Reads bytes from the receiver object into the specified byte array.
byte	readBufferByte(Object receiver, long byteOffset)	Reads the byte from the receiver object at the given byte offset from the start of the buffer.
double	readBufferDouble(Object receiver, ByteOrder order, long byteOffset)	Reads the double from the receiver object in the given byte order at the given byte offset from the start of the buffer.
float	readBufferFloat(Object receiver, ByteOrder order, long byteOffset)	Reads the float from the receiver object in the given byte order at the given byte offset from the start of the buffer.
int	readBufferInt(Object receiver, ByteOrder order, long byteOffset)	Reads the int from the receiver object in the given byte order at the given byte offset from the start of the buffer.
long	readBufferLong(Object receiver, ByteOrder order, long byteOffset)	Reads the long from the receiver object in the given byte order at the given byte offset from the start of the buffer.
short	readBufferShort(Object receiver, ByteOrder order, long byteOffset)	Reads the short from the receiver object in the given byte order at the given byte offset from the start of the buffer.
Object	readHashValue(Object receiver, Object key)	Reads the value for the specified key.
Object	readHashValueOrDefault(Object receiver, Object key, Object defaultValue)	Reads the value for the specified key or returns the defaultValue when the mapping for the specified key does not exist or is not readable.
Object	readMember(Object receiver, String member)	Reads the value of a given member.
void	removeArrayElement(Object receiver, long index)	Remove an array element from the receiver object.
void	removeHashEntry(Object receiver, Object key)	Removes the mapping for a given key from the receiver.
void	removeMember(Object receiver, String member)	Removes a member from the receiver object.
RuntimeException	throwException(Object receiver)	Throws the receiver object as an exception of the source language, as if it was thrown by the source language itself.
final Object	toDisplayString(Object receiver)	Converts the receiver to a human readable string of the language.
Object	toDisplayString(Object receiver, boolean allowSideEffects)	Converts the receiver to a human readable string.
void	toNative(Object receiver)	Attempts to transform a receiver to a value that represents a raw native pointer.
void	writeArrayElement(Object receiver, long index, Object value)	Writes the value of an array element by index.
void	writeBufferByte(Object receiver, long byteOffset, byte value)	Writes the given byte from the receiver object at the given byte offset from the start of the buffer.
void	writeBufferDouble(Object receiver, ByteOrder order, long byteOffset, double value)	Writes the given double from the receiver object in the given byte order at the given byte offset from the start of the buffer.
void	writeBufferFloat(Object receiver, ByteOrder order, long byteOffset, float value)	Writes the given float from the receiver object in the given byte order at the given byte offset from the start of the buffer.
void	writeBufferInt(Object receiver, ByteOrder order, long byteOffset, int value)	Writes the given int from the receiver object in the given byte order at the given byte offset from the start of the buffer.
void	writeBufferLong(Object receiver, ByteOrder order, long byteOffset, long value)	Writes the given long from the receiver object in the given byte order at the given byte offset from the start of the buffer.
void	writeBufferShort(Object receiver, ByteOrder order, long byteOffset, short value)	Writes the given short from the receiver object in the given byte order at the given byte offset from the start of the buffer.
void	writeHashEntry(Object receiver, Object key, Object value)	Associates the specified value with the specified key in the receiver.
void	writeMember(Object receiver, String member, Object value)	Writes the value of a given member.

Methods inherited from class com.oracle.truffle.api.library.Library

accepts

Methods inherited from class com.oracle.truffle.api.nodes.Node

accept, adoptChildren, atomic, atomic, copy, deepCopy, getChildren, getCost, getDebugProperties, getDescription, getEncapsulatingSourceSection, getLock, getParent, getRootNode, getSourceSection, insert, insert, isAdoptable, isSafelyReplaceableBy, notifyInserted, onReplace, replace, replace, reportPolymorphicSpecialize, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

InteropLibrary

protected InteropLibrary()

Since:

19.0

Method Details

isNull

public boolean isNull(Object receiver)

Returns true if the receiver represents a null like value, else false. Most object oriented languages have one or many values representing null values. Invoking this message does not cause any observable side-effects.

Since:

19.0

isBoolean

public boolean isBoolean(Object receiver)

Returns true if the receiver represents a boolean like value, else false. Invoking this message does not cause any observable side-effects.

Since:

19.0

See Also:

• asBoolean(Object)

asBoolean

public boolean asBoolean(Object receiver)
                  throws UnsupportedMessageException

Returns the Java boolean value if the receiver represents a boolean like value.

Throws:

UnsupportedMessageException - if and only if isBoolean(Object) returns false for the same receiver.

Since:

19.0

See Also:

• isBoolean(Object)

isExecutable

public boolean isExecutable(Object receiver)

Returns true if the receiver represents an executable value, else false. Functions, methods or closures are common examples of executable values. Invoking this message does not cause any observable side-effects. Note that receiver values which are executable might also be instantiable.

Since:

19.0

See Also:

• execute(Object, Object...)

execute

public Object execute(Object receiver,
 Object... arguments)
               throws UnsupportedTypeException,
ArityException,
UnsupportedMessageException

Executes an executable value with the given arguments.

Throws:

UnsupportedTypeException - if one of the arguments is not compatible to the executable signature. The exception is thrown on best effort basis, dynamic languages may throw their own exceptions if the arguments are wrong.

ArityException - if the number of expected arguments does not match the number of actual arguments.

UnsupportedMessageException - if and only if isExecutable(Object) returns false for the same receiver.

Since:

19.0

See Also:

• isExecutable(Object)

hasExecutableName

public boolean hasExecutableName(Object receiver)

Returns true if the receiver has an executable name. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

20.3

See Also:

• getExecutableName(Object)

getExecutableName

public Object getExecutableName(Object receiver)
                         throws UnsupportedMessageException

Returns executable name of the receiver. Throws UnsupportedMessageException when the receiver is has no executable name. The return value is an interop value that is guaranteed to return true for isString(Object).

Throws:

UnsupportedMessageException

Since:

20.3

See Also:

• hasExecutableName(Object)

hasDeclaringMetaObject

public boolean hasDeclaringMetaObject(Object receiver)

Returns true if the receiver has a declaring meta object. The declaring meta object is the meta object of the executable or meta object that declares the receiver value. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

20.3

See Also:

• getDeclaringMetaObject(Object)

getDeclaringMetaObject

public Object getDeclaringMetaObject(Object receiver)
                              throws UnsupportedMessageException

Returns declaring meta object. The declaring meta object is the meta object of declaring executable or meta object. Throws UnsupportedMessageException when the receiver is has no declaring meta object. The return value is an interop value that is guaranteed to return true for isMetaObject(Object).

Throws:

UnsupportedMessageException

Since:

20.3

See Also:

• hasDeclaringMetaObject(Object)

isInstantiable

public boolean isInstantiable(Object receiver)

Returns true if the receiver represents an instantiable value, else false. Contructors or metaobjects are typical examples of instantiable values. Invoking this message does not cause any observable side-effects. Note that receiver values which are executable might also be instantiable.

Since:

19.0

See Also:

• instantiate(Object, Object...)
• isMetaObject(Object)

instantiate

public Object instantiate(Object receiver,
 Object... arguments)
                   throws UnsupportedTypeException,
ArityException,
UnsupportedMessageException

Instantiates the receiver value with the given arguments. The returned object must be initialized correctly according to the language specification (e.g. by calling the constructor or initialization routine).

Throws:

UnsupportedTypeException - if one of the arguments is not compatible to the executable signature

ArityException - if the number of expected arguments does not match the number of actual arguments.

UnsupportedMessageException - if and only if isInstantiable(Object) returns false for the same receiver.

Since:

19.0

See Also:

• isExecutable(Object)

isString

public boolean isString(Object receiver)

Returns true if the receiver represents a string value, else false. Invoking this message does not cause any observable side-effects.

Since:

19.0

See Also:

• asString(Object)

asString

public String asString(Object receiver)
                throws UnsupportedMessageException

Returns the Java string value if the receiver represents a string like value.

Throws:

UnsupportedMessageException - if and only if isString(Object) returns false for the same receiver.

Since:

19.0

See Also:

• isString(Object)

asTruffleString

public TruffleString asTruffleString(Object receiver)
                              throws UnsupportedMessageException

Returns the TruffleString value if the receiver represents a string like value.

Throws:

UnsupportedMessageException - if and only if isString(Object) returns false for the same receiver.

Since:

21.3

See Also:

• isString(Object)

isNumber

public boolean isNumber(Object receiver)

Returns true if the receiver represents a number value, else false. Invoking this message does not cause any observable side-effects.

Since:

19.0

See Also:

• fitsInByte(Object)
• fitsInShort(Object)
• fitsInInt(Object)
• fitsInLong(Object)
• fitsInBigInteger(Object)
• fitsInFloat(Object)
• fitsInDouble(Object)
• asByte(Object)
• asShort(Object)
• asInt(Object)
• asLong(Object)
• asBigInteger(Object)
• asFloat(Object)
• asDouble(Object)

fitsInByte

public boolean fitsInByte(Object receiver)

Returns true if the receiver represents a number and its value fits in a Java byte primitive without loss of precision, else false. Invoking this message does not cause any observable side-effects.

Since:

19.0

See Also:

• isNumber(Object)
• asByte(Object)

fitsInShort

public boolean fitsInShort(Object receiver)

Returns true if the receiver represents a number and its value fits in a Java short primitive without loss of precision, else false. Invoking this message does not cause any observable side-effects.

Since:

19.0

See Also:

• isNumber(Object)
• asShort(Object)

fitsInInt

public boolean fitsInInt(Object receiver)

Returns true if the receiver represents a number and its value fits in a Java int primitive without loss of precision, else false. Invoking this message does not cause any observable side-effects.

Since:

19.0

See Also:

• isNumber(Object)
• asInt(Object)

fitsInLong

public boolean fitsInLong(Object receiver)

Returns true if the receiver represents a number and its value fits in a Java long primitive without loss of precision, else false. Invoking this message does not cause any observable side-effects.

Since:

19.0

See Also:

• isNumber(Object)
• asLong(Object)

fitsInBigInteger

public boolean fitsInBigInteger(Object receiver)

Returns true if the receiver represents a number and its value fits in a Java BigInteger without loss of precision, else false. Invoking this message does not cause any observable side-effects.

Since:

23.0

See Also:

• isNumber(Object)
• asBigInteger(Object)

fitsInFloat

public boolean fitsInFloat(Object receiver)

Returns true if the receiver represents a number and its value fits in a Java float primitive without loss of precision, else false. Invoking this message does not cause any observable side-effects.

Since:

19.0

See Also:

• isNumber(Object)
• asFloat(Object)

fitsInDouble

public boolean fitsInDouble(Object receiver)

Returns true if the receiver represents a number and its value fits in a Java double primitive without loss of precision, else false. Invoking this message does not cause any observable side-effects.

Since:

19.0

See Also:

• isNumber(Object)
• asDouble(Object)

asByte

public byte asByte(Object receiver)
            throws UnsupportedMessageException

Returns the receiver value as Java byte primitive if the number fits without loss of precision. Invoking this message does not cause any observable side-effects.

Throws:

UnsupportedMessageException - if and only if the receiver is not a isNumber(Object) or it does not fit without loss of precision.

Since:

19.0

See Also:

• isNumber(Object)
• fitsInByte(Object)

asShort

public short asShort(Object receiver)
              throws UnsupportedMessageException

Returns the receiver value as Java short primitive if the number fits without loss of precision. Invoking this message does not cause any observable side-effects.

Throws:

UnsupportedMessageException - if and only if the receiver is not a isNumber(Object) or it does not fit without loss of precision.

Since:

19.0

See Also:

• isNumber(Object)
• fitsInShort(Object)

asInt

public int asInt(Object receiver)
          throws UnsupportedMessageException

Returns the receiver value as Java int primitive if the number fits without loss of precision. Invoking this message does not cause any observable side-effects.

Throws:

UnsupportedMessageException - if and only if the receiver is not a isNumber(Object) or it does not fit without loss of precision.

Since:

19.0

See Also:

• isNumber(Object)
• fitsInInt(Object)

asLong

public long asLong(Object receiver)
            throws UnsupportedMessageException

Returns the receiver value as Java long primitive if the number fits without loss of precision. Invoking this message does not cause any observable side-effects.

Throws:

UnsupportedMessageException - if and only if the receiver is not a isNumber(Object) or it does not fit without loss of precision.

Since:

19.0

See Also:

• isNumber(Object)
• fitsInLong(Object)

asBigInteger

public BigInteger asBigInteger(Object receiver)
                        throws UnsupportedMessageException

Returns the receiver value as Java BigInteger if the number fits without loss of precision. Invoking this message does not cause any observable side-effects.

Throws:

UnsupportedMessageException - if and only if the receiver is not a isNumber(Object) or it does not fit without loss of precision.

Since:

23.0

See Also:

• isNumber(Object)
• fitsInBigInteger(Object)

asFloat

public float asFloat(Object receiver)
              throws UnsupportedMessageException

Returns the receiver value as Java float primitive if the number fits without loss of precision. Invoking this message does not cause any observable side-effects.

Throws:

UnsupportedMessageException - if and only if the receiver is not a isNumber(Object) or it does not fit without loss of precision.

Since:

19.0

See Also:

• isNumber(Object)
• fitsInFloat(Object)

asDouble

public double asDouble(Object receiver)
                throws UnsupportedMessageException

Returns the receiver value as Java double primitive if the number fits without loss of precision. Invoking this message does not cause any observable side-effects.

Throws:

UnsupportedMessageException - if and only if the receiver is not a isNumber(Object) or it does not fit without loss of precision.

Since:

19.0

See Also:

• isNumber(Object)
• fitsInDouble(Object)

hasMembers

public boolean hasMembers(Object receiver)

Returns true if the receiver may have members. Therefore, at least one of readMember(Object, String), writeMember(Object, String, Object), removeMember(Object, String), invokeMember(Object, String, Object...) must not throw UnsupportedMessageException. Members are structural elements of a class. For example, a method or field is a member of a class. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• getMembers(Object, boolean)
• isMemberReadable(Object, String)
• isMemberModifiable(Object, String)
• isMemberInvocable(Object, String)
• isMemberInsertable(Object, String)
• isMemberRemovable(Object, String)
• readMember(Object, String)
• writeMember(Object, String, Object)
• removeMember(Object, String)
• invokeMember(Object, String, Object...)

getMembers

public Object getMembers(Object receiver,
 boolean includeInternal)
                  throws UnsupportedMessageException

Returns an array of member name strings. The returned value must return true for hasArrayElements(Object) and every array element must be of type string. The member elements may also provide additional information like source location in case of scope variables, etc.

The order of member names needs to be:

• deterministic, assuming the program execution is deterministic,
• in the declaration order, when applicable,
• multiple invocations of this method must return the same members in the same order as long as no side-effecting operations were performed.

If the includeInternal argument is true then internal member names are returned as well. Internal members are implementation specific and should not be exposed to guest language application. An example of internal members are internal slots in ECMAScript.

Throws:

UnsupportedMessageException - if and only if the receiver does not have any members.

Since:

19.0

See Also:

• hasMembers(Object)

getMembers

public final Object getMembers(Object receiver)
                        throws UnsupportedMessageException

Short-cut for getMembers(receiver, false). Invoking this message does not cause any observable side-effects.

Throws:

UnsupportedMessageException - if and only if the receiver has no members.

Since:

19.0

See Also:

• getMembers(Object, boolean)

isMemberReadable

public boolean isMemberReadable(Object receiver,
 String member)

Returns true if a given member is readable. This method may only return true if hasMembers(Object) returns true as well and isMemberInsertable(Object, String) returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• readMember(Object, String)

readMember

public Object readMember(Object receiver,
 String member)
                  throws UnsupportedMessageException,
UnknownIdentifierException

Reads the value of a given member.

In case of a method-like member, we recommend that languages return a bound method (or an artificial receiver-method binding) to improve cross-language portability. In this case, the member should be readable and invocable and the result of reading the member should be executable and bound to the receiver.

This message must have not observable side-effects unless hasMemberReadSideEffects(Object, String) returns true.

Throws:

UnsupportedMessageException - if when the receiver does not support reading at all. An empty receiver with no readable members supports the read operation (even though there is nothing to read), therefore it throws UnknownIdentifierException for all arguments instead.

UnknownIdentifierException - if the given member cannot be read, e.g. because it is not (or no longer) readable such as when the member with the given name does not exist or has been removed.

Since:

19.0

See Also:

• hasMemberReadSideEffects(Object, String)

isMemberModifiable

public boolean isMemberModifiable(Object receiver,
 String member)

Returns true if a given member is existing and writable. This method may only return true if hasMembers(Object) returns true as well and isMemberInsertable(Object, String) returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• writeMember(Object, String, Object)

isMemberInsertable

public boolean isMemberInsertable(Object receiver,
 String member)

Returns true if a given member is not existing and writable. This method may only return true if hasMembers(Object) returns true as well and isMemberExisting(Object, String) returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• writeMember(Object, String, Object)

writeMember

public void writeMember(Object receiver,
 String member,
 Object value)
                 throws UnsupportedMessageException,
UnknownIdentifierException,
UnsupportedTypeException

Writes the value of a given member. Writing a member is allowed if is existing and modifiable, or not existing and insertable. This method must have no observable side-effects other than the changed member unless side-effects are allowed.

Throws:

UnsupportedMessageException - when the receiver does not support writing at all, e.g. when it is immutable.

UnknownIdentifierException - if the given member is not modifiable nor insertable.

UnsupportedTypeException - if the provided value type is not allowed to be written.

Since:

19.0

See Also:

• hasMemberWriteSideEffects(Object, String)

isMemberRemovable

public boolean isMemberRemovable(Object receiver,
 String member)

Returns true if a given member is existing and removable. This method may only return true if hasMembers(Object) returns true as well and isMemberInsertable(Object, String) returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• removeMember(Object, String)

removeMember

public void removeMember(Object receiver,
 String member)
                  throws UnsupportedMessageException,
UnknownIdentifierException

Removes a member from the receiver object. Removing member is allowed if is removable. This method does not have not observable side-effects other than the removed member.

Throws:

UnsupportedMessageException - when the receiver does not support removing at all, e.g. when it is immutable.

UnknownIdentifierException - if the given member is not isMemberRemovable(Object, String) removable}, e.g. the receiver does not have a member with the given name.

Since:

19.0

See Also:

• isMemberRemovable(Object, String)

isMemberInvocable

public boolean isMemberInvocable(Object receiver,
 String member)

Returns true if a given member is invocable. This method may only return true if hasMembers(Object) returns true as well and isMemberInsertable(Object, String) returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• invokeMember(Object, String, Object...)

invokeMember

public Object invokeMember(Object receiver,
 String member,
 Object... arguments)
                    throws UnsupportedMessageException,
ArityException,
UnknownIdentifierException,
UnsupportedTypeException

Invokes a member for a given receiver and arguments.

Throws:

UnknownIdentifierException - if the given member does not exist or is not invocable.

UnsupportedTypeException - if one of the arguments is not compatible to the executable signature. The exception is thrown on best effort basis, dynamic languages may throw their own exceptions if the arguments are wrong.

ArityException - if the number of expected arguments does not match the number of actual arguments.

UnsupportedMessageException - when the receiver does not support invoking at all, e.g. when storing executable members is not allowed.

Since:

19.0

See Also:

• isMemberInvocable(Object, String)

isMemberInternal

public boolean isMemberInternal(Object receiver,
 String member)

Returns true if a member is internal. Internal members are not enumerated by getMembers(Object, boolean) by default. Internal members are only relevant to guest language implementations and tools, but not to guest applications or embedders. An example of internal members are internal slots in ECMAScript. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• getMembers(Object, boolean)

isMemberWritable

public final boolean isMemberWritable(Object receiver,
 String member)

Returns true if the member is modifiable or insertable.

Since:

19.0

isMemberExisting

public final boolean isMemberExisting(Object receiver,
 String member)

Returns true if the member is existing. A member is existing if it is modifiable, readable, removable or invocable.

Since:

19.0

hasMemberReadSideEffects

public boolean hasMemberReadSideEffects(Object receiver,
 String member)

Returns true if reading a member may cause a side-effect. Invoking this message does not cause any observable side-effects. A member read does not cause any side-effects by default.

For instance in JavaScript a property read may have side-effects if the property has a getter function.

Since:

19.0

See Also:

• readMember(Object, String)

hasMemberWriteSideEffects

public boolean hasMemberWriteSideEffects(Object receiver,
 String member)

Returns true if writing a member may cause a side-effect, besides the write operation of the member. Invoking this message does not cause any observable side-effects. A member write does not cause any side-effects by default.

For instance in JavaScript a property write may have side-effects if the property has a setter function.

Since:

19.0

See Also:

• writeMember(Object, String, Object)

hasHashEntries

public boolean hasHashEntries(Object receiver)

Returns true if the receiver may have hash entries. Therefore, at least one of readHashValue(Object, Object), writeHashEntry(Object, Object, Object), removeHashEntry(Object, Object) must not throw UnsupportedMessageException. For example, the contents of a map data structure could be interpreted as hash elements. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

21.1

See Also:

• getHashEntriesIterator(Object)
• getHashSize(Object)
• isHashEntryReadable(Object, Object)
• isHashEntryWritable(Object, Object)
• isHashEntryInsertable(Object, Object)
• isHashEntryRemovable(Object, Object)
• readHashValue(Object, Object)
• readHashValueOrDefault(Object, Object, Object)
• writeHashEntry(Object, Object, Object)
• removeHashEntry(Object, Object)

getHashSize

public long getHashSize(Object receiver)
                 throws UnsupportedMessageException

Returns the number of receiver entries.

Throws:

UnsupportedMessageException - if and only if hasHashEntries(Object) returns false.

Since:

21.1

isHashEntryReadable

public boolean isHashEntryReadable(Object receiver,
 Object key)

Returns true if mapping for the specified key exists and is readable. This method may only return true if hasHashEntries(Object) returns true as well and isHashEntryInsertable(Object, Object) returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

21.1

See Also:

• readHashValue(Object, Object)

readHashValue

public Object readHashValue(Object receiver,
 Object key)
                     throws UnsupportedMessageException,
UnknownKeyException

Reads the value for the specified key.

Throws:

UnsupportedMessageException - if the receiver does not support reading at all. An empty receiver with no readable hash entries supports the read operation (even though there is nothing to read), therefore it throws UnknownKeyException for all arguments instead.

UnknownKeyException - if mapping for the specified key is not readable, e.g. when the hash does not contain specified key.

Since:

21.1

See Also:

• isHashEntryReadable(Object, Object)
• readHashValueOrDefault(Object, Object, Object)

readHashValueOrDefault

public Object readHashValueOrDefault(Object receiver,
 Object key,
 Object defaultValue)
                              throws UnsupportedMessageException

Reads the value for the specified key or returns the defaultValue when the mapping for the specified key does not exist or is not readable.

Throws:

UnsupportedMessageException - if the receiver does not support reading at all. An empty receiver with no readable hash entries supports the read operation (even though there is nothing to read), therefore it returns the defaultValue for all arguments instead.

Since:

21.1

See Also:

• isHashEntryReadable(Object, Object)
• readHashValue(Object, Object)

isHashEntryModifiable

public boolean isHashEntryModifiable(Object receiver,
 Object key)

Returns true if mapping for the specified key exists and is writable. This method may only return true if hasHashEntries(Object) returns true as well and isHashEntryInsertable(Object, Object) returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

21.1

See Also:

• writeHashEntry(Object, Object, Object)

isHashEntryInsertable

public boolean isHashEntryInsertable(Object receiver,
 Object key)

Returns true if mapping for the specified key does not exist and is writable. This method may only return true if hasHashEntries(Object) returns true as well and isHashEntryExisting(Object, Object) returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

21.1

See Also:

• writeHashEntry(Object, Object, Object)

isHashEntryWritable

public boolean isHashEntryWritable(Object receiver,
 Object key)

Returns true if mapping for the specified key is modifiable or insertable.

Since:

21.1

writeHashEntry

public void writeHashEntry(Object receiver,
 Object key,
 Object value)
                    throws UnsupportedMessageException,
UnknownKeyException,
UnsupportedTypeException

Associates the specified value with the specified key in the receiver. Writing the entry is allowed if is existing and modifiable, or not existing and insertable.

Throws:

UnsupportedMessageException - when the receiver does not support writing at all, e.g. when it is immutable.

UnknownKeyException - if mapping for the specified key is not modifiable nor insertable.

UnsupportedTypeException - if the provided key type or value type is not allowed to be written.

Since:

21.1

isHashEntryRemovable

public boolean isHashEntryRemovable(Object receiver,
 Object key)

Returns true if mapping for the specified key exists and is removable. This method may only return true if hasHashEntries(Object) returns true as well and isHashEntryInsertable(Object, Object) returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

21.1

See Also:

• removeHashEntry(Object, Object)

removeHashEntry

public void removeHashEntry(Object receiver,
 Object key)
                     throws UnsupportedMessageException,
UnknownKeyException

Removes the mapping for a given key from the receiver. Mapping removing is allowed if it is removable.

Throws:

UnsupportedMessageException - when the receiver does not support removing at all, e.g. when it is immutable.

UnknownKeyException - if the given mapping is not removable, e.g. the receiver does not have a mapping for given key.

Since:

21.1

See Also:

• isHashEntryRemovable(Object, Object)

isHashEntryExisting

public boolean isHashEntryExisting(Object receiver,
 Object key)

Returns true if mapping for a given key is existing. The mapping is existing if it is modifiable, readable or removable.

Since:

21.1

getHashEntriesIterator

public Object getHashEntriesIterator(Object receiver)
                              throws UnsupportedMessageException

Returns the hash entries iterator for the receiver. The return value is always an iterator of array elements. The first array element is a key, the second array element is an associated value. Array returned by the iterator may be modifiable but detached from the hash, updating the array elements may not update the hash. So even if array elements are modifiable always use writeHashEntry(Object, Object, Object) to update the hash mapping.

Throws:

UnsupportedMessageException - if and only if hasHashEntries(Object) returns false for the same receiver.

Since:

21.1

getHashKeysIterator

public Object getHashKeysIterator(Object receiver)
                           throws UnsupportedMessageException

Returns the hash keys iterator for the receiver. The return value is always an iterator.

Throws:

UnsupportedMessageException - if and only if hasHashEntries(Object) returns false for the same receiver.

Since:

21.1

getHashValuesIterator

public Object getHashValuesIterator(Object receiver)
                             throws UnsupportedMessageException

Returns the hash values iterator for the receiver. The return value is always an iterator.

Throws:

UnsupportedMessageException - if and only if hasHashEntries(Object) returns false for the same receiver.

Since:

21.1

hasArrayElements

public boolean hasArrayElements(Object receiver)

Returns true if the receiver may have array elements. Therefore, At least one of readArrayElement(Object, long), writeArrayElement(Object, long, Object), removeArrayElement(Object, long) must not throw {#link UnsupportedMessageException. For example, the contents of an array or list datastructure could be interpreted as array elements. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• getArraySize(Object)

readArrayElement

public Object readArrayElement(Object receiver,
 long index)
                        throws UnsupportedMessageException,
InvalidArrayIndexException

Reads the value of an array element by index. This method must have not observable side-effect.

Throws:

UnsupportedMessageException - when the receiver does not support reading at all. An empty receiver with no readable array elements supports the read operation (even though there is nothing to read), therefore it throws UnknownIdentifierException for all arguments instead.

InvalidArrayIndexException - if the given index is not readable, e.g. when the index is invalid or the index is out of bounds.

Since:

19.0

getArraySize

public long getArraySize(Object receiver)
                  throws UnsupportedMessageException

Returns the array size of the receiver.

Throws:

UnsupportedMessageException - if and only if hasArrayElements(Object) returns false.

Since:

19.0

isArrayElementReadable

public boolean isArrayElementReadable(Object receiver,
 long index)

Returns true if a given array element is readable. This method may only return true if hasArrayElements(Object) returns true as well. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• readArrayElement(Object, long)

writeArrayElement

public void writeArrayElement(Object receiver,
 long index,
 Object value)
                       throws UnsupportedMessageException,
UnsupportedTypeException,
InvalidArrayIndexException

Writes the value of an array element by index. Writing an array element is allowed if is existing and modifiable, or not existing and insertable. This method must have not observable side-effects other than the changed array element.

Throws:

UnsupportedMessageException - when the receiver does not support writing at all, e.g. when it is immutable.

InvalidArrayIndexException - if the given index is not insertable nor modifiable, e.g. when the index is invalid or the index is out of bounds and the array does not support growing.

UnsupportedTypeException - if the provided value type is not allowed to be written.

Since:

19.0

removeArrayElement

public void removeArrayElement(Object receiver,
 long index)
                        throws UnsupportedMessageException,
InvalidArrayIndexException

Remove an array element from the receiver object. Removing member is allowed if the array element is removable. This method may only return true if hasArrayElements(Object) returns true as well and isArrayElementInsertable(Object, long) returns false. This method does not have observable side-effects other than the removed array element and shift of remaining elements. If shifting is not supported then the array might allow only removal of last element.

Throws:

UnsupportedMessageException - when the receiver does not support removing at all, e.g. when it is immutable.

InvalidArrayIndexException - if the given index is not removable, e.g. when the index is invalid, the index is out of bounds, or the array does not support shifting of remaining elements.

Since:

19.0

See Also:

• isArrayElementRemovable(Object, long)

isArrayElementModifiable

public boolean isArrayElementModifiable(Object receiver,
 long index)

Returns true if a given array element index is existing and writable. This method may only return true if hasArrayElements(Object) returns true as well and isArrayElementInsertable(Object, long) returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• writeArrayElement(Object, long, Object)
• isArrayElementInsertable(Object, long)

isArrayElementInsertable

public boolean isArrayElementInsertable(Object receiver,
 long index)

Returns true if a given array element index is not existing and insertable. This method may only return true if hasArrayElements(Object) returns true as well and isArrayElementExisting(Object, long)} returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• writeArrayElement(Object, long, Object)
• isArrayElementModifiable(Object, long)

isArrayElementRemovable

public boolean isArrayElementRemovable(Object receiver,
 long index)

Returns true if a given array element index is existing and removable. This method may only return true if hasArrayElements(Object) returns true as well and isArrayElementInsertable(Object, long)} returns false. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

19.0

See Also:

• removeArrayElement(Object, long)

isArrayElementWritable

public final boolean isArrayElementWritable(Object receiver,
 long index)

Returns true if the array element is modifiable or insertable.

Since:

19.0

isArrayElementExisting

public final boolean isArrayElementExisting(Object receiver,
 long index)

Returns true if the array element is existing. An array element is existing if it is, modifiable, readable or removable.

Since:

19.0

hasBufferElements

public boolean hasBufferElements(Object receiver)

Returns true if the receiver may have buffer elements.

If this message returns true, then getBufferSize(Object), readBufferByte(Object, long), readBufferShort(Object, ByteOrder, long), readBufferInt(Object, ByteOrder, long), readBufferLong(Object, ByteOrder, long), readBufferFloat(Object, ByteOrder, long) and readBufferDouble(Object, ByteOrder, long) must not throw UnsupportedMessageException.

Invoking this message does not cause any observable side-effects.

By default, it returns false.

Since:

21.1

isBufferWritable

public boolean isBufferWritable(Object receiver)
                         throws UnsupportedMessageException

Returns true if the receiver is a modifiable buffer.

If this message returns true, then getBufferSize(Object), writeBufferByte(Object, long, byte), writeBufferShort(Object, ByteOrder, long, short), writeBufferInt(Object, ByteOrder, long, int), writeBufferLong(Object, ByteOrder, long, long), writeBufferFloat(Object, ByteOrder, long, float) and writeBufferDouble(Object, ByteOrder, long, double) must not throw UnsupportedMessageException.

Invoking this message does not cause any observable side-effects.

By default, it returns false if hasBufferElements(Object) return true, and throws UnsupportedMessageException otherwise.

Throws:

UnsupportedMessageException - if and only if hasBufferElements(Object) returns false

Since:

21.1

getBufferSize

public long getBufferSize(Object receiver)
                   throws UnsupportedMessageException

Returns the buffer size of the receiver, in bytes.

Invoking this message does not cause any observable side-effects.

Throws:

UnsupportedMessageException - if and only if hasBufferElements(Object) returns false

Since:

21.1

readBufferByte

public byte readBufferByte(Object receiver,
 long byteOffset)
                    throws UnsupportedMessageException,
InvalidBufferOffsetException

Reads the byte from the receiver object at the given byte offset from the start of the buffer.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Invoking this message does not cause any observable side-effects.

Returns:

the byte at the given index

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object)

UnsupportedMessageException - if and only if hasBufferElements(Object) returns false

Since:

21.1

readBuffer

public void readBuffer(Object receiver,
 long byteOffset,
 byte[] destination,
 int destinationOffset,
 int length)
                throws UnsupportedMessageException,
InvalidBufferOffsetException

Reads bytes from the receiver object into the specified byte array.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Invoking this message does not cause any observable side-effects.

Parameters:

byteOffset - offset in the buffer to start reading from.

destination - byte array to write the read bytes into.

destinationOffset - offset in the destination array to start writing from.

length - number of bytes to read.

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || length < 0 || byteOffset + length > getBufferSize(Object)

UnsupportedMessageException - if and only if hasBufferElements(Object) returns false

Since:

24.0

writeBufferByte

public void writeBufferByte(Object receiver,
 long byteOffset,
 byte value)
                     throws UnsupportedMessageException,
InvalidBufferOffsetException

Writes the given byte from the receiver object at the given byte offset from the start of the buffer.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object)

UnsupportedMessageException - if and only if either hasBufferElements(Object) or isBufferWritable(java.lang.Object) returns false

Since:

21.1

readBufferShort

public short readBufferShort(Object receiver,
 ByteOrder order,
 long byteOffset)
                      throws UnsupportedMessageException,
InvalidBufferOffsetException

Reads the short from the receiver object in the given byte order at the given byte offset from the start of the buffer.

Unaligned accesses are supported.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Invoking this message does not cause any observable side-effects.

Returns:

the short at the given byte offset from the start of the buffer

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object) - 1

UnsupportedMessageException - if and only if hasBufferElements(Object) returns false

Since:

21.1

writeBufferShort

public void writeBufferShort(Object receiver,
 ByteOrder order,
 long byteOffset,
 short value)
                      throws UnsupportedMessageException,
InvalidBufferOffsetException

Writes the given short from the receiver object in the given byte order at the given byte offset from the start of the buffer.

Unaligned accesses are supported.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object) - 1

UnsupportedMessageException - if and only if either hasBufferElements(Object) or isBufferWritable(java.lang.Object) returns false

Since:

21.1

readBufferInt

public int readBufferInt(Object receiver,
 ByteOrder order,
 long byteOffset)
                  throws UnsupportedMessageException,
InvalidBufferOffsetException

Reads the int from the receiver object in the given byte order at the given byte offset from the start of the buffer.

Unaligned accesses are supported.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Invoking this message does not cause any observable side-effects.

Returns:

the int at the given byte offset from the start of the buffer

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object) - 3

UnsupportedMessageException - if and only if hasBufferElements(Object) returns false

Since:

21.1

writeBufferInt

public void writeBufferInt(Object receiver,
 ByteOrder order,
 long byteOffset,
 int value)
                    throws UnsupportedMessageException,
InvalidBufferOffsetException

Writes the given int from the receiver object in the given byte order at the given byte offset from the start of the buffer.

Unaligned accesses are supported.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object) - 3

UnsupportedMessageException - if and only if either hasBufferElements(Object) or isBufferWritable(java.lang.Object) returns false

Since:

21.1

readBufferLong

public long readBufferLong(Object receiver,
 ByteOrder order,
 long byteOffset)
                    throws UnsupportedMessageException,
InvalidBufferOffsetException

Reads the long from the receiver object in the given byte order at the given byte offset from the start of the buffer.

Unaligned accesses are supported.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Invoking this message does not cause any observable side-effects.

Returns:

the int at the given byte offset from the start of the buffer

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object) - 7

UnsupportedMessageException - if and only if hasBufferElements(Object) returns false

Since:

21.1

writeBufferLong

public void writeBufferLong(Object receiver,
 ByteOrder order,
 long byteOffset,
 long value)
                     throws UnsupportedMessageException,
InvalidBufferOffsetException

Writes the given long from the receiver object in the given byte order at the given byte offset from the start of the buffer.

Unaligned accesses are supported.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object) - 7

UnsupportedMessageException - if and only if either hasBufferElements(Object) or isBufferWritable(java.lang.Object) returns false

Since:

21.1

readBufferFloat

public float readBufferFloat(Object receiver,
 ByteOrder order,
 long byteOffset)
                      throws UnsupportedMessageException,
InvalidBufferOffsetException

Reads the float from the receiver object in the given byte order at the given byte offset from the start of the buffer.

Unaligned accesses are supported.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Invoking this message does not cause any observable side-effects.

Returns:

the float at the given byte offset from the start of the buffer

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object) - 3

UnsupportedMessageException - if and only if hasBufferElements(Object) returns false

Since:

21.1

writeBufferFloat

public void writeBufferFloat(Object receiver,
 ByteOrder order,
 long byteOffset,
 float value)
                      throws UnsupportedMessageException,
InvalidBufferOffsetException

Writes the given float from the receiver object in the given byte order at the given byte offset from the start of the buffer.

Unaligned accesses are supported.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object) - 3

UnsupportedMessageException - if and only if either hasBufferElements(Object) or isBufferWritable(java.lang.Object) returns false

Since:

21.1

readBufferDouble

public double readBufferDouble(Object receiver,
 ByteOrder order,
 long byteOffset)
                        throws UnsupportedMessageException,
InvalidBufferOffsetException

Reads the double from the receiver object in the given byte order at the given byte offset from the start of the buffer.

Unaligned accesses are supported.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Invoking this message does not cause any observable side-effects.

Returns:

the double at the given byte offset from the start of the buffer

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object) - 7

UnsupportedMessageException - if and only if hasBufferElements(Object) returns false

Since:

21.1

writeBufferDouble

public void writeBufferDouble(Object receiver,
 ByteOrder order,
 long byteOffset,
 double value)
                       throws UnsupportedMessageException,
InvalidBufferOffsetException

Writes the given double from the receiver object in the given byte order at the given byte offset from the start of the buffer.

Unaligned accesses are supported.

The access is not guaranteed to be atomic. Therefore, this message is not thread-safe.

Throws:

InvalidBufferOffsetException - if and only if byteOffset < 0 || byteOffset >= getBufferSize(Object) - 7

UnsupportedMessageException - if and only if either hasBufferElements(Object) or isBufferWritable(java.lang.Object) returns false

Since:

21.1

isPointer

public boolean isPointer(Object receiver)

Returns true if the receiver value represents a native pointer. Native pointers are represented as 64 bit pointers. Invoking this message does not cause any observable side-effects. Returns false by default.

It is expected that objects should only return true if the native pointer value corresponding to this object already exists, and obtaining it is a cheap operation. If an object can be transformed to a pointer representation, but this hasn't happened yet, the object is expected to return false with isPointer(Object), and wait for the toNative(Object) message to trigger the transformation.

Since:

19.0

See Also:

• asPointer(Object)
• toNative(Object)

asPointer

public long asPointer(Object receiver)
               throws UnsupportedMessageException

Returns the pointer value as long value if the receiver represents a pointer like value.

Throws:

UnsupportedMessageException - if and only if isPointer(Object) returns false for the same receiver.

Since:

19.0

See Also:

• isPointer(Object)

toNative

public void toNative(Object receiver)

Attempts to transform a receiver to a value that represents a raw native pointer. After a successful transformation, the provided receiver returns true for isPointer(Object) and can be unwrapped using the asPointer(Object) message. If transformation cannot be done isPointer(Object) will keep returning false.

Since:

19.0

See Also:

• isPointer(Object)
• asPointer(Object)

asInstant

public Instant asInstant(Object receiver)
                  throws UnsupportedMessageException

Returns the receiver as instant if this object represents an instant. If a value is an instant then it is also a date, time and timezone. Using this method may be more efficient than reconstructing the timestamp from the date, time and timezone data.

Implementers should implement this method if they can provide a more efficient conversion to Instant than reconstructing it from date, time and timezone date. Implementers must ensure that the following Java code snippet always holds:

 ZoneId zone = getTimeZone(receiver);
 LocalDate date = getDate(receiver);
 LocalTime time = getTime(receiver);
 assert ZonedDateTime.of(date, time, zone).toInstant().equals(getInstant(receiver));
 

Throws:

UnsupportedMessageException - if and only if isInstant(Object) returns false.

Since:

20.0.0 beta 2

See Also:

• isDate(Object)
• isTime(Object)
• isTimeZone(Object)

isInstant

public final boolean isInstant(Object receiver)

Returns true if the receiver represents an instant. If a value is an instant then it is also a date, time and timezone. This method is short-hand for:

 isDate(v) && isTime(v) && isTimeZone(v)
 

Since:

20.0.0 beta 2

See Also:

• isDate(Object)
• isTime(Object)
• isInstant(Object)
• asInstant(Object)

isTimeZone

public boolean isTimeZone(Object receiver)

Returns true if this object represents a timezone, else false. The interpretation of timezone objects may vary:

• If isDate(Object) and isTime(Object) return true, then the returned date or time information is aware of this timezone.
• If isDate(Object) and isTime(Object) returns false, then it represents just timezone information.

Objects with only date information must not have timezone information attached and objects with only time information must have either none, or fixed zone only. If this rule is violated then an AssertionError is thrown if assertions are enabled.

If this method is implemented then also asTimeZone(Object) must be implemented.

Since:

20.0.0 beta 2

See Also:

• asTimeZone(Object)
• asInstant(Object)

asTimeZone

public ZoneId asTimeZone(Object receiver)
                  throws UnsupportedMessageException

Returns the receiver as timestamp if this object represents a timezone.

Throws:

UnsupportedMessageException - if and only if isTimeZone(Object) returns false .

Since:

20.0.0 beta 2

See Also:

• isTimeZone(Object)

isDate

public boolean isDate(Object receiver)

Returns true if this object represents a date, else false. If the receiver is also a timezone then the date is aware, otherwise it is naive.

Since:

20.0.0 beta 2

See Also:

• asDate(Object)

asDate

public LocalDate asDate(Object receiver)
                 throws UnsupportedMessageException

Returns the receiver as date if this object represents a date. The returned date is either aware if the receiver has a timezone otherwise it is naive.

Throws:

UnsupportedMessageException - if and only if isDate(Object) returns false.

Since:

20.0.0 beta 2

See Also:

• isDate(Object)

isTime

public boolean isTime(Object receiver)

Returns true if this object represents a time, else false. If the receiver is also a timezone then the time is aware, otherwise it is naive.

Since:

20.0.0 beta 2

See Also:

• asTime(Object)

asTime

public LocalTime asTime(Object receiver)
                 throws UnsupportedMessageException

Returns the receiver as time if this object represents a time. The returned time is either aware if the receiver has a timezone otherwise it is naive.

Throws:

UnsupportedMessageException - if and only if isTime(Object) returns false.

Since:

20.0.0 beta 2

See Also:

• isTime(Object)

isDuration

public boolean isDuration(Object receiver)

Returns true if this object represents a duration, else false.

Since:

20.0.0 beta 2

See Also:

• Duration
• asDuration(Object)

asDuration

public Duration asDuration(Object receiver)
                    throws UnsupportedMessageException

Returns the receiver as duration if this object represents a duration.

Throws:

UnsupportedMessageException - if and only if isDuration(Object) returns false .

Since:

20.0.0 beta 2

See Also:

• isDuration(Object)

isException

public boolean isException(Object receiver)

Returns true if the receiver value represents a throwable exception/error}. Invoking this message does not cause any observable side-effects. Returns false by default.

Objects must only return true if they support throwException(java.lang.Object) as well. If this method is implemented then also throwException(Object) must be implemented. The following simplified TryCatchNode shows how the exceptions should be handled by languages.

static final class TryCatchNode extends StatementNode {

    @Node.Child private BlockNode block;
    @Node.Child private BlockNode catchBlock;
    @Node.Child private BlockNode finallyBlock;
    private final BranchProfile exceptionProfile;

    TryCatchNode(BlockNode block, BlockNode catchBlock,
                    BlockNode finallyBlock) {
        this.block = block;
        this.catchBlock = catchBlock;
        this.finallyBlock = finallyBlock;
        this.exceptionProfile = BranchProfile.create();
    }

    @Override
    void executeVoid(VirtualFrame frame) {
        RuntimeException rethrowException = null;
        try {
            block.executeVoid(frame);
        } catch (AbstractTruffleException ex) {
            exceptionProfile.enter();
            try {
                if (catchBlock != null) {
                    catchBlock.executeVoid(frame);
                    // do not rethrow if handled
                    rethrowException = null;
                } else {
                    // rethrow if not handled
                    rethrowException = ex;
                }
            } catch (AbstractTruffleException e) {
                rethrowException = e;
            }
        } catch (ControlFlowException cfe) {
            // run finally blocks for control flow
            rethrowException = cfe;
        }
        // Java finally blocks that execute nodes are not allowed for
        // compilation as code in finally blocks is duplicated
        // by the Java bytecode compiler. This can lead to
        // exponential code growth in worst cases.
        if (finallyBlock != null) {
            finallyBlock.executeVoid(frame);
        }
        if (rethrowException != null) {
            throw rethrowException;
        }
    }
}

Since:

19.3

See Also:

• throwException(Object)
• AbstractTruffleException

throwException

public RuntimeException throwException(Object receiver)
                                throws UnsupportedMessageException

Throws the receiver object as an exception of the source language, as if it was thrown by the source language itself. Allows rethrowing exceptions caught by another language. If this method is implemented then also isException(Object) must be implemented.

Any interop value can be an exception value and export throwException(Object). The exception thrown by this message must extend AbstractTruffleException. In future versions this contract will be enforced using an assertion.

For a sample TryCatchNode implementation see isException.

Throws:

UnsupportedMessageException - if and only if isException(Object) returns false for the same receiver.

Since:

19.3

See Also:

• isException(Object)

getExceptionType

public ExceptionType getExceptionType(Object receiver)
                               throws UnsupportedMessageException

Returns exception type of the receiver. Throws UnsupportedMessageException when the receiver is not an exception.

For a sample TryCatchNode implementation see isException.

Throws:

UnsupportedMessageException

Since:

20.3

See Also:

• isException(Object)
• ExceptionType

isExceptionIncompleteSource

public boolean isExceptionIncompleteSource(Object receiver)
                                    throws UnsupportedMessageException

Returns true if receiver value represents an incomplete source exception. Throws UnsupportedMessageException when the receiver is not an exception or the exception is not a ExceptionType.PARSE_ERROR.

Throws:

UnsupportedMessageException

Since:

20.3

See Also:

• isException(Object)
• getExceptionType(Object)

getExceptionExitStatus

public int getExceptionExitStatus(Object receiver)
                           throws UnsupportedMessageException

Returns exception exit status of the receiver. Throws UnsupportedMessageException when the receiver is not an exception of the exit type. See Context Exit for further information. A return value zero indicates that the execution of the application was successful, a non-zero value that it failed. The individual interpretation of non-zero values depends on the application.

Throws:

UnsupportedMessageException

Since:

20.3

See Also:

• isException(Object)
• getExceptionType(Object)
• ExceptionType

hasExceptionCause

public boolean hasExceptionCause(Object receiver)

Returns true if the receiver is an exception with an attached internal cause. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

20.3

See Also:

• isException(Object)
• getExceptionCause(Object)

getExceptionCause

public Object getExceptionCause(Object receiver)
                         throws UnsupportedMessageException

Returns the internal cause of the receiver. Throws UnsupportedMessageException when the receiver is not an exception or has no internal cause. The return value of this message is guaranteed to return true for isException(Object).

Throws:

UnsupportedMessageException

Since:

20.3

See Also:

• isException(Object)
• hasExceptionCause(Object)

hasExceptionMessage

public boolean hasExceptionMessage(Object receiver)

Returns true if the receiver is an exception that has an exception message. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

20.3

See Also:

• isException(Object)
• getExceptionMessage(Object)

getExceptionMessage

public Object getExceptionMessage(Object receiver)
                           throws UnsupportedMessageException

Returns exception message of the receiver. Throws UnsupportedMessageException when the receiver is not an exception or has no exception message. The return value of this message is guaranteed to return true for isString(Object).

Throws:

UnsupportedMessageException

Since:

20.3

See Also:

• isException(Object)
• hasExceptionMessage(Object)

hasExceptionStackTrace

public boolean hasExceptionStackTrace(Object receiver)

Returns true if the receiver is an exception and has a stack trace. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

20.3

See Also:

• isException(Object)
• getExceptionStackTrace(Object)

getExceptionStackTrace

public Object getExceptionStackTrace(Object receiver)
                              throws UnsupportedMessageException

Returns the exception stack trace of the receiver that is of type exception. Returns an array of objects with potentially executable name, declaring meta object and source location of the caller. Throws UnsupportedMessageException when the receiver is not an exception or has no stack trace. Invoking this message or accessing the stack trace elements array must not cause any observable side-effects.

The default implementation of getExceptionStackTrace(Object) calls TruffleStackTrace.getStackTrace(Throwable) on the underlying exception object and TruffleStackTraceElement.getGuestObject() to access an interop capable object of the underlying stack trace element.

Throws:

UnsupportedMessageException

Since:

20.3

See Also:

• isException(Object)
• hasExceptionStackTrace(Object)

hasIterator

public boolean hasIterator(Object receiver)

Returns true if the receiver provides an iterator. For example, an array or a list provide an iterator over their content. Invoking this message does not cause any observable side-effects. By default returns true for receivers that have array elements.

Since:

21.1

See Also:

• getIterator(Object)

getIterator

public Object getIterator(Object receiver)
                   throws UnsupportedMessageException

Returns the iterator for the receiver. The return value is always an iterator. Invoking this message does not cause any observable side-effects.

Throws:

UnsupportedMessageException - if and only if hasIterator(Object) returns false for the same receiver.

Since:

21.1

isIterator

public boolean isIterator(Object receiver)

Returns true if the receiver represents an iterator. Invoking this message does not cause any observable side-effects. Returns false by default.

Since:

21.1

See Also:

• hasIterator(Object)
• getIterator(Object)

hasIteratorNextElement

public boolean hasIteratorNextElement(Object receiver)
                               throws UnsupportedMessageException

Returns true if the receiver is an iterator which has more elements, else false. Multiple calls to the hasIteratorNextElement(Object) might lead to different results if the underlying data structure is modified.

The following example shows how the hasIteratorNextElement message can be emulated in languages where iterators only have a next method and throw an exception if there are no further elements.

 @ExportLibrary(InteropLibrary.class)
 abstract class InteropIterator implements TruffleObject {

     @SuppressWarnings("serial")
     public static final class Stop extends AbstractTruffleException {
     }

     private static final Object STOP = new Object();
     private Object next;

     protected InteropIterator() {
     }

     protected abstract Object next() throws Stop;

     @ExportMessage
     @SuppressWarnings("static-method")
     boolean isIterator() {
         return true;
     }

     @ExportMessage
     boolean hasIteratorNextElement() {
         fetchNext();
         return next != STOP;
     }

     @ExportMessage
     Object getIteratorNextElement() throws StopIterationException {
         fetchNext();
         Object res = next;
         if (res == STOP) {
             throw StopIterationException.create();
         } else {
             next = null;
         }
         return res;
     }

     private void fetchNext() {
         if (next == null) {
             try {
                 next = next();
             } catch (Stop stop) {
                 next = STOP;
             }
         }
     }
 }
 

Throws:

UnsupportedMessageException - if and only if isIterator(Object) returns false for the same receiver.

Since:

21.1

See Also:

• isIterator(Object)
• getIteratorNextElement(Object)

getIteratorNextElement

public Object getIteratorNextElement(Object receiver)
                              throws UnsupportedMessageException,
StopIterationException

Returns the next element in the iteration. When the underlying data structure is modified the getIteratorNextElement(Object) may throw the StopIterationException despite the hasIteratorNextElement(Object) returned true.

Throws:

UnsupportedMessageException - if isIterator(Object) returns false for the same receiver or when the underlying iterator element exists but is not readable.

StopIterationException - if the iteration has no more elements. Even if the StopIterationException was thrown it might not be thrown again by a next getIteratorNextElement(Object) invocation on the same receiver due to a modification of an underlying iterable.

Since:

21.1

See Also:

• isIterator(Object)
• hasIteratorNextElement(Object)

hasSourceLocation

public boolean hasSourceLocation(Object receiver)

Returns true if the receiver value has a declared source location attached, else false. Returning a source location for a value is optional and typically impacts the capabilities of tools like debuggers to jump to the declaration of a value.

Examples for values that may provide a source location:

• Metaobjects like classes or types.
• First class executables, like functions, closures or promises.
• Allocation sites for instances. Note that in most languages it is very expensive to track the allocation site of an instance and it is therefore not recommended to support this feature by default, but ideally behind an optional language option.

  This method must not cause any observable side-effects. If this method is implemented then also getSourceLocation(Object) must be implemented.

Since:

20.1

See Also:

• getSourceLocation(Object)

getSourceLocation

public SourceSection getSourceLocation(Object receiver)
                                throws UnsupportedMessageException

Returns the declared source location of the receiver value. Throws an UnsupportedMessageException if the value does not have a declared source location. See hasSourceLocation(Object) for further details on potential interpretations. Throws UnsupportedMessageException by default.

This method must not cause any observable side-effects. If this method is implemented then also hasSourceLocation(Object) must be implemented.

Throws:

UnsupportedMessageException - if and only if hasSourceLocation(Object) returns false for the same receiver.

Since:

20.1

hasLanguage

public boolean hasLanguage(Object receiver)

Returns true if the receiver originates from a language, else false . Primitive values or other shared interop value representations that are not associated with a language may return false. Values that originate from a language should return true. Returns false by default.

The associated language allows tools to identify the original language of a value. If an instrument requests a language view then values that are already associated with a language will just return the same value. Otherwise TruffleLanguage.getLanguageView(Object, Object) will be invoked on the language. The returned language may be also exposed to embedders in the future.

This method must not cause any observable side-effects. If this method is implemented then also getLanguage(Object) and toDisplayString(Object, boolean) must be implemented.

Since:

20.1

See Also:

• getLanguage(Object)
• toDisplayString(Object)

getLanguage

public Class<? extends TruffleLanguage<?>> getLanguage(Object receiver)
                                                throws UnsupportedMessageException

Returns the the original language of the receiver value. The returned language class must be non-null and represent a valid registered language class. For more details see hasLanguage(Object).

This method must not cause any observable side-effects. If this method is implemented then also hasLanguage(Object) must be implemented.

Throws:

UnsupportedMessageException - if and only if hasLanguage(Object) returns false for the same receiver.

Since:

20.1

hasMetaObject

public boolean hasMetaObject(Object receiver)

Returns true if the receiver value has a metaobject associated. The metaobject represents a description of the object, reveals its kind and its features. Some information that a metaobject might define includes the base object's type, interface, class, methods, attributes, etc. Should return false when no metaobject is known for this type. Returns false by default.

An example, for Java objects the returned metaobject is the class instance. In JavaScript this could be the function or class that is associated with the object.

Metaobjects for primitive values or values of other languages may be provided using language views. While an object is associated with a metaobject in one language, the metaobject might be a different when viewed from another language.

This method must not cause any observable side-effects. If this method is implemented then also getMetaObject(Object) must be implemented.

Since:

20.1

See Also:

• getMetaObject(Object)
• isMetaObject(Object)

getMetaObject

public Object getMetaObject(Object receiver)
                     throws UnsupportedMessageException

Returns the metaobject that is associated with this value. The metaobject represents a description of the object, reveals its kind and its features. Some information that a metaobject might define includes the base object's type, interface, class, methods, attributes, etc. When no metaobject is known for this type. Throws UnsupportedMessageException by default.

The returned object must return true for isMetaObject(Object) and provide implementations for getMetaSimpleName(Object), getMetaQualifiedName(Object), and isMetaInstance(Object, Object). For all values with metaobjects it must at hold that isMetaInstance(getMetaObject(value), value) == true.

This method must not cause any observable side-effects. If this method is implemented then also hasMetaObject(Object) must be implemented.

Throws:

UnsupportedMessageException - if and only if hasMetaObject(Object) returns false for the same receiver.

Since:

20.1

See Also:

• hasMetaObject(Object)

toDisplayString

public Object toDisplayString(Object receiver,
 boolean allowSideEffects)

Converts the receiver to a human readable string. Each language may have special formating conventions - even primitive values may not follow the traditional Java rules. The format of the returned string is intended to be interpreted by humans not machines and should therefore not be relied upon by machines. By default the receiver class name and its identity hash code is used as string representation.

String representations for primitive values or values of other languages may be provided using language views. It is common that languages provide different string representations for primitive and foreign values. To convert the result value to a Java string use asString(Object).

Parameters:

allowSideEffects - whether side-effects are allowed in the production of the string.

Since:

20.1

See Also:

• TruffleLanguage.getLanguageView(Object, Object)

toDisplayString

public final Object toDisplayString(Object receiver)

Converts the receiver to a human readable string of the language. Short-cut for toDisplayString(Object, true).

Since:

20.1

See Also:

• toDisplayString(Object, boolean)

isMetaObject

public boolean isMetaObject(Object receiver)

Returns true if the receiver value represents a metaobject. Metaobjects may be values that naturally occur in a language or they may be returned by getMetaObject(Object). A metaobject represents a description of the object, reveals its kind and its features. If a receiver is a metaobject it is often also instantiable, but this is not a requirement.

Sample interpretations: In Java an instance of the type Class is a metaobject. In JavaScript any function instance is a metaobject. For example, the metaobject of a JavaScript class is the associated constructor function.

This method must not cause any observable side-effects. If this method is implemented then also getMetaQualifiedName(Object), getMetaSimpleName(Object) and isMetaInstance(Object, Object) must be implemented as well.

Since:

20.1

getMetaQualifiedName

public Object getMetaQualifiedName(Object metaObject)
                            throws UnsupportedMessageException

Returns the qualified name of a metaobject as string.

Sample interpretations: The qualified name of a Java class includes the package name and its class name. JavaScript does not have the notion of qualified name and therefore returns the simple name instead.

This method must not cause any observable side-effects. If this method is implemented then also isMetaObject(Object) must be implemented as well.

Throws:

UnsupportedMessageException - if and only if isMetaObject(Object) returns false for the same receiver.

Since:

20.1

getMetaSimpleName

public Object getMetaSimpleName(Object metaObject)
                         throws UnsupportedMessageException

Returns the simple name of a metaobject as string.

Sample interpretations: The simple name of a Java class is the class name.

This method must not cause any observable side-effects. If this method is implemented then also isMetaObject(Object) must be implemented as well.

Throws:

UnsupportedMessageException - if and only if isMetaObject(Object) returns false for the same receiver.

Since:

20.1

isMetaInstance

public boolean isMetaInstance(Object receiver,
 Object instance)
                       throws UnsupportedMessageException

Returns true if the given instance is of the provided receiver metaobject, else false.

Sample interpretations: A Java object is an instance of its returned class.

This method must not cause any observable side-effects. If this method is implemented then also isMetaObject(Object) must be implemented as well.

Parameters:

instance - the instance object to check.

Throws:

UnsupportedMessageException - if and only if isMetaObject(Object) returns false for the same receiver.

Since:

20.1

hasMetaParents

public boolean hasMetaParents(Object receiver)

Returns true if the receiver value is a metaobject which has parents (super types).

This method must not cause any observable side-effects. If this method is implemented then also getMetaParents(Object) must be implemented.

Parameters:

receiver - a metaobject

Since:

22.2

See Also:

• getMetaParents(Object)

getMetaParents

public Object getMetaParents(Object receiver)
                      throws UnsupportedMessageException

Returns an array like hasArrayElements(Object) of metaobjects that are direct parents (super types) of this metaobject.

The returned object is an array of objects that return true from isMetaObject(Object).

Parameters:

receiver - a metaobject

Throws:

UnsupportedMessageException - if and only if hasMetaParents(Object) returns false for the same receiver.

Since:

22.2

See Also:

• hasMetaParents(Object)

isIdenticalOrUndefined

protected TriState isIdenticalOrUndefined(Object receiver,
 Object other)

Returns TRUE if the receiver is or FALSE if the receiver is not identical to the other value. Returns UNDEFINED if the operation is not specified.

Sample interpretations:

• A Java object might be of the identical instance as another Java object. Typically compared using the == operator.

Any implementation, with the exception of an implementation that returns UNDEFINED unconditionally, must guarantee the following properties:

• It is reflexive: for any value x, lib.isIdenticalOrUndefined(x, x) always returns TRUE. This is necessary to ensure that the hasIdentity(Object) contract has reliable results.
• It is symmetric: for any values x and y, lib.isIdenticalOrUndefined(x, y) returns TRUE if and only if lib.isIdenticalOrUndefined(y, x) returns TRUE.
• It is transitive: for any values x, y, and z, if lib.isIdenticalOrUndefined(x, y) returns TRUE and lib.isIdenticalOrUndefined(y, z) returns TRUE, then lib.isIdentical(x, z, zLib) returns TRUE.
• It is consistent: for any values x and y, multiple invocations of lib.isIdenticalOrUndefined(x, y) consistently returns the same value.

Note that the target language identical semantics typically does not map directly to interop identical implementation. Instead target language identity is specified by the language operation, may take multiple other rules into account and may only fallback to interop identical for values without dedicated interop type. For example, in many languages primitives like numbers or strings may be identical, in the target language sense, still identity can only be exposed for objects and non-primitive values. Primitive values like Integer can never be interop identical to other boxed language integers as this would violate the symmetric property.

Example receiver class MyObject which uses an explicit identity field to compute whether two values are identical.

 static class MyObject {

     final Object identity;

     MyObject(Object identity) {
         this.identity = identity;
     }

     @ExportMessage
     static final class IsIdenticalOrUndefined {
         @Specialization
         static TriState doMyObject(MyObject receiver, MyObject other) {
             return receiver.identity == other.identity ? TriState.TRUE : TriState.FALSE;
         }

         @Fallback
         static TriState doOther(MyObject receiver, Object other) {
             return TriState.UNDEFINED;
         }
     }
     // ...
 }
 

This method must not cause any observable side-effects. If this method is implemented then also identityHashCode(Object) must be implemented.

Parameters:

other - the other value to compare to

Since:

20.2

isIdentical

public boolean isIdentical(Object receiver,
 Object other,
 InteropLibrary otherInterop)

Returns true if two values represent the the identical value, else false. Two values are identical if and only if they have specified identity semantics in the target language and refer to the identical instance.

By default, an interop value does not support identical comparisons, and will return false for any invocation of this method. Use hasIdentity(Object) to find out whether a receiver supports identity comparisons.

This method has the following properties:

• It is not reflexive: for any value x, lib.isIdentical(x, x, lib) may return false if the object does not support identity, else true. This method is reflexive if x supports identity. A value supports identity if lib.isIdentical(x, x, lib) returns true. The method hasIdentity(Object) may be used to document this intent explicitly.
• It is symmetric: for any values x and y, lib.isIdentical(x, y, yLib) returns true if and only if lib.isIdentical(y, x, xLib) returns true.
• It is transitive: for any values x, y, and z, if lib.isIdentical(x, y, yLib) returns true and lib.isIdentical(y, z, zLib) returns true, then lib.isIdentical(x, z, zLib) returns true.
• It is consistent: for any values x and y, multiple invocations of lib.isIdentical(x, y, yLib) consistently returns true or consistently return false.

Note that the target language identical semantics typically does not map directly to interop identical implementation. Instead target language identity is specified by the language operation, may take multiple other rules into account and may only fallback to interop identical for values without dedicated interop type. For example, in many languages primitives like numbers or strings may be identical, in the target language sense, still identity can only be exposed for objects and non-primitive values. Primitive values like Integer can never be interop identical to other boxed language integers as this would violate the symmetric property.

This method performs double dispatch by forwarding calls to isIdenticalOrUndefined(Object, Object) with receiver and other value first and then with reversed parameters if the result was undefined. This allows the receiver and the other value to negotiate identity semantics. This method is supposed to be exported only if the receiver represents a wrapper that forwards messages. In such a case the isIdentical message should be forwarded to the delegate value. Otherwise, the isIdenticalOrUndefined(Object, Object) should be exported instead.

This method must not cause any observable side-effects.

Cached usage example:

 abstract class IsIdenticalUsage extends Node {

     abstract boolean execute(Object left, Object right);

     @Specialization(limit = "3")
     public boolean isIdentical(Object left, Object right,
                     @CachedLibrary("left") InteropLibrary leftInterop,
                     @CachedLibrary("right") InteropLibrary rightInterop) {
         return leftInterop.isIdentical(left, right, rightInterop);
     }
 }
 

Uncached usage example:

 @TruffleBoundary
 public static boolean isIdentical(Object left, Object right) {
     return InteropLibrary.getUncached(left).isIdentical(left, right,
                     InteropLibrary.getUncached(right));
 }
 

For a full example please refer to the SLEqualNode of the SimpleLanguage example implementation.

Since:

20.2

hasIdentity

public final boolean hasIdentity(Object receiver)

Returns true if and only if the receiver specifies identity, else false. This method is a short-cut for this.isIdentical(receiver, receiver, this) != TriState.UNDEFINED. This message cannot be exported. To add identity support to the receiver export isIdenticalOrUndefined(Object, Object) instead.

Since:

20.2

See Also:

• isIdenticalOrUndefined(Object, Object)

identityHashCode

public int identityHashCode(Object receiver)
                     throws UnsupportedMessageException

Returns an identity hash code for the receiver if it has identity. If the receiver has no identity then an UnsupportedMessageException is thrown. The identity hash code may be used by languages to store foreign values with identity in an identity hash map.

• Whenever it is invoked on the same object more than once during an execution of a guest context, the identityHashCode method must consistently return the same integer. This integer need not remain consistent from one execution context of a guest application to another execution context of the same application.
• If two objects are the same according to the isIdentical(Object, Object, InteropLibrary) message, then calling the identityHashCode method on each of the two objects must produce the same integer result.
• As much as is reasonably practical, the identityHashCode message does return distinct integers for objects that are not the same.

This method must not cause any observable side-effects. If this method is implemented then also isIdenticalOrUndefined(Object, Object) must be implemented.

Throws:

UnsupportedMessageException - if and only if hasIdentity(Object) returns false for the same receiver.

Since:

20.2

See Also:

• isIdenticalOrUndefined(Object, Object)
• isIdentical(Object, Object, InteropLibrary)

isScope

public boolean isScope(Object receiver)

Returns true if the value represents a scope object, else false. The scope object contains variables as members and has a scope display name. It needs to be associated with a language. The scope may return a source location that indicates the range of the scope in the source code. The scope may have parent scopes.

The members of a scope represent all visible flattened variables, including all parent scopes, if any. The variables of the current scope must be listed first in getMembers(Object). Variables of the parent scope must be listed afterwards, even if they contain duplicates. This allows to resolve which variables are redeclared in sub scopes.

Every member may not be just a String literal, but a string object that provides also a source location of its declaration. When different variables of the same name are in different scopes, they will be represented by different member elements providing the same name.

This method must not cause any observable side-effects. If this method is implemented then also hasMembers(Object) and toDisplayString(Object, boolean) must be implemented and hasSourceLocation(Object) is recommended.

Since:

20.3

See Also:

• getLanguage(Object)
• getMembers(Object)
• hasScopeParent(Object)

hasScopeParent

public boolean hasScopeParent(Object receiver)

Returns true if this scope has an enclosing parent scope, else false.

This method must not cause any observable side-effects. If this method is implemented then also isScope(Object) and getScopeParent(Object) must be implemented.

Since:

20.3

See Also:

• isScope(Object)
• getScopeParent(Object)

getScopeParent

public Object getScopeParent(Object receiver)
                      throws UnsupportedMessageException

Returns the parent scope object if it has the parent. The returned object must be a scope and must provide a reduced list of member variables, omitting all variables that are local to the current scope.

This method must not cause any observable side-effects. If this method is implemented then also isScope(Object) and getScopeParent(Object) must be implemented.

Throws:

UnsupportedMessageException - if and only if hasScopeParent(Object) returns false for the same receiver.

Since:

20.3

See Also:

• isScope(Object)
• hasScopeParent(Object)

getFactory

public static LibraryFactory<InteropLibrary> getFactory()

Returns the library factory for the interop library. Short-cut for ResolvedLibrary.resolve(InteropLibrary.class).

Since:

19.0

See Also:

• LibraryFactory.resolve(Class)

getUncached

public static InteropLibrary getUncached()

Returns the uncached automatically dispatched version of the interop library. This is a short-cut for calling InteropLibrary.getFactory().getUncached().

Since:

20.2

See Also:

• LibraryFactory.getUncached()

getUncached

public static InteropLibrary getUncached(Object v)

Returns the uncached manually dispatched version of the interop library. This is a short-cut for calling InteropLibrary.getFactory().getUncached(v).

Since:

20.2

See Also:

• LibraryFactory.getUncached(Object)

assertAdopted

protected final boolean assertAdopted()

Utility for libraries to require adoption before cached versions of nodes can be executed. Only fails if assertions (-ea) are enabled.

Since:

19.0

isValidValue

public static boolean isValidValue(Object receiver)

Utility to check whether a value is a valid interop value. Interop values are all values that can flow through the language implementation freely and are intended to be used as receivers for the InteropLibrary. This method will be extended with more checked types as interop is extended with further allowed values.

It is not recommended to make assumptions about the types of interop values. It is recommended to use instance methods in InteropLibrary to check for interop types instead. However, it can be useful to make such assumptions for performance reasons. To verify that these assumptions continue to hold this method can be used.

Since:

21.3

isValidProtocolValue

public static boolean isValidProtocolValue(Object value)

Utility to check whether a value is a valid interop protocol value. An interop protocol value is either an interop value or a value that might be returned or passed as parameter by any of the methods in InteropLibrary. This can be useful to validate all values received or returned by a wrapper that uses ReflectionLibrary to delegate all interop protocol parameters and return values. This method will be extended with more checked types as interop is extended with further allowed values.

Since:

21.3

See Also:

• isValidValue(Object)