Value (GraalVM SDK Java API Reference)

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, float or double value.
- Boolean. This value represents a boolean value. The boolean value can be accessed using Value.asBoolean().
- String: This value represents a string value. The string value can be accessed using Value.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 Value.asDuration().
- Host Object: This value represents a value of the host language (Java). The original Java value can be accessed using Value.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 Value.asNativePointer().
- Exception: This value represents an exception object. The exception can be thrown using Value.throwException().
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 Value.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.
In addition to the language agnostic types, the language specific type can be accessed using Value.getMetaObject(). The identity of value objects is unspecified and should not be relied upon. For example, multiple calls to Value.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 Value.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.
Since:

19.0

See Also:

Context, Engine, PolyglotException

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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.
`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 the receiver 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 the receiver 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 the receiver 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.
`LocalTime`	`asTime()` Returns the receiver as time if this object represents a `time`.
`ZoneId`	`asTimeZone()` Returns the receiver 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.
`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`	`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`.
`Value`	`getArrayElement(long index)` Returns the array element of a given index.
`long`	`getArraySize()` Returns the array size for values with array elements.
`Context`	`getContext()` Returns the context this value was created with.
`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 meta representation of this polyglot value.
`SourceSection`	`getSourceLocation()` Returns the declared source location of the value.
`boolean`	`hasArrayElements()` Returns `true` if this polyglot value has array elements.
`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.
`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`	`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 the receiver represents an instant.
`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`	`putMember(String identifier, Object value)` Sets the value of a member using an identifier.
`boolean`	`removeArrayElement(long index)` Removes an array element at a given index.
`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 the receiver if this object represents an `exception`.
`String`	`toString()` A string representation of the value formatted by the original language.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - getMetaObject
```
public Value getMetaObject()
```
    Returns the meta representation of this polyglot value. The interpretation of this function differs for each guest language. A language agnostic way to get to a type name is: value.getMetaObject().toString(). If a language does not provide any meta object information, null is returned.
    
    Throws:
    
    IllegalStateException - if the context is already closed.
    
    Since:
    
    19.0
  - hasArrayElements
```
public boolean hasArrayElements()
```
    Returns true if this polyglot value has array elements. In this case array elements can be accessed using Value.getArrayElement(long), Value.setArrayElement(long, Object), Value.removeArrayElement(long) and the array size can be queried using Value.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.
    
    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
  - 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 Value.getMember(String), Value.putMember(String, Object) and Value.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 Value.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 Value.hasMember(String). Removing an element from the returned set is equivalent to calling Value.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.
    
    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:
    
    Value.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 Value.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:
    
    Value.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:
    
    Value.execute(Object...)
  - canInstantiate
```
public boolean canInstantiate()
```
    Returns true if the value can be instantiated. This indicates that the Value.newInstance(Object...) can be used with this value.
    
    Since:
    
    19.0
  - 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 (Value.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., Value.invokeMember(String, Object...)
  - invokeMember
```
public Value invokeMember(String identifier,
                          Object... arguments)
```
    Invokes the given member of this value. Unlike Value.execute(Object...), this is an object oriented execution of a member of an object. To test whether invocation is supported, call Value.canInvokeMember(String). When object oriented semantics are not supported, use Value.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:
    
    Value.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
  - 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:
    
    Value.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:
    
    Value.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:
    
    Value.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
  - 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:
    
    Value.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:
    
    Value.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:
    
    Value.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:
    
    Value.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 Value.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 Value.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 Value.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 Value.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 when the context is constructed. 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.
    - Object.class is always supported. See section Object mapping rules.
    - Map.class is supported if the value has members or array elements. The returned map can be safely cast to Map. The key type in such a case is either String or 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. 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 the value has array elements and it has an array size that is smaller or equal than 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.
    - 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.
    - Any functional interface if 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 Value.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. 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 a UnsupportedOperationException is thrown when the method is executed. A member If one of the parameters cannot be mapped to the target type a ClassCastException or a NullPointerException is thrown.
    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 ((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){a})").as(IntFunction.class).foo(42) == 42;

 @FunctionalInterface interface StringListFunction { int foo(List<String> value); }
 assert context.eval("js", "(function(a){a.length})").as(StringListFunction.class)
                                                     .foo(new String[]{"42"}) == 1;
 
```
    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 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.
    7. 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.
    8. 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 Map if the value has array elements or members.
    9. 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:
    
    Value.as(Class)
  - toString
```
public String toString()
```
    A string representation of the value formatted by the original language.
    
    Overrides:
    
    toString in class Object
    
    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 the receiver 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:
    
    Value.asDate()
  - asDate
```
public LocalDate asDate()
```
    Returns the receiver as date if this object represents a date. The returned date is either aware if the receiver has a timezone otherwise it is naive.
    
    Throws:
    
    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:
    
    Value.isDate()
  - isTime
```
public boolean isTime()
```
    Returns true if this object represents a time, else false. If the receiver is also a timezone then the time is aware, otherwise it is naive.
    
    Throws:
    
    IllegalStateException - if the underlying context is already closed.
    
    Since:
    
    19.2.0
    
    See Also:
    
    Value.asTime()
  - asTime
```
public LocalTime asTime()
```
    Returns the receiver as time if this object represents a time. The returned time is either aware if the receiver has a timezone otherwise it is naive.
    
    Throws:
    
    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:
    
    Value.isTime()
  - isInstant
```
public boolean isInstant()
```
    Returns true if the receiver represents an instant. If a value is an instant then it is also a date, time and timezone. This method is short-hand for:
```
 v.isDate() && v.isTime() && v.isTimeZone()
 
```
    Throws:
    
    IllegalStateException - if the underlying context is already closed.
    
    Since:
    
    19.2.0
    
    See Also:
    
    Value.isDate(), Value.isTime(), Value.isInstant(), Value.asInstant()
  - asInstant
```
public Instant asInstant()
```
    Returns the receiver as instant if this object represents an instant. If a value is an instant then it is also a date, time and timezone. Using this method may be more efficient than reconstructing the timestamp from the date, time and timezone data.
    The following assertion always holds if Value.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:
    
    Value.isDate(), Value.isTime(), Value.isTimeZone()
  - isTimeZone
```
public boolean isTimeZone()
```
    Returns true if this object represents a timezone, else false. The interpretation of timezone objects may vary:
    - If Value.isDate() and Value.isTime() return true, then the returned date or time information is aware of this timezone.
    - If Value.isDate() and Value.isTime() returns false, then it represents just timezone information.
    Objects with only time or only date information must not have timezone information attached, as aware date or time information always consist of both date and time. If this rule is violated then an AssertionError is thrown if assertions are enabled.
    If this method is implemented then also Value.asTimeZone() must be implemented.
    Throws:
    
    IllegalStateException - if the underlying context is already closed.
    
    Since:
    
    19.2.0
    
    See Also:
    
    Value.asTimeZone(), Value.asInstant()
  - asTimeZone
```
public ZoneId asTimeZone()
```
    Returns the receiver 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:
    
    Value.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, Value.asDate()
  - asDuration
```
public Duration asDuration()
```
    Returns the receiver 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:
    
    Value.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:
    
    Value.throwException()
  - throwException
```
public RuntimeException throwException()
```
    Throws the receiver 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:
    
    Value.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 Value.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
  - 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 Value.getContext().
    
    Parameters:
    
    o - the object to convert
    
    Throws:
    
    IllegalStateException - if no context is currently entered.
    
    Since:
    
    19.0
    
    See Also:
    
    Conversion rules.

Class Value

Naive and aware dates and times

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getMetaObject

hasArrayElements

getArrayElement

setArrayElement

removeArrayElement

getArraySize

hasMembers

hasMember

getMember

getMemberKeys

putMember

removeMember

canExecute

execute

executeVoid

canInstantiate

newInstance

canInvokeMember

invokeMember

isString

asString

fitsInInt

asInt

isBoolean

asBoolean

isNumber

fitsInLong

asLong

fitsInDouble

asDouble

fitsInFloat

asFloat

fitsInByte

asByte

fitsInShort

asShort

isNull

isNativePointer

asNativePointer

isHostObject

asHostObject

isProxyObject

asProxyObject

as

Target type mapping

Object target type mapping

Object Identity

as

toString

getSourceLocation

isDate

asDate

isTime

asTime

isInstant

asInstant

isTimeZone

asTimeZone

isDuration

asDuration

isException

throwException

getContext

asValue