public interface JsObject
Allows accessing the object's properties and calling its functions. The JavaScript object is
alive while the web page where the object was created is loaded. When the web page is unloaded,
all the JavaScript objects will be automatically disposed. Access to the already disposed
JavaScript object will lead to the IllegalStateException
.
Modifier and Type | Method and Description |
---|---|
<T> T |
call(java.lang.String methodName,
java.lang.Object... args)
Executes the function with the given
methodName and the args in the
JavaScript object. |
Frame |
frame()
Returns the
Frame instance of this JavaScript object. |
boolean |
hasProperty(java.lang.String name)
Checks whether the JavaScript object has a property or function with the given
name . |
java.util.List<java.lang.String> |
ownPropertyNames()
Returns an immutable list of the names of the properties of this JavaScript object, excluding
properties from the prototype objects.
|
<T> java.util.Optional<T> |
property(java.lang.String name)
Returns an
Optional describing the value of the JavaScript object's property
with the given name or an empty Optional if there is no such property
or its value is undefined. |
java.util.List<java.lang.String> |
propertyNames()
Returns an immutable list of the names of the properties of this JavaScript object, including
properties from the prototype objects.
|
boolean |
putProperty(java.lang.String name,
java.lang.Object value)
Creates a new property with the given
name or updates the existing one in the
current JavaScript object and returns true if the property with the given
name was created or updated successfully. |
boolean |
removeProperty(java.lang.String name)
Removes a property with the given
name in the JavaScript object and returns true if the property was successfully removed. |
Frame frame()
Frame
instance of this JavaScript object.java.util.List<java.lang.String> propertyNames()
ObjectClosedException
- when the JavaScript object is already disposed or invalidjava.util.List<java.lang.String> ownPropertyNames()
ObjectClosedException
- when the JavaScript object is already disposed or invalidboolean hasProperty(java.lang.String name)
name
.name
- a string that represents the name of the property or functiontrue
if object has property with the given name
java.lang.IllegalArgumentException
- when name
is empty or blankObjectClosedException
- when the JavaScript object is already disposed or invalid<T> java.util.Optional<T> property(java.lang.String name)
Optional
describing the value of the JavaScript object's property
with the given name
or an empty Optional
if there is no such property
or its value is undefined.
The type mapping rules are the following:
| JavaScript | Java | |--------------------|----------------| | Number | Double | | String | String | | Boolean | Boolean | | null and undefined | null | | Node | JsObject, Node | | ArrayBuffer | JsArrayBuffer | | Array | JsArray | | Set | JsSet | | Map | JsMap | | Object | JsObject | | Proxy Object | Object |
Proxy objects are mapped to the corresponding injected Java object.
T
- the result type according to the type mapping rulesname
- a string that represents the name of the property or functionOptional
describing the value of the JavaScript object's property with
the given name
. If the object does not have this property or the property
value is null
or undefined, the method returns an empty Optional
java.lang.IllegalArgumentException
- when name
is empty or blankObjectClosedException
- when the JavaScript object is already disposed or invalidhasProperty(String)
boolean putProperty(java.lang.String name, @Nullable java.lang.Object value)
name
or updates the existing one in the
current JavaScript object and returns true
if the property with the given
name
was created or updated successfully.
The type mapping rules are the following:
| Java | JavaScript |
|--------------------|-------------------------------|
| Number | Double |
| String | String |
| Boolean | Boolean |
| null | null |
| JsObject | Object |
| Node | Node |
| List<?> | Array or Proxy Object |
| Set<?> | Set or Proxy Object |
| Map<?,?> | Map or Proxy Object |
| byte[] | ArrayBuffer |
| Object | Proxy Object |
If you pass a non-primitive Java object to JavaScript, it will be converted into a
"proxy" JavaScript object. Method and property calls to this object will be delegated to
the Java object. For security reasons, JavaScript can access only those methods and fields
of the injected Java object that are explicitly marked as accessible either using the
JsAccessible
annotation or via the JsAccessibleTypes
class.
Java collections that are not made accessible to JavaScript using the JsAccessible
annotation or via the JsAccessibleTypes
class are converted to JavaScript
collections. The content of the converted collection is a deep copy of the Java collection.
Modifications of the converted collection in JavaScript do not affect the collection in Java.
Java collections that are made accessible to JavaScript using the JsAccessible
annotation or via the JsAccessibleTypes
class are wrapped into a JavaScript proxy
object. Such proxy objects can be used to modify the collection in Java.
name
- a string that represents the property namevalue
- a new value associated with the property with the given name
true
when property was created or updated successfullyjava.lang.IllegalArgumentException
- when name
is empty or blankjava.lang.IllegalArgumentException
- when value
is a JsObject
from a different
web page or frameObjectClosedException
- when the JavaScript object is already disposed or invalidboolean removeProperty(java.lang.String name)
name
in the JavaScript object and returns true
if the property was successfully removed. Once you remove the property, it will not be
available in the current JavaScript object anymore.name
- a string that represents the name of the property or functiontrue
if the property was successfully removedjava.lang.IllegalArgumentException
- when name
is empty or blankObjectClosedException
- when the JavaScript object is already disposed or invalid<T> T call(java.lang.String methodName, java.lang.Object... args)
methodName
and the args
in the
JavaScript object. This method blocks current thread execution until the function finishes
its execution. If the function raises an exception, then JsException
with an error
message that describes the reason of the exception will be thrown. Same error message will be
printed in JavaScript Console.
The type mapping rules are the following:
| Java | JavaScript |
|--------------------|-------------------------------|
| Number | Double |
| String | String |
| Boolean | Boolean |
| null | null |
| JsObject | Object |
| Node | Node |
| List<?> | Array or Proxy Object |
| Set<?> | Set or Proxy Object |
| Map<?,?> | Map or Proxy Object |
| byte[] | ArrayBuffer |
| Object | Proxy Object |
If you pass a non-primitive Java object to JavaScript, it will be converted into a
"proxy" JavaScript object. Method and property calls to this object will be delegated to
the Java object. For security reasons, JavaScript can access only those methods and fields
of the injected Java object that are explicitly marked as accessible either using the
JsAccessible
annotation or via the JsAccessibleTypes
class.
Java collections that are not made accessible to JavaScript using the JsAccessible
annotation or via the JsAccessibleTypes
class are converted to JavaScript
collections. The content of the converted collection is a deep copy of the Java collection.
Modifications of the converted collection in JavaScript do not affect the collection in Java.
Java collections that are made accessible to JavaScript using the JsAccessible
annotation or via the JsAccessibleTypes
class are wrapped into a JavaScript proxy
object. Such proxy objects can be used to modify the collection in Java.
The type mapping rules are the following:
| JavaScript | Java | |--------------------|----------------| | Number | Double | | String | String | | Boolean | Boolean | | null and undefined | null | | Node | JsObject, Node | | ArrayBuffer | JsArrayBuffer | | Array | JsArray | | Set | JsSet | | Map | JsMap | | Object | JsObject | | Proxy Object | Object |
Proxy objects are mapped to the corresponding injected Java object.
T
- the result of the JavaScript function executionmethodName
- a string that represents a function nameargs
- the input arguments that will be converted according to the mapping rulesJsException
- when an error occurs during function executionjava.lang.IllegalArgumentException
- when methodName
is empty or blankjava.lang.IllegalArgumentException
- when args
contains an unsupported typeObjectClosedException
- when the JavaScript object is already disposed or invalid