Package org.graalvm.polyglot

Class Value

java.lang.Object

org.graalvm.polyglot.Value

public final class Value
extends Object

Represents a polyglot value that can be accessed using a set of language agnostic operations. Polyglot values represent values from host or guest language. Polyglot values are bound to a context. If the context is closed then all value operations throw an IllegalStateException.

Polyglot values have one of the following type combinations:

• Null: This value represents a null like value. Certain languages might use a different name or use multiple values to represent null like values.
• Number: This value represents a floating or fixed point number. The number value may be accessed as byte, short, int, long, asBigInteger() BigInteger}, float, or double value.
• Boolean. This value represents a boolean value. The boolean value can be accessed using asBoolean().
• String: This value represents a string value. The string value can be accessed using asString().
• Date, Time or Timezone: This value represents a date, time or timezone. Multiple types may return true at the same time.
• Duration: This value represents a duration value. The duration value can be accessed using asDuration().
• Host Object: This value represents a value of the host language (Java). The original Java value can be accessed using asHostObject().
• Proxy Object: This value represents a proxy value.
• Native Pointer: This value represents a native pointer. The native pointer value can be accessed using asNativePointer().
• Exception: This value represents an exception object. The exception can be thrown using throwException().
• Meta-Object: This value represents a metaobject. Access metaobject operations using getMetaSimpleName(), getMetaQualifiedName() and isMetaInstance(Object).
• Iterator: This value represents an iterator. The iterator can be iterated using hasIteratorNextElement() and getIteratorNextElement().

In addition any value may have one or more of the following traits:

• Array Elements: This value may contain array elements. The array indices always start with 0, also if the language uses a different style.
• Members: This value may contain members. Members are structural elements of an object. For example, the members of a Java object are all public methods and fields. Members are accessible using getMember(String).
• Executable: This value can be executed. This indicates that the value represents an element that can be executed. Guest language examples for executable elements are functions, methods, closures or promises.
• Instantiable: This value can be instantiated. For example, Java classes are instantiable.
• Buffer Elements: This value may contain buffer elements. The buffer indices always start with 0, also if the language uses a different style.
• Iterable: This value provides an iterator which can be used to iterate value elements. For example, Guest language arrays are iterable.
• hasHashEntries() Hash Entries}: This value represents a map.
• hasMetaParents() Meta Parents}: This value represents Array Elements of Meta Objects.

In addition to the language agnostic types, the language specific type can be accessed using getMetaObject(). The identity of value objects is unspecified and should not be relied upon. For example, multiple calls to getArrayElement(long) with the same index might return the same or different instances of Value. The equality of values is based on the identity of the value instance. All values return a human-readable string for debugging, formatted by the original language.

Polyglot values may be converted to host objects using as(Class). In addition values may be created from Java values using Context.asValue(Object).

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.

Scoped Values

In the case of a guest-to-host callback, a value may be passed as a parameter. These values may represent objects that are only valid during the invocation of the callback function, i.e. they are scoped, with the scope being the callback function. If enabled via the corresponding settings in HostAccess, such values are released when the function returns, with all future invocations of value operations throwing an exception. If an embedder wishes to extend the scope of the value beyond the callback's return, the value can be pinned, such that it is not released automatically.

Since:

19.0

See Also:

• Context
• Engine
• PolyglotException

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	Value.StringEncoding	Enum like class representing the supported string encodings.

Method Summary

