public final class Value extends Object
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()
.
Meta-Object
: This value represents a metaobject. Access metaobject
operations using Value.getMetaSimpleName()
, Value.getMetaQualifiedName()
and
Value.isMetaInstance(Object)
.
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)
.
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.
Context
,
Engine
,
PolyglotException
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()
|
LocalDate |
asDate()
Returns this value as date if this object represents a
date . |
double |
asDouble()
|
Duration |
asDuration()
Returns this value as duration if this object represents a
duration . |
float |
asFloat()
|
<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()
|
long |
asLong()
|
long |
asNativePointer()
Returns the value of the pointer as
long value. |
<T extends Proxy> |
asProxyObject()
Returns the unboxed instance of the
Proxy . |
short |
asShort()
|
String |
asString()
|
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 |
fitsInByte()
|
boolean |
fitsInDouble()
|
boolean |
fitsInFloat()
|
boolean |
fitsInInt()
|
boolean |
fitsInLong()
|
boolean |
fitsInShort()
|
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 metaobject that is associated with this value or
null if no
metaobject is available. |
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. |
int |
hashCode()
Returns the identity hash code of the underlying object.
|
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 this value represents an instant. |
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()
|
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 this value if this object represents an
exception . |
String |
toString()
Converts this value to a human readable string.
|
public Value getMetaObject()
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 Value.isMetaObject()
and provides
implementations for Value.getMetaSimpleName()
, Value.getMetaQualifiedName()
, and
Value.isMetaInstance(Object)
.
This method does not cause any observable side-effects.
IllegalStateException
- if the context is already closed.PolyglotException
- if a guest language error occurred during execution.Value.isMetaObject()
public boolean isMetaObject()
true
if the value represents a metaobject. Metaobjects may be values
that naturally occur in a language or they may be returned by Value.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 Value.getMetaQualifiedName()
, Value.getMetaSimpleName()
and
Value.isMetaInstance(Object)
must be implemented as well.
IllegalStateException
- if the context is already closed.PolyglotException
- if a guest language error occurred during execution.Value.getMetaQualifiedName()
,
Value.getMetaSimpleName()
,
Value.isMetaInstance(Object)
,
Value.getMetaObject()
public String getMetaQualifiedName()
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.
UnsupportedOperationException
- if and only if Value.isMetaObject()
returns
false
for the same value.PolyglotException
- if a guest language error occurred during execution.public String getMetaSimpleName()
string
.
Sample interpretations: The simple name of a Java class is the class name.
UnsupportedOperationException
- if and only if Value.isMetaObject()
returns
false
for the same value.PolyglotException
- if a guest language error occurred during execution.public boolean isMetaInstance(Object instance)
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
.
instance
- the instance object to check.UnsupportedOperationException
- if and only if Value.isMetaObject()
returns
false
for the same value.PolyglotException
- if a guest language error occurred during execution.public boolean hasArrayElements()
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()
.IllegalStateException
- if the context is already closed.PolyglotException
- if a guest language error occurred during execution.public Value getArrayElement(long index)
0
,
independent of the guest language. The given array index must be greater or equal to 0.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.public void setArrayElement(long index, Object value)
0
, independent
of the guest language. The array element value is subject to polyglot value mapping rules as
described in Context.asValue(Object)
.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.public boolean removeArrayElement(long index)
true
if the underlying array
element could be removed, otherwise false
.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.public long getArraySize()
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.public boolean hasMembers()
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)
.IllegalStateException
- if the context is already closed.PolyglotException
- if a guest language error occurred during execution.To check the existence of members.
,
To read members.
,
To write members.
,
To remove a member.
,
For a list of members.
public boolean hasMember(String identifier)
true
if such a member exists for a given identifier
. If the
value has no members
then Value.hasMember(String)
returns
false
.PolyglotException
- if a guest language error occurred during execution.NullPointerException
- if the identifier is null.public Value getMember(String identifier)
identifier
or null
if the member
does not exist.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.public Set<String> getMemberKeys()
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.IllegalStateException
- if the context is already closed
.PolyglotException
- if a guest language error occurred during execution.public void putMember(String identifier, Object value)
Context.asValue(Object)
.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.public boolean removeMember(String identifier)
true
if the member was
successfully removed, false
if such a member does not exist.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.public boolean canExecute()
true
if the value can be executed
.IllegalStateException
- if the underlying context was closed.Value.execute(Object...)
public Value execute(Object... arguments)
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)
.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.Value.executeVoid(Object...)
public void executeVoid(Object... arguments)
can
be executed. All arguments are subject to
polyglot value mapping rules as described in Context.asValue(Object)
.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.Value.execute(Object...)
public boolean canInstantiate()
true
if the value can be instantiated. This indicates that the
Value.newInstance(Object...)
can be used with this value. If a value is instantiable it is
often also a Value.isMetaObject()
, but this is not a requirement.Value.isMetaObject()
public Value newInstance(Object... arguments)
can
be instantiated. All arguments
are subject to polyglot value mapping rules as described in Context.asValue(Object)
.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.public boolean canInvokeMember(String identifier)
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.identifier
- the member identifierIllegalStateException
- if the context is already closed.PolyglotException
- if a guest language error occurred.For a list of members.
,
Value.invokeMember(String, Object...)
public Value invokeMember(String identifier, Object... arguments)
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.identifier
- the member identifier to invokearguments
- the invocation argumentsUnsupportedOperationException
- if this member cannot be invoked.PolyglotException
- if a guest language error occurred during invocation.NullPointerException
- if the arguments array is null.Value.canInvokeMember(String)
public boolean isString()
true
if this value represents a string.PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.public String asString()
String
value if this value is
a string. This method
returns null
if this value represents a null
value.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.public boolean fitsInInt()
PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.Value.asInt()
public int asInt()
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.public boolean isBoolean()
true
if this value represents a boolean value.PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.Value.asBoolean()
public boolean asBoolean()
boolean
representation of this value if it is boolean
.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.public boolean isNumber()
true
if this value represents a number
, else
false
. The number value may be accessed as byte
,
short
int
long
, float
or double
value.PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.public boolean fitsInLong()
PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.Value.asLong()
public long asLong()
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.public boolean fitsInDouble()
PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.Value.asDouble()
public double asDouble()
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.public boolean fitsInFloat()
PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.Value.asFloat()
public float asFloat()
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.public boolean fitsInByte()
PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.Value.asByte()
public byte asByte()
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.public boolean fitsInShort()
PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.Value.asShort()
public short asShort()
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.public boolean isNull()
true
if this value is a null
like.PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.public boolean isNativePointer()
true
if this value is a native pointer. The value of the pointer can be
accessed using Value.asNativePointer()
.PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.public long asNativePointer()
long
value.UnsupportedOperationException
- if the value is not a pointer.PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.public boolean isHostObject()
true
if the value originated form the host language Java. In such a case
the value can be accessed using Value.asHostObject()
.PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.public <T> T asHostObject()
UnsupportedOperationException
- if Value.isHostObject()
is false
.PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.public boolean isProxyObject()
true
if this value represents a Proxy
. The proxy instance can be
unboxed using Value.asProxyObject()
.PolyglotException
- if a guest language error occurred during execution.IllegalStateException
- if the underlying context was closed.public <T extends Proxy> T asProxyObject()
Proxy
. Proxies are not automatically boxed to
host objects
on host language call boundaries (Java methods).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.public <T> T as(Class<T> targetType) throws ClassCastException, IllegalStateException, PolyglotException
The following target types are supported and interpreted in the following order:
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.
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
.host object
.
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 the value has members
or array elements
. The returned map can be safely cast
to MapClassCastException
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){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 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:
null
then null
is returned.
host object
then the value is coerced to
host object value
.
string
then the value is coerced to String
or Character
.
boolean
then the value is coerced to
Boolean
.
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()
.
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
.
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
.
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
.
Value
instance is 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;
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);
targetType
- the target Java type to mapClassCastException
- 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.to map to generic type signatures.
public <T> T as(TypeLiteral<T> targetType)
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"); }
NullPointerException
- if the target type is null.Value.as(Class)
public String toString()
identity hash code
is used as string representation.public SourceSection getSourceLocation()
SourceSection
or null if unknownpublic boolean isDate()
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.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.Value.asDate()
public LocalDate asDate()
date
. The returned
date is either aware if the value has a timezone
otherwise it is naive.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.Value.isDate()
public boolean isTime()
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.IllegalStateException
- if the underlying context is already closed.Value.asTime()
public LocalTime asTime()
time
. The returned
time is either aware if the value has a timezone
otherwise it is naive.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.Value.isTime()
public boolean isInstant()
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
()
IllegalStateException
- if the underlying context is already closed.Value.isDate()
,
Value.isTime()
,
Value.isInstant()
,
Value.asInstant()
public Instant asInstant()
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));
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.Value.isDate()
,
Value.isTime()
,
Value.isTimeZone()
public boolean isTimeZone()
true
if this object represents a timezone, else false
. The
interpretation of timezone objects may vary:
Value.isDate()
and Value.isTime()
return true
, then the returned
date or time information is aware of this timezone.
Value.isDate()
and Value.isTime()
returns false
, then it represents
just timezone information.
fixed
zone
only. 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.
IllegalStateException
- if the underlying context is already closed.Value.asTimeZone()
,
Value.asInstant()
public ZoneId asTimeZone()
timezone
.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.Value.isTimeZone()
public boolean isDuration()
true
if this object represents a duration, else false
.IllegalStateException
- if the underlying context is already closed.Duration
,
Value.asDuration()
public Duration asDuration()
duration
.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.Value.isDuration()
public boolean isException()
true
if this object represents an exception, else false
.IllegalStateException
- if the underlying context is already closed.Value.throwException()
public RuntimeException throwException()
exception
.UnsupportedOperationException
- if the value is not an exception.IllegalStateException
- if the underlying context is already closed.Value.isException()
public Context getContext()
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.
public boolean equals(Object obj)
public int hashCode()
public static Value asValue(Object o)
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()
.o
- the object to convertIllegalStateException
- if no context is currently entered.Conversion rules.