Graal Sdk 23.1.1 · org.graalvm.polyglot.Value · APIdia, the JavaDoc alternative

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.

Access	Constructor and Description
pack-priv	Value(AbstractPolyglotImpl.AbstractValueDispatch dispatch, Object context, Object receiver)

Method Summary

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

public final Class Value

Naive and aware dates and times

Scoped Values

Field Summary

Constructor Summary

Method Summary