Modifier and Type	Method	Description
<T> T	as(Class<T> targetType)	Maps a polyglot value to a value with a given Java target type.
<T> T	as(TypeLiteral<T> targetType)	Maps a polyglot value to a given Java target type literal.
BigInteger	asBigInteger()	Returns a BigInteger representation of this value if it is number and the value fits.
boolean	asBoolean()	Returns a boolean representation of this value if it is boolean.
byte	asByte()	Returns a byte representation of this value if it is number and the value fits.
LocalDate	asDate()	Returns this value as date if this object represents a date.
double	asDouble()	Returns a double representation of this value if it is number and the value fits.
Duration	asDuration()	Returns this value as duration if this object represents a duration.
float	asFloat()	Returns a float representation of this value if it is number and the value fits.
<T> T	asHostObject()	Returns the original Java host language object.
Instant	asInstant()	Returns this value as instant if this object represents an instant.
int	asInt()	Returns an int representation of this value if it is number and the value fits.
long	asLong()	Returns a long representation of this value if it is number and the value fits.
long	asNativePointer()	Returns the value of the pointer as long value.
<T extends Proxy> T	asProxyObject()	Returns the unboxed instance of the Proxy.
short	asShort()	Returns a short representation of this value if it is number and the value fits.
String	asString()	Returns the String value if this value is a string.
byte[]	asStringBytes(Value.StringEncoding encoding)	Returns the bytes of a given string value without converting it to a Java String.
LocalTime	asTime()	Returns this value as time if this object represents a time.
ZoneId	asTimeZone()	Returns this value as timestamp if this object represents a timezone.
static Value	asValue(Object o)	Converts a Java host value to a polyglot value.
boolean	canExecute()	Returns true if the value can be executed.
boolean	canInstantiate()	Returns true if the value can be instantiated.
boolean	canInvokeMember(String identifier)	Returns true if the given member exists and can be invoked.
boolean	equals(Object obj)	Compares the identity of the underlying polyglot objects.
Value	execute(Object... arguments)	Executes this value if it can be executed and returns its result.
void	executeVoid(Object... arguments)	Executes this value if it can be executed.
boolean	fitsInBigInteger()	Returns true if this value represents a number and the value fits in BigInteger, else false.
boolean	fitsInByte()	Returns true if this value represents a number and the value fits in byte, else false.
boolean	fitsInDouble()	Returns true if this value represents a number and the value fits in double, else false.
boolean	fitsInFloat()	Returns true if this value represents a number and the value fits in float, else false.
boolean	fitsInInt()	Returns true if this value represents a number and the value fits in int, else false.
boolean	fitsInLong()	Returns true if this value represents a number and the value fits in long, else false.
boolean	fitsInShort()	Returns true if this value represents a number and the value fits in short, else false.
static Value	fromByteBasedString(byte[] bytes, int offset, int length, Value.StringEncoding encoding, boolean copy)	Creates a byte-based string value with more granular control over the byte array's usage.
static Value	fromByteBasedString(byte[] bytes, Value.StringEncoding encoding)	Creates a byte-based string value that can be passed to polyglot languages.
static Value	fromNativeString(long basePointer, int byteOffset, int byteLength, Value.StringEncoding encoding, boolean copy)	Creates a native string object that can be passed to polyglot languages.
static Value	fromNativeString(long basePointer, int byteLength, Value.StringEncoding encoding)	Creates a native string object with default safety settings.
Value	getArrayElement(long index)	Returns the array element of a given index.
long	getArraySize()	Returns the array size for values with array elements.
long	getBufferSize()	Returns the buffer size in bytes for values with buffer elements.
Context	getContext()	Returns the context this value was created with.
Value	getHashEntriesIterator()	Creates a new hash entries iterator that allows read each map entry.
Value	getHashKeysIterator()	Creates a new hash keys iterator that allows read each map key.
long	getHashSize()	Returns the number of map entries for values with hash entries.
Value	getHashValue(Object key)	Returns the value for the specified key or null if the mapping for the specified key does not exist.
Value	getHashValueOrDefault(Object key, Object defaultValue)	Returns the value for the specified key or the default value if the mapping for the specified key does not exist or is not readable.
Value	getHashValuesIterator()	Creates a new hash values iterator that allows read each map value.
Value	getIterator()	Creates a new iterator that allows read each element of a sequence.
Value	getIteratorNextElement()	Returns the next element in the iteration.
Value	getMember(String identifier)	Returns the member with a given identifier or null if the member does not exist.
Set<String>	getMemberKeys()	Returns a set of all member keys.
Value	getMetaObject()	Returns the metaobject that is associated with this value or null if no metaobject is available.
Value	getMetaParents()	Returns the meta parents of a meta object as an array object hasArrayElements().
String	getMetaQualifiedName()	Returns the qualified name of a metaobject as String.
String	getMetaSimpleName()	Returns the simple name of a metaobject as string.
SourceSection	getSourceLocation()	Returns the declared source location of the value.
boolean	hasArrayElements()	Returns true if this polyglot value has array elements.
boolean	hasBufferElements()	Returns true if the receiver may have buffer elements.
boolean	hasHashEntries()	Returns true if this polyglot value represents a map.
boolean	hasHashEntry(Object key)	Returns true if mapping for the specified key exists.
int	hashCode()	Returns the identity hash code of the underlying object.
boolean	hasIterator()	Returns true if this polyglot value provides an iterator.
boolean	hasIteratorNextElement()	Returns true if the value represents an iterator which has more elements, else false.
boolean	hasMember(String identifier)	Returns true if such a member exists for a given identifier.
boolean	hasMembers()	Returns true if this value generally supports containing members.
boolean	hasMetaParents()	Returns true if the value represents a metaobject and the metaobject has meta parents.
Value	invokeMember(String identifier, Object... arguments)	Invokes the given member of this value.
boolean	isBoolean()	Returns true if this value represents a boolean value.
boolean	isBufferWritable()	Returns true if the receiver object is a modifiable buffer.
boolean	isDate()	Returns true if this object represents a date, else false.
boolean	isDuration()	Returns true if this object represents a duration, else false.
boolean	isException()	Returns true if this object represents an exception, else false.
boolean	isHostObject()	Returns true if the value originated form the host language Java.
boolean	isInstant()	Returns true if this value represents an instant.
boolean	isIterator()	Returns true if the value represents an iterator object.
boolean	isMetaInstance(Object instance)	Returns true if the given instance is an instance of this value, else false.
boolean	isMetaObject()	Returns true if the value represents a metaobject.
boolean	isNativePointer()	Returns true if this value is a native pointer.
boolean	isNull()	Returns true if this value is a null like.
boolean	isNumber()	Returns true if this value represents a number, else false.
boolean	isProxyObject()	Returns true if this value represents a Proxy.
boolean	isString()	Returns true if this value represents a string.
boolean	isTime()	Returns true if this object represents a time, else false.
boolean	isTimeZone()	Returns true if this object represents a timezone, else false.
Value	newInstance(Object... arguments)	Instantiates this value if it can be instantiated.
void	pin()	Pins a scoped value such that it can be used beyond the scope of a scoped host method call.
void	putHashEntry(Object key, Object value)	Associates the specified value with the specified key.
void	putMember(String identifier, Object value)	Sets the value of a member using an identifier.
void	readBuffer(long byteOffset, byte[] destination, int destinationOffset, int length)	Reads bytes from the receiver object into the specified byte array.
byte	readBufferByte(long byteOffset)	Reads the byte at the given byte offset from the start of the buffer.
double	readBufferDouble(ByteOrder order, long byteOffset)	Reads the double at the given byte offset from the start of the buffer in the given byte order.
float	readBufferFloat(ByteOrder order, long byteOffset)	Reads the float at the given byte offset from the start of the buffer in the given byte order.
int	readBufferInt(ByteOrder order, long byteOffset)	Reads the int at the given byte offset from the start of the buffer in the given byte order.
long	readBufferLong(ByteOrder order, long byteOffset)	Reads the long at the given byte offset from the start of the buffer in the given byte order.
short	readBufferShort(ByteOrder order, long byteOffset)	Reads the short at the given byte offset from the start of the buffer in the given byte order.
boolean	removeArrayElement(long index)	Removes an array element at a given index.
boolean	removeHashEntry(Object key)	Removes the mapping for a given key.
boolean	removeMember(String identifier)	Removes a single member from the object.
void	setArrayElement(long index, Object value)	Sets the value at a given index.
RuntimeException	throwException()	Throws this value if this object represents an exception.
String	toString()	Converts this value to a human readable string.
void	writeBufferByte(long byteOffset, byte value)	Writes the given byte at the given byte offset from the start of the buffer.
void	writeBufferDouble(ByteOrder order, long byteOffset, double value)	Writes the given double in the given byte order at the given byte offset from the start of the buffer.
void	writeBufferFloat(ByteOrder order, long byteOffset, float value)	Writes the given float in the given byte order at the given byte offset from the start of the buffer.
void	writeBufferInt(ByteOrder order, long byteOffset, int value)	Writes the given int in the given byte order at the given byte offset from the start of the buffer.
void	writeBufferLong(ByteOrder order, long byteOffset, long value)	Writes the given long in the given byte order at the given byte offset from the start of the buffer.
void	writeBufferShort(ByteOrder order, long byteOffset, short value)	Writes the given short in the given byte order at the given byte offset from the start of the buffer.

Methods inherited from class java.lang.Object

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

Method Details

getMetaObject

public Value getMetaObject()

Returns the metaobject that is associated with this value or null if no metaobject is available. The metaobject represents a description of the object, reveals it's kind and it's features. Some information that a metaobject might define includes the base object's type, interface, class, methods, attributes, etc.

The returned value returns true for isMetaObject() and provides implementations for getMetaSimpleName(), getMetaQualifiedName(), and isMetaInstance(Object).

This method does not cause any observable side-effects.

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

19.0 revised in 20.1

See Also:

• isMetaObject()

isMetaObject

public boolean isMetaObject()

Returns true if the value represents a metaobject. Metaobjects may be values that naturally occur in a language or they may be returned by getMetaObject(). A metaobject represents a description of the object, reveals its kind and its features. Returns false by default. Metaobjects are often also instantiable, but not necessarily.

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 does not cause any observable side-effects. If this method is implemented then also getMetaQualifiedName(), getMetaSimpleName() and isMetaInstance(Object) must be implemented as well.

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

20.1

See Also:

• getMetaQualifiedName()
• getMetaSimpleName()
• isMetaInstance(Object)
• getMetaObject()

getMetaQualifiedName

public String getMetaQualifiedName()

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.

Throws:

UnsupportedOperationException - if and only if isMetaObject() returns false for the same value.

PolyglotException - if a guest language error occurred during execution.

Since:

20.1

getMetaSimpleName

public String getMetaSimpleName()

Returns the simple name of a metaobject as string.

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

Throws:

UnsupportedOperationException - if and only if isMetaObject() returns false for the same value.

PolyglotException - if a guest language error occurred during execution.

Since:

20.1

isMetaInstance

public boolean isMetaInstance(Object instance)

Returns true if the given instance is an instance of this value, else false. The instance value is subject to polyglot value mapping rules as described in Context.asValue(Object).

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

Parameters:

instance - the instance object to check.

Throws:

UnsupportedOperationException - if and only if isMetaObject() returns false for the same value.

PolyglotException - if a guest language error occurred during execution.

Since:

20.1

hasMetaParents

public boolean hasMetaParents()

Returns true if the value represents a metaobject and the metaobject has meta parents. Returns false by default.

Sample interpretations: In Java an instance of the type Class is a metaobject. Further, the superclass and the implemented interfaces types of that type constitute the meta parents. In JavaScript any function instance is a metaobject. For example, the metaobject of a JavaScript class is the associated constructor function.

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

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

22.2

See Also:

• getMetaParents()

getMetaParents

public Value getMetaParents()

Returns the meta parents of a meta object as an array object hasArrayElements(). This method does not cause any observable side-effects. If this method is implemented then also hasMetaParents() must be implemented as well.

Throws:

IllegalStateException - if the context is already closed.

UnsupportedOperationException - if the value does not have any hasMetaParents() meta parents.

PolyglotException - if a guest language error occurred during execution.

Since:

22.2

See Also:

• hasMetaParents()

hasArrayElements

public boolean hasArrayElements()

Returns true if this polyglot value has array elements. In this case array elements can be accessed using getArrayElement(long), setArrayElement(long, Object), removeArrayElement(long) and the array size can be queried using getArraySize().

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

19.0

getArrayElement

public Value getArrayElement(long index)

Returns the array element of a given index. Polyglot arrays start with index 0, independent of the guest language. The given array index must be greater or equal to 0.

Throws:

ArrayIndexOutOfBoundsException - if the array index does not exist.

UnsupportedOperationException - if the value does not have any array elements or if the index exists but is not readable.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

19.0

setArrayElement

public void setArrayElement(long index,
 Object value)

Sets the value at a given index. Polyglot arrays start with index 0, independent of the guest language. The array element value is subject to polyglot value mapping rules as described in Context.asValue(Object).

Throws:

ArrayIndexOutOfBoundsException - if the array index does not exist.

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

UnsupportedOperationException - if the value does not have any array elements or if the index exists but is not modifiable.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

19.0

removeArrayElement

public boolean removeArrayElement(long index)

Removes an array element at a given index. Returns true if the underlying array element could be removed, otherwise false.

Throws:

ArrayIndexOutOfBoundsException - if the array index does not exist.

UnsupportedOperationException - if the value does not have any array elements or if the index exists but is not removable.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

19.0

getArraySize

public long getArraySize()

Returns the array size for values with array elements.

Throws:

UnsupportedOperationException - if the value does not have any array elements.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

19.0

hasBufferElements

public boolean hasBufferElements()

Returns true if the receiver may have buffer elements. In this case, the buffer size can be queried using getBufferSize() and elements can be read using readBufferByte(long), readBufferShort(ByteOrder, long), readBufferInt(ByteOrder, long), readBufferLong(ByteOrder, long), readBufferFloat(ByteOrder, long) and readBufferDouble(ByteOrder, long). If isBufferWritable() returns true, then buffer elements can also be written using writeBufferByte(long, byte), writeBufferShort(ByteOrder, long, short), writeBufferInt(ByteOrder, long, int), writeBufferLong(ByteOrder, long, long), writeBufferFloat(ByteOrder, long, float) and writeBufferDouble(ByteOrder, long, double).

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

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

See Also:

• hasBufferElements()

isBufferWritable

public boolean isBufferWritable()
                         throws UnsupportedOperationException

Returns true if the receiver object is a modifiable buffer. In this case, elements can be written using writeBufferByte(long, byte), writeBufferShort(ByteOrder, long, short), writeBufferInt(ByteOrder, long, int), writeBufferLong(ByteOrder, long, long), writeBufferFloat(ByteOrder, long, float) and writeBufferDouble(ByteOrder, long, double).

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

Throws:

UnsupportedOperationException - if the value does not have buffer elements.

Since:

21.1

getBufferSize

public long getBufferSize()
                   throws UnsupportedOperationException

Returns the buffer size in bytes for values with buffer elements.

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

Throws:

UnsupportedOperationException - if the value does not have buffer elements.

Since:

21.1

readBufferByte

public byte readBufferByte(long byteOffset)
                    throws UnsupportedOperationException,
IndexOutOfBoundsException

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

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

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

Parameters:

byteOffset - the offset, in bytes, from the start of the buffer at which the byte will be read.

Returns:

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

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize().

UnsupportedOperationException - if the value does not have buffer elements.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

readBuffer

public void readBuffer(long byteOffset,
 byte[] destination,
 int destinationOffset,
 int length)
                throws UnsupportedOperationException,
IndexOutOfBoundsException

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.

Example reading into an output stream using a 4k auxiliary byte array:

 Value val = ...
 assert val.hasBufferElements();
 try (OutputStream out = ...) {
     byte[] aux = new byte[4096];
     long bufferSize = val.getBufferSize();
     for (long offset = 0; offset < bufferSize; offset += aux.length) {
         int bytesToRead = (int) Math.min(bufferSize - offset, aux.length);
         val.readBuffer(offset, aux, 0, bytesToRead);
         out.write(aux, 0, bytesToRead);
     }
 }
 

In case the goal is to read the whole contents into a single byte array, the easiest way is to do that through ByteSequence:

 byte[] byteArray = val.as(ByteSequence.class).toByteArray();
 

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:

IndexOutOfBoundsException - if and only if byteOffset < 0 || length < 0 || byteOffset + length > getBufferSize() || destinationOffset < 0 || destinationOffset + length > destination.length

UnsupportedOperationException - if the value does not have buffer elements.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

24.0

writeBufferByte

public void writeBufferByte(long byteOffset,
 byte value)
                     throws UnsupportedOperationException,
IndexOutOfBoundsException

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

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

Parameters:

byteOffset - the offset, in bytes, from the start of the buffer at which the byte will be written.

value - the byte value to be written.

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize().

UnsupportedOperationException - if the value does not have buffer elements or is not modifiable.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

readBufferShort

public short readBufferShort(ByteOrder order,
 long byteOffset)
                      throws UnsupportedOperationException,
IndexOutOfBoundsException

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

Unaligned accesses are supported.

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

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

Parameters:

order - the order in which to read the individual bytes of the short.

byteOffset - the offset, in bytes, from the start of the buffer from which the short will be read.

Returns:

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

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize() - 1.

UnsupportedOperationException - if the value does not have buffer elements.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

writeBufferShort

public void writeBufferShort(ByteOrder order,
 long byteOffset,
 short value)
                      throws UnsupportedOperationException,
IndexOutOfBoundsException

Writes the given short 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 method is not thread-safe.

Parameters:

order - the order in which to write the individual bytes of the short.

byteOffset - the offset, in bytes, from the start of the buffer from which the short will be written.

value - the short value to be written.

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize() - 1.

UnsupportedOperationException - if the value does not have buffer elements or is not modifiable.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

readBufferInt

public int readBufferInt(ByteOrder order,
 long byteOffset)
                  throws UnsupportedOperationException,
IndexOutOfBoundsException

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

Unaligned accesses are supported.

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

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

Parameters:

order - the order in which to read the individual bytes of the int.

byteOffset - the offset, in bytes, from the start of the buffer from which the int will be read.

Returns:

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

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize() - 3.

UnsupportedOperationException - if the value does not have buffer elements.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

writeBufferInt

public void writeBufferInt(ByteOrder order,
 long byteOffset,
 int value)
                    throws UnsupportedOperationException,
IndexOutOfBoundsException

Writes the given int 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 method is not thread-safe.

Parameters:

order - the order in which to write the individual bytes of the int.

byteOffset - the offset, in bytes, from the start of the buffer from which the int will be written.

value - the int value to be written.

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize() - 3.

UnsupportedOperationException - if the value does not have buffer elements or is not modifiable.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

readBufferLong

public long readBufferLong(ByteOrder order,
 long byteOffset)
                    throws UnsupportedOperationException,
IndexOutOfBoundsException

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

Unaligned accesses are supported.

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

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

Parameters:

order - the order in which to read the individual bytes of the long.

byteOffset - the offset, in bytes, from the start of the buffer from which the int will be read.

Returns:

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

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize() - 7.

UnsupportedOperationException - if the value does not have buffer elements.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

writeBufferLong

public void writeBufferLong(ByteOrder order,
 long byteOffset,
 long value)
                     throws UnsupportedOperationException,
IndexOutOfBoundsException

Writes the given long 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 method is not thread-safe.

Parameters:

order - the order in which to write the individual bytes of the long.

byteOffset - the offset, in bytes, from the start of the buffer from which the int will be written.

value - the int value to be written.

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize() - 7.

UnsupportedOperationException - if the value does not have buffer elements or is not modifiable.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

readBufferFloat

public float readBufferFloat(ByteOrder order,
 long byteOffset)
                      throws UnsupportedOperationException,
IndexOutOfBoundsException

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

Unaligned accesses are supported.

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

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

Parameters:

order - the order in which to read the individual bytes of the float.

byteOffset - the offset, in bytes, from the start of the buffer from which the float will be read.

Returns:

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

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize() - 3.

UnsupportedOperationException - if the value does not have buffer elements.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

writeBufferFloat

public void writeBufferFloat(ByteOrder order,
 long byteOffset,
 float value)
                      throws UnsupportedOperationException,
IndexOutOfBoundsException

Writes the given float 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 method is not thread-safe.

Parameters:

order - the order in which to read the individual bytes of the float.

byteOffset - the offset, in bytes, from the start of the buffer from which the float will be written.

value - the float value to be written.

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize() - 3.

UnsupportedOperationException - if the value does not have buffer elements or is not modifiable.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

readBufferDouble

public double readBufferDouble(ByteOrder order,
 long byteOffset)
                        throws UnsupportedOperationException,
IndexOutOfBoundsException

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

Unaligned accesses are supported.

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

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

Parameters:

order - the order in which to write the individual bytes of the double.

byteOffset - the offset, in bytes, from the start of the buffer from which the double will be read.

Returns:

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

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize() - 7.

UnsupportedOperationException - if the value does not have buffer elements.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

writeBufferDouble

public void writeBufferDouble(ByteOrder order,
 long byteOffset,
 double value)
                       throws UnsupportedOperationException,
IndexOutOfBoundsException

Writes the given double 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 method is not thread-safe.

Parameters:

order - the order in which to write the individual bytes of the double.

byteOffset - the offset, in bytes, from the start of the buffer from which the double will be written.

value - the double value to be written.

Throws:

IndexOutOfBoundsException - if and only if byteOffset < 0 || byteOffset >= getBufferSize() - 7.

UnsupportedOperationException - if the value does not have buffer elements or is not modifiable.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

hasMembers

public boolean hasMembers()

Returns true if this value generally supports containing members. To check whether a value has no members use getMemberKeys().isEmpty() instead. If polyglot value has members, it may also support getMember(String), putMember(String, Object) and removeMember(String).

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

19.0

See Also:

• To check the existence of members.
• To read members.
• To write members.
• To remove a member.
• For a list of members.

hasMember

public boolean hasMember(String identifier)

Returns true if such a member exists for a given identifier. If the value has no members then hasMember(String) returns false.

Throws:

PolyglotException - if a guest language error occurred during execution.

NullPointerException - if the identifier is null.

Since:

19.0

getMember

public Value getMember(String identifier)

Returns the member with a given identifier or null if the member does not exist.

Throws:

UnsupportedOperationException - if the value has no members or the given identifier exists but is not readable.

PolyglotException - if a guest language error occurred during execution.

NullPointerException - if the identifier is null.

Since:

19.0

getMemberKeys

public Set<String> getMemberKeys()

Returns a set of all member keys. Calling Set.contains(Object) with a string key is equivalent to calling hasMember(String). Removing an element from the returned set is equivalent to calling removeMember(String). Adding an element to the set is equivalent to calling putMember(key, null). If the value does not support members then an empty unmodifiable set is returned. If the context gets closed while the returned set is still alive, then the set will throw an IllegalStateException if any methods except Object methods are invoked.

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

19.0

putMember

public void putMember(String identifier,
 Object value)

Sets the value of a member using an identifier. The member value is subject to polyglot value mapping rules as described in Context.asValue(Object).

Throws:

IllegalStateException - if the context is already closed.

UnsupportedOperationException - if the value does not have any members, the key does not exist and new members cannot be added, or the existing member is not modifiable.

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

PolyglotException - if a guest language error occurred during execution.

NullPointerException - if the identifier is null.

Since:

19.0

removeMember

public boolean removeMember(String identifier)

Removes a single member from the object. Returns true if the member was successfully removed, false if such a member does not exist.

Throws:

UnsupportedOperationException - if the value does not have any members or if the key exists but cannot be removed.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

NullPointerException - if the identifier is null.

Since:

19.0

canExecute

public boolean canExecute()

Returns true if the value can be executed.

Throws:

IllegalStateException - if the underlying context was closed.

Since:

19.0

See Also:

• execute(Object...)

execute

public Value execute(Object... arguments)

Executes this value if it can be executed and returns its result. If no result value is expected or needed use executeVoid(Object...) for better performance. All arguments are subject to polyglot value mapping rules as described in Context.asValue(Object).

Throws:

IllegalStateException - if the underlying context was closed.

IllegalArgumentException - if a wrong number of arguments was provided or one of the arguments was not applicable.

UnsupportedOperationException - if this value cannot be executed.

PolyglotException - if a guest language error occurred during execution.

NullPointerException - if the arguments array is null.

Since:

19.0

See Also:

• executeVoid(Object...)

executeVoid

public void executeVoid(Object... arguments)

Executes this value if it can be executed. All arguments are subject to polyglot value mapping rules as described in Context.asValue(Object).

Throws:

IllegalStateException - if the underlying context was closed.

IllegalArgumentException - if a wrong number of arguments was provided or one of the arguments was not applicable.

UnsupportedOperationException - if this value cannot be executed.

PolyglotException - if a guest language error occurred during execution.

NullPointerException - if the arguments array is null.

Since:

19.0

See Also:

• execute(Object...)

canInstantiate

public boolean canInstantiate()

Returns true if the value can be instantiated. This indicates that the newInstance(Object...) can be used with this value. If a value is instantiable it is often also a isMetaObject(), but this is not a requirement.

Since:

19.0

See Also:

• isMetaObject()

newInstance

public Value newInstance(Object... arguments)

Instantiates this value if it can be instantiated. All arguments are subject to polyglot value mapping rules as described in Context.asValue(Object).

Throws:

IllegalStateException - if the underlying context was closed.

IllegalArgumentException - if a wrong number of arguments was provided or one of the arguments was not applicable.

UnsupportedOperationException - if this value cannot be instantiated.

PolyglotException - if a guest language error occurred during execution.

NullPointerException - if the arguments array is null.

Since:

19.0

canInvokeMember

public boolean canInvokeMember(String identifier)

Returns true if the given member exists and can be invoked. Returns false if the member does not exist (hasMember(String) returns false), or is not invocable.

Parameters:

identifier - the member identifier

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred.

Since:

19.0

See Also:

• For a list of members.
• invokeMember(String, Object...)

invokeMember

public Value invokeMember(String identifier,
 Object... arguments)

Invokes the given member of this value. Unlike execute(Object...), this is an object oriented execution of a member of an object. To test whether invocation is supported, call canInvokeMember(String). When object oriented semantics are not supported, use getMember(String).execute(Object...) instead.

Parameters:

identifier - the member identifier to invoke

arguments - the invocation arguments

Throws:

UnsupportedOperationException - if this member cannot be invoked.

PolyglotException - if a guest language error occurred during invocation.

NullPointerException - if the arguments array is null.

Since:

19.0

See Also:

• canInvokeMember(String)

isString

public boolean isString()

Returns true if this value represents a string.

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

asString

public String asString()

Returns the String value if this value is a string. This method returns null if this value represents a null value.

Throws:

ClassCastException - if this value could not be converted to string.

UnsupportedOperationException - if this value does not represent a string.

PolyglotException - if a guest language error occurred during execution.

Since:

19.0

asStringBytes

public byte[] asStringBytes(Value.StringEncoding encoding)

Returns the bytes of a given string value without converting it to a Java String.

This method retrieves the raw bytes of the string in the specified Value.StringEncoding, avoiding intermediate conversions to a Java String. This is particularly useful for performance-sensitive scenarios where the overhead of creating a Java String is undesirable.

If the string is not already encoded in the specified encoding, it will be re-encoded before the bytes are returned. Note that re-encoding may involve additional computational overhead depending on the size of the string and the differences between its current encoding and the target encoding. Usage Note: The returned byte array represents the raw data of the string in the requested encoding. Modifications to the array will not affect the underlying string value.

Parameters:

encoding - the desired encoding for the string. Must not be null. Supported encodings are defined in Value.StringEncoding.

Returns:

a byte array containing the string's raw bytes in the specified encoding

Throws:

NullPointerException - if encoding is null

IllegalStateException - if the string value is no longer valid (e.g., the associated context has been closed)

Since:

24.2

fitsInInt

public boolean fitsInInt()

Returns true if this value represents a number and the value fits in int, else false.

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

See Also:

• asInt()

asInt

public int asInt()

Returns an int representation of this value if it is number and the value fits.

Throws:

NullPointerException - if this value represents null.

ClassCastException - if this value could not be converted.

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

isBoolean

public boolean isBoolean()

Returns true if this value represents a boolean value.

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

See Also:

• asBoolean()

asBoolean

public boolean asBoolean()

Returns a boolean representation of this value if it is boolean.

Throws:

NullPointerException - if this value represents null

ClassCastException - if this value could not be converted.

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

isNumber

public boolean isNumber()

Returns true if this value represents a number, else false. The number value may be accessed as byte, short int long, float or double value.

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

fitsInLong

public boolean fitsInLong()

Returns true if this value represents a number and the value fits in long, else false.

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

See Also:

• asLong()

asLong

public long asLong()

Returns a long representation of this value if it is number and the value fits.

Throws:

NullPointerException - if this value represents null.

ClassCastException - if this value could not be converted to long.

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

fitsInBigInteger

public boolean fitsInBigInteger()

Returns true if this value represents a number and the value fits in BigInteger, else false.

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

23.0

See Also:

• asBigInteger()

asBigInteger

public BigInteger asBigInteger()

Returns a BigInteger representation of this value if it is number and the value fits.

Throws:

NullPointerException - if this value represents null.

ClassCastException - if this value could not be converted to BigInteger.

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

23.0

fitsInDouble

public boolean fitsInDouble()

Returns true if this value represents a number and the value fits in double, else false.

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

See Also:

• asDouble()

asDouble

public double asDouble()

Returns a double representation of this value if it is number and the value fits.

Throws:

NullPointerException - if this value represents null.

ClassCastException - if this value could not be converted.

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

fitsInFloat

public boolean fitsInFloat()

Returns true if this value represents a number and the value fits in float, else false.

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

See Also:

• asFloat()

asFloat

public float asFloat()

Returns a float representation of this value if it is number and the value fits.

Throws:

NullPointerException - if this value represents null.

ClassCastException - if this value could not be converted.

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

fitsInByte

public boolean fitsInByte()

Returns true if this value represents a number and the value fits in byte, else false.

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

See Also:

• asByte()

asByte

public byte asByte()

Returns a byte representation of this value if it is number and the value fits.

Throws:

NullPointerException - if this value represents null.

ClassCastException - if this value could not be converted.

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

fitsInShort

public boolean fitsInShort()

Returns true if this value represents a number and the value fits in short, else false.

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

See Also:

• asShort()

asShort

public short asShort()

Returns a short representation of this value if it is number and the value fits.

Throws:

NullPointerException - if this value represents null.

ClassCastException - if this value could not be converted.

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

isNull

public boolean isNull()

Returns true if this value is a null like.

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

isNativePointer

public boolean isNativePointer()

Returns true if this value is a native pointer. The value of the pointer can be accessed using asNativePointer().

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

asNativePointer

public long asNativePointer()

Returns the value of the pointer as long value.

Throws:

UnsupportedOperationException - if the value is not a pointer.

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

isHostObject

public boolean isHostObject()

Returns true if the value originated form the host language Java. In such a case the value can be accessed using asHostObject().

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

asHostObject

public <T> T asHostObject()

Returns the original Java host language object.

Throws:

UnsupportedOperationException - if isHostObject() is false.

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

isProxyObject

public boolean isProxyObject()

Returns true if this value represents a Proxy. The proxy instance can be unboxed using asProxyObject().

Throws:

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

asProxyObject

public <T extends Proxy> T asProxyObject()

Returns the unboxed instance of the Proxy. Proxies are not automatically boxed to host objects on host language call boundaries (Java methods).

Throws:

UnsupportedOperationException - if a value is not a proxy object.

PolyglotException - if a guest language error occurred during execution.

IllegalStateException - if the underlying context was closed.

Since:

19.0

as

public <T> T as(Class<T> targetType)
         throws ClassCastException,
IllegalStateException,
PolyglotException

Maps a polyglot value to a value with a given Java target type.

Target type mapping

The following target types are supported and interpreted in the following order:

• Custom target type mappings specified in the HostAccess configuration with precedence HostAccess.TargetMappingPrecedence.HIGHEST or HostAccess.TargetMappingPrecedence.HIGH. These custom target type mappings may override all the type mappings below. This allows for customization if one of the below type mappings is not suitable.
• Value.class is always supported and returns this instance.
• If the value represents a host object then all classes implemented or extended by the host object can be used as target type.
• String.class is supported if the value is a string.
• Character.class is supported if the value is a string of length one or if a number can be safely be converted to a character.
• Number.class is supported if the value is a number. Byte, Short, Integer, Long, Float and Double are allowed if they fit without conversion. If a conversion is necessary then a ClassCastException is thrown. Primitive class literals throw a NullPointerException if the value represents null.
• Boolean.class is supported if the value is a boolean. Primitive boolean.class literal is also supported. The primitive class literal throws a NullPointerException if the value represents null.
• LocalDate.class is supported if the value is a date
• LocalTime.class is supported if the value is a time
• LocalDateTime.class is supported if the value is a date and time.
• Instant.class is supported if the value is an instant.
• ZonedDateTime.class is supported if the value is a date, time and timezone.
• ZoneId.class is supported if the value is a timezone.
• Duration.class is supported if the value is a duration.
• PolyglotException.class is supported if the value is an exception object.
• Any Java type in the type hierarchy of a host object.
• Custom target type mappings specified in the HostAccess configuration with precedence HostAccess.TargetMappingPrecedence.LOW.
• Object.class is always supported. See section Object mapping rules.
• Map.class is supported if HostAccess.MutableTargetMapping.MEMBERS_TO_JAVA_MAP respectively HostAccess.MutableTargetMapping.HASH_TO_JAVA_MAP are allowed and the value has hasHashEntries() hash entries}, members or array elements. The returned map can be safely cast to Map<Object, Object>. For value with members the key type is String. For value with array elements the key type is Long. It is recommended to use type literals to specify the expected collection component types. With type literals the value type can be restricted, for example to Map<String, String>. If the raw Map.class or an Object component type is used, then the return types of the the list are subject to Object target type mapping rules recursively.
• List.class is supported if HostAccess.MutableTargetMapping.ARRAY_TO_JAVA_LIST is allowed and the value has array elements and it has an array size that is smaller or equal to Integer.MAX_VALUE. The returned list can be safely cast to List<Object>. It is recommended to use type literals to specify the expected component type. With type literals the value type can be restricted to any supported target type, for example to List<Integer>. If the raw List.class or an Object component type is used, then the return types of the the list are recursively subject to Object target type mapping rules.
• ByteSequence.class is supported if the value has buffer elements and it has a buffer size that is smaller or equal to Integer.MAX_VALUE.
• byte[].class is supported if the value has buffer elements and it has a buffer size that is smaller or equal to Integer.MAX_VALUE - 8. The contents of the buffer will be copied to a new byte array with appropriate size.
• Any Java array type of a supported target type. The values of the value will be eagerly coerced and copied into a new instance of the provided array type. This means that changes in returned array will not be reflected in the original value. Since conversion to a Java array might be an expensive operation it is recommended to use the `List` or `Collection` target type if possible.
• Iterable.class is supported if HostAccess.MutableTargetMapping.ITERATOR_TO_JAVA_ITERATOR is allowed and the value has an iterator. The returned iterable can be safely cast to Iterable<Object>. It is recommended to use type literals to specify the expected component type. With type literals the value type can be restricted to any supported target type, for example to Iterable<Integer>.
• Iterator.class is supported if HostAccess.MutableTargetMapping.ITERATOR_TO_JAVA_ITERATOR is allowed and the value is an iterator The returned iterator can be safely cast to Iterator<Object>. It is recommended to use type literals to specify the expected component type. With type literals the value type can be restricted to any supported target type, for example to Iterator<Integer>. If the raw Iterator.class or an Object component type is used, then the return types of the the iterator are recursively subject to Object target type mapping rules. The returned iterator's next method may throw a ConcurrentModificationException when an underlying iterable has changed or UnsupportedOperationException when the iterator's current element is not readable.
• Any functional interface if HostAccess.MutableTargetMapping.EXECUTABLE_TO_JAVA_INTERFACE is allowed and the value can be executed or instantiated and the interface type is implementable. Note that FunctionalInterface are implementable by default in with the explicit host access policy. In case a value can be executed and instantiated then the returned implementation of the interface will be executed. The coercion to the parameter types of functional interface method is converted using the semantics of as(Class). If a standard functional interface like Function is used, it is recommended to use type literals to specify the expected generic method parameter and return type.
• Any interface if the value has members and the interface type is implementable and HostAccess.MutableTargetMapping.MEMBERS_TO_JAVA_INTERFACE is allowed. Each interface method maps to one member of the value. Whenever a method of the interface is executed a member with the method or field name must exist otherwise an UnsupportedOperationException is thrown when the method is executed. If one of the parameters or the return value cannot be mapped to the target type a ClassCastException or a NullPointerException is thrown.
• JVM only: Any abstract class with an accessible default constructor if the value has members and the class is implementable. Each interface method maps to one member of the value. Whenever an abstract method of the class is executed a member with the method or field name must exist otherwise an UnsupportedOperationException is thrown when the method is executed. If one of the parameters or the return value cannot be mapped to the target type a ClassCastException or a NullPointerException is thrown.
• Custom target type mappings specified in the HostAccess configuration with precedence HostAccess.TargetMappingPrecedence.LOWEST.

A ClassCastException is thrown for other unsupported target types.

JavaScript Usage Examples:

 Context context = Context.newBuilder().allowHostAccess(HostAccess.ALL).build();
 assert context.eval("js", "undefined").as(Object.class) == null;
 assert context.eval("js", "'foobar'").as(String.class).equals("foobar");
 assert context.eval("js", "42").as(Integer.class) == 42;
 assert context.eval("js", "({foo:'bar'})").as(Map.class).get("foo").equals("bar");
 assert context.eval("js", "[42]").as(List.class).get(0).equals(42);
 assert Arrays.equals(context.eval("js", "([0, 1, 127])").as(byte[].class), new byte[]{0, 1, 127});
 assert Arrays.equals(context.eval("js", "(new Uint8Array([0, 1, 127, 255]))").getMember("buffer").as(byte[].class), new byte[]{0, 1, 127, -1});
 assert ((Map<String, Object>) context.eval("js", "[{foo:'bar'}]").as(List.class).get(0)).get("foo").equals("bar");

 @FunctionalInterface
 interface IntFunction {
     int foo(int value);
 }
 assert context.eval("js", "(function(a){return a})").as(IntFunction.class).foo(42).asInt() == 42;

 @FunctionalInterface
 interface StringListFunction {
     int foo(List<String> value);
 }
 assert context.eval("js", "(function(a){return a.length})").as(StringListFunction.class).foo(new String[]{"42"}).asInt() == 1;

 public abstract class AbstractClass {
     public AbstractClass() {
     }

     int foo(int value);
 }
 assert context.eval("js", "({foo: function(a){return a}})").as(AbstractClass.class).foo(42).asInt() == 42;
 

Object target type mapping

Object target mapping is useful to map polyglot values to its closest corresponding standard JDK type. The following rules apply when Object is used as a target type:

1. If the value represents null then null is returned.
2. If the value is a host object then the value is coerced to host object value.
3. If the value is a string then the value is coerced to String or Character.
4. If the value is a boolean then the value is coerced to Boolean.
5. If the value is a number then the value is coerced to Number. The specific sub type of the Number is not specified. Users need to be prepared for any Number subclass including BigInteger or BigDecimal. It is recommended to cast to Number and then convert to a Java primitive like with Number.longValue().
6. If the value has array elements and it has an array size that is smaller or equal than Integer.MAX_VALUE then the result value will implement List. Every array element of the value maps to one list element. The size of the returned list maps to the array size of the value. The returned value may also implement Function if the value can be executed or instantiated.
7. If the value has hash entries then the result value will implement Map. The size of the returned Map is equal to the hash entries count. The returned value may also implement Function if the value can be executed or instantiated.
8. If the value has members then the result value will implement Map. If this value has members then all members are accessible using String keys. The size of the returned Map is equal to the count of all members. The returned value may also implement Function if the value can be executed or instantiated.
9. If the value has an hasIterator() iterator} then the result value will implement Iterable. The returned value may also implement Function if the value can be executed or instantiated.
10. If the value is an isIterator() iterator} then the result value will implement Iterator. The returned value may also implement Function if the value can be executed or instantiated.
11. If the value can be executed or instantiated then the result value implements Function. By default the argument of the function will be used as single argument to the function when executed. If a value of type Object[] is provided then the function will be executed with those arguments. The returned function may also implement List or Map if the value has array elements or members, respectively.
12. Mappings to mutable target types such as List, Map, Iterator and Iterable are only available if the corresponding mappings are enabled (see HostAccess.Builder.allowMutableTargetMappings(org.graalvm.polyglot.HostAccess.MutableTargetMapping...)).
13. If none of the above rules apply then this Value instance is returned.

Returned host objects, String, Number, Boolean and null values have unlimited lifetime. Other values will throw an IllegalStateException for any operation if their originating context was closed.

If a Map element is modified, a List element is modified or a Function argument is provided then these values are interpreted according to the host to polyglot value mapping rules.

JavaScript Usage Examples:

 Context context = Context.create();
 assert context.eval("js", "undefined").as(Object.class) == null;
 assert context.eval("js", "'foobar'").as(Object.class) instanceof String;
 assert context.eval("js", "42").as(Object.class) instanceof Number;
 assert context.eval("js", "[]").as(Object.class) instanceof Map;
 assert context.eval("js", "{}").as(Object.class) instanceof Map;
 assert ((Map<Object, Object>) context.eval("js", "[{}]").as(Object.class)).get(0) instanceof Map;
 assert context.eval("js", "(function(){})").as(Object.class) instanceof Function;
 

Object Identity

If polyglot values are mapped as Java primitives such as Boolean, null, String, Character or Number, then the identity of the polyglot value is not preserved. All other results can be converted back to a polyglot value using Context.asValue(Object). Mapping Example using JavaScript: This example first creates a new JavaScript object and maps it to a Map. Using the Context.asValue(Object) it is possible to recreate the polyglot value from the Java map. The JavaScript object identity is preserved in the process.

 Context context = Context.create();
 Map<Object, Object> javaMap = context.eval("js", "{}").as(Map.class);
 Value polyglotValue = context.asValue(javaMap);
 

Parameters:

targetType - the target Java type to map

Throws:

ClassCastException - if polyglot value could not be mapped to the target type.

PolyglotException - if the conversion triggered a guest language error.

IllegalStateException - if the underlying context is already closed.

NullPointerException - if the target type is null.

Since:

19.0

See Also:

• to map to generic type signatures.

as

public <T> T as(TypeLiteral<T> targetType)

Maps a polyglot value to a given Java target type literal. For usage instructions see TypeLiteral.

Usage example:

 static final TypeLiteral<List<String>> STRING_LIST = new TypeLiteral<List<String>>() {
 };

 public static void main(String[] args) {
     Context context = Context.create();
     List<String> javaList = context.eval("js", "['foo', 'bar', 'bazz']").as(STRING_LIST);
     assert javaList.get(0).equals("foo");
 }
 

Throws:

NullPointerException - if the target type is null.

Since:

19.0

See Also:

• as(Class)

toString

public String toString()

Converts this value to a human readable string. Each language may have special formating conventions - even primitive values may not follow the traditional Java formating 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 this value class name and its identity hash code is used as string representation.

Since:

19.0

getSourceLocation

public SourceSection getSourceLocation()

Returns the declared source location of the value.

Returns:

the SourceSection or null if unknown

Since:

19.0

isDate

public boolean isDate()

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

Throws:

ClassCastException - if polyglot value could not be mapped to the target type.

NullPointerException - if the target type is null.

PolyglotException - if the conversion triggered a guest language error.

IllegalStateException - if the underlying context is already closed.

Since:

19.2.0

See Also:

• asDate()

asDate

public LocalDate asDate()

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

Throws:

ClassCastException - if polyglot value could not be mapped to the target type.

NullPointerException - if the target type is null.

PolyglotException - if the conversion triggered a guest language error.

IllegalStateException - if the underlying context is already closed.

Since:

19.2.0

See Also:

• isDate()

isTime

public boolean isTime()

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

Throws:

IllegalStateException - if the underlying context is already closed.

Since:

19.2.0

See Also:

• asTime()

asTime

public LocalTime asTime()

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

Throws:

ClassCastException - if polyglot value could not be mapped to the target type.

NullPointerException - if the target type is null.

PolyglotException - if the conversion triggered a guest language error.

IllegalStateException - if the underlying context is already closed.

Since:

19.2.0

See Also:

• isTime()

isInstant

public boolean isInstant()

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

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

Throws:

IllegalStateException - if the underlying context is already closed.

Since:

19.2.0

See Also:

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

asInstant

public Instant asInstant()

Returns this value 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.

The following assertion always holds if isInstant() returns true:

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

Throws:

ClassCastException - if polyglot value could not be mapped to the target type.

NullPointerException - if the target type is null.

PolyglotException - if the conversion triggered a guest language error.

IllegalStateException - if the underlying context is already closed.

Since:

19.2.0

See Also:

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

isTimeZone

public boolean isTimeZone()

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

• If isDate() and isTime() return true, then the returned date or time information is aware of this timezone.
• If isDate() and isTime() 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() must be implemented.

Throws:

IllegalStateException - if the underlying context is already closed.

Since:

19.2.0

See Also:

• asTimeZone()
• asInstant()

asTimeZone

public ZoneId asTimeZone()

Returns this value as timestamp if this object represents a timezone.

Throws:

ClassCastException - if polyglot value could not be mapped to the target type.

PolyglotException - if the conversion triggered a guest language error.

IllegalStateException - if the underlying context is already closed.

NullPointerException - if the target type is null.

Since:

19.2.0

See Also:

• isTimeZone()

isDuration

public boolean isDuration()

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

Throws:

IllegalStateException - if the underlying context is already closed.

Since:

19.2.0

See Also:

• Duration
• asDuration()

asDuration

public Duration asDuration()

Returns this value as duration if this object represents a duration.

Throws:

ClassCastException - if polyglot value could not be mapped to the target type.

PolyglotException - if the conversion triggered a guest language error.

IllegalStateException - if the underlying context is already closed.

NullPointerException - if the target type is null.

Since:

19.2.0

See Also:

• isDuration()

isException

public boolean isException()

Returns true if this object represents an exception, else false.

Throws:

IllegalStateException - if the underlying context is already closed.

Since:

19.3

See Also:

• throwException()

throwException

public RuntimeException throwException()

Throws this value if this object represents an exception.

Throws:

UnsupportedOperationException - if the value is not an exception.

IllegalStateException - if the underlying context is already closed.

Since:

19.3

See Also:

• isException()

getContext

public Context getContext()

Returns the context this value was created with. The returned context may be null if the value was created using asValue(Object) and no current context was entered at the time.

The returned context can not be used to enter , leave or close the context or engine. Invoking such methods will cause an IllegalStateException to be thrown. This ensures that only the creator of a context is allowed to enter, leave or close a context and that a context is not closed while it is still active.

Since:

19.3.0

equals

public boolean equals(Object obj)

Compares the identity of the underlying polyglot objects. This method does not do any structural comparisons.

Since:

20.1

hashCode

public int hashCode()

Returns the identity hash code of the underlying object. This method does not compute the hash code depending on the contents of the value.

Since:

20.1

hasIterator

public boolean hasIterator()

Returns true if this polyglot value provides an iterator. In this case the iterator can be obtained using getIterator().

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

See Also:

• getIterator()

getIterator

public Value getIterator()

Creates a new iterator that allows read each element of a sequence.

Throws:

UnsupportedOperationException - if the value does not provide iterator.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

See Also:

• hasIterator()

isIterator

public boolean isIterator()

Returns true if the value represents an iterator object. In this case the iterator elements can be accessed using getIteratorNextElement().

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

See Also:

• hasIteratorNextElement()
• getIteratorNextElement()

hasIteratorNextElement

public boolean hasIteratorNextElement()

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

Throws:

UnsupportedOperationException - if the value is not an iterator.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

See Also:

• isIterator()
• getIteratorNextElement()

getIteratorNextElement

public Value getIteratorNextElement()

Returns the next element in the iteration. When the underlying data structure is modified the getIteratorNextElement() may throw the NoSuchElementException despite the hasIteratorNextElement() returned true, or it may throw a language error.

Throws:

UnsupportedOperationException - if the value is not an iterator or when the underlying iterable element exists but is not readable.

NoSuchElementException - if the iteration has no more elements. Even if the NoSuchElementException was thrown it might not be thrown again by a next call of the getIteratorNextElement() due to a modification of an underlying iterable.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

See Also:

• isIterator()
• hasIteratorNextElement()

hasHashEntries

public boolean hasHashEntries()

Returns true if this polyglot value represents a map. In this case map entries can be accessed using getHashValue(Object), getHashValueOrDefault(Object, Object), putHashEntry(Object, Object), removeHashEntry(Object), getHashEntriesIterator() and the map size can be queried using getHashSize().

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

getHashSize

public long getHashSize()
                 throws UnsupportedOperationException

Returns the number of map entries for values with hash entries.

Throws:

UnsupportedOperationException - if the value does not have any hasHashEntries() hash entries}.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

hasHashEntry

public boolean hasHashEntry(Object key)

Returns true if mapping for the specified key exists. If the value has no hash entries then hasHashEntry(Object) returns false. The key is subject to polyglot value mapping rules as described in Context.asValue(Object).

Throws:

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

getHashValue

public Value getHashValue(Object key)
                   throws UnsupportedOperationException

Returns the value for the specified key or null if the mapping for the specified key does not exist. The key is subject to polyglot value mapping rules as described in Context.asValue(Object).

Throws:

UnsupportedOperationException - if the value has no hash entries or the mapping for given key exists but is not readable.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

getHashValueOrDefault

public Value getHashValueOrDefault(Object key,
 Object defaultValue)
                            throws UnsupportedOperationException

Returns the value for the specified key or the default value if the mapping for the specified key does not exist or is not readable. The key and the default value are subject to polyglot value mapping rules as described in Context.asValue(Object).

Throws:

UnsupportedOperationException - if the value has no hash entries at all.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

putHashEntry

public void putHashEntry(Object key,
 Object value)
                  throws IllegalArgumentException,
UnsupportedOperationException

Associates the specified value with the specified key. Both key and value are subject to polyglot value mapping rules as described in Context.asValue(Object).

Throws:

UnsupportedOperationException - if the value does not have any hash entries, the mapping for specified key does not exist and new members cannot be added, or the existing mapping for specified key is not modifiable.

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

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

removeHashEntry

public boolean removeHashEntry(Object key)
                        throws UnsupportedOperationException

Removes the mapping for a given key. Returns true if the mapping was successfully removed, false if mapping for a given key does not exist. The key is subject to polyglot value mapping rules as described in Context.asValue(Object).

Throws:

UnsupportedOperationException - if the value does not have any hash entries or if mapping for specified key exists but cannot be removed.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

getHashEntriesIterator

public Value getHashEntriesIterator()
                             throws UnsupportedOperationException

Creates a new hash entries iterator that allows read each map entry. 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. Even if the value array element is modifiable writing to array may not update the mapping, always use putHashEntry(Object, Object) to update the mapping.

Throws:

UnsupportedOperationException - if the value does not have any hash entries.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

getHashKeysIterator

public Value getHashKeysIterator()
                          throws UnsupportedOperationException

Creates a new hash keys iterator that allows read each map key. The return value is always an iterator.

Throws:

UnsupportedOperationException - if the value does not have any hash entries.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

getHashValuesIterator

public Value getHashValuesIterator()
                            throws UnsupportedOperationException

Creates a new hash values iterator that allows read each map value. The return value is always an iterator.

Throws:

UnsupportedOperationException - if the value does not have any hash entries.

IllegalStateException - if the context is already closed.

PolyglotException - if a guest language error occurred during execution.

Since:

21.1

asValue

public static Value asValue(Object o)

Converts a Java host value to a polyglot value. Returns a value for any host or guest value. If there is a context available use Context.asValue(Object) for efficiency instead. The value is bound the current context when created. If there is no context available when the value was constructed then Values constructed with this method may return null for getContext().

Parameters:

o - the object to convert

Throws:

IllegalStateException - if no context is currently entered.

Since:

19.0

See Also:

• Conversion rules.

pin

public void pin()

Pins a scoped value such that it can be used beyond the scope of a scoped host method call. Pinning is an idempotent operation, i.e. pinning an already pinned value just results in a pinned value again. Trying to pin a value that is not scoped will not cause an effect. Trying to pin a scoped value that has already been released will raise a IllegalStateException.

Throws:

IllegalStateException - if the method scope of the value was finished

Since:

21.3

See Also:

• HostAccess.SCOPED

fromByteBasedString

public static Value fromByteBasedString(byte[] bytes,
 Value.StringEncoding encoding)

Creates a byte-based string value that can be passed to polyglot languages.

The returned value is guaranteed to return true for isString(). The string can later be retrieved as a byte array using asStringBytes(StringEncoding). This method ensures immutability by conservatively copying the byte array before passing it to the underlying implementation.

Performance Note: Copying the byte array can have a performance impact. Use this method when immutability is required, or use the more flexible overloaded method fromByteBasedString(byte[], int, int, StringEncoding, boolean) to control copying behavior.

Parameters:

bytes - the byte array representing the string

encoding - the encoding of the byte array

Returns:

a polyglot string Value

Throws:

NullPointerException - if either bytes or encoding is null

Since:

24.2

fromByteBasedString

public static Value fromByteBasedString(byte[] bytes,
 int offset,
 int length,
 Value.StringEncoding encoding,
 boolean copy)

Creates a byte-based string value with more granular control over the byte array's usage.

This method provides additional flexibility by allowing a subset of the byte array to be passed and controlling whether the byte array should be copied to ensure immutability.

Parameters:

bytes - the byte array representing the string

offset - the starting offset in the byte array

length - the number of bytes to include starting from offset

encoding - the encoding of the byte array

copy - whether to copy the byte array to ensure immutability

Returns:

a polyglot string Value

Since:

24.2

fromNativeString

public static Value fromNativeString(long basePointer,
 int byteOffset,
 int byteLength,
 Value.StringEncoding encoding,
 boolean copy)

Creates a native string object that can be passed to polyglot languages.

Native strings avoid copying, offering better performance for certain use cases. However, clients must guarantee the lifetime of the native string as long as the Value is alive. The returned value is guaranteed to return true for isString().

Usage Warning: The polyglot context or engine does not manage the lifetime of the native pointer. Clients must ensure that the pointer remains valid and that the memory is not deallocated while the string is in use. Passing a deallocated or invalid pointer can result in crashes or undefined behavior.

Note: Whenever possible, use fromByteBasedString(byte[], StringEncoding) to avoid the risks associated with native memory management.

• The native string's memory must remain valid for the lifetime of the context it is passed to.
• The native bytes must not be mutated after being passed to this method.
• The bytes must already be encoded with the specified encoding.

Parameters:

basePointer - the raw base pointer to the native string in memory

byteLength - the length of the string in bytes

encoding - the encoding of the native string

copy - whether to copy the native string bytes for additional safety

Returns:

a polyglot string Value

Since:

24.2

fromNativeString

public static Value fromNativeString(long basePointer,
 int byteLength,
 Value.StringEncoding encoding)

Creates a native string object with default safety settings.

This method is equivalent to calling fromNativeString(long, int, int, StringEncoding, boolean) with copy set to true.

Parameters:

basePointer - the raw base pointer to the native string in memory

byteLength - the length of the string in bytes

encoding - the encoding of the native string

Returns:

a polyglot string Value

Since:

24.2