Package com.teamdev.jxbrowser.js

Interface JsObject

All Known Subinterfaces:
JsArray, JsArrayBuffer, JsFunction, JsMap, JsPromise, JsSet
public interface JsObject
A JavaScript object.

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.

  • Method Summary

    Modifier and Type
    Method
    Description
    <T> T
    call(String methodName, Object... args)
    Executes the function with the given methodName and the args in the JavaScript object.
    void
    close()
    Closes this JavaScript object.
    Frame
    frame()
    Returns the Frame instance of this JavaScript object.
    boolean
    hasProperty(JsSymbol jsSymbol)
    Checks whether this JavaScript object or any of its prototypes has a property with the given jsSymbol key.
    boolean
    hasProperty(String name)
    Checks whether this JavaScript object or any of its prototypes has an enumerable property with the given name.
    List<String>
    ownPropertyNames()
    Returns an immutable list of the names of the properties of this JavaScript object, both enumerable and non-enumerable, excluding the properties from the prototype objects.
    List<JsSymbol>
    ownPropertySymbols()
    Returns an immutable list of the symbol properties of this JavaScript object, excluding the properties from the prototype objects.
    <T> Optional<T>
    property(JsSymbol jsSymbol)
    Returns an Optional describing the value of the JavaScript object's property with the given jsSymbol key or an empty Optional if there is no such property or its value is undefined.
    <T> Optional<T>
    property(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.
    List<String>
    propertyNames()
    Returns an immutable list of the names of the enumerable properties of this JavaScript object, including the properties from the prototype objects.
    boolean
    putProperty(JsSymbol jsSymbol, Object value)
    Creates a new property with the given jsSymbol key 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
    putProperty(String name, 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(JsSymbol jsSymbol)
    Removes a property with the given jsSymbol key in the JavaScript object and returns true if the property was successfully removed.
    boolean
    removeProperty(String name)
    Removes a property with the given name in the JavaScript object and returns true if the property was successfully removed.

  • Method Details

    • frame

      Frame frame()
      Returns the Frame instance of this JavaScript object.
      Since:
      7.6

    • propertyNames

      List<String> propertyNames()
      Returns an immutable list of the names of the enumerable properties of this JavaScript object, including the properties from the prototype objects.

      The list returned by this method contains the same values as would be enumerated by a for-in statement over this object in JavaScript.

      Returns:
      a list of the names of the properties of this JavaScript object or an empty list if the object does not have any properties
      Throws:
      ObjectClosedException - when the JavaScript object is already disposed or invalid

    • ownPropertyNames

      List<String> ownPropertyNames()
      Returns an immutable list of the names of the properties of this JavaScript object, both enumerable and non-enumerable, excluding the properties from the prototype objects.
      Returns:
      a list of the names of the own properties of this JavaScript object or an empty list if the object does not have any own properties
      Throws:
      ObjectClosedException - when the JavaScript object is already disposed or invalid

    • ownPropertySymbols

      List<JsSymbol> ownPropertySymbols()
      Returns an immutable list of the symbol properties of this JavaScript object, excluding the properties from the prototype objects.
      Returns:
      a list of the symbol properties of this JavaScript object or an empty list if the object does not have any properties
      Throws:
      ObjectClosedException - when the JavaScript object is already disposed or invalid
      Since:
      8.13.0

    • hasProperty

      boolean hasProperty(String name)
      Checks whether this JavaScript object or any of its prototypes has an enumerable property with the given name.
      Parameters:
      name - the name of the property
      Returns:
      true if object has property with the given name
      Throws:
      IllegalArgumentException - when name is empty or blank
      ObjectClosedException - when the JavaScript object is already disposed or invalid

    • hasProperty

      boolean hasProperty(JsSymbol jsSymbol)
      Checks whether this JavaScript object or any of its prototypes has a property with the given jsSymbol key.
      Parameters:
      jsSymbol - a symbol that represents the property key
      Returns:
      true if object has property with the given jsSymbol
      Throws:
      IllegalArgumentException - when jsSymbol is from a different web page or frame
      ObjectClosedException - when the JavaScript object or jsSymbol is already disposed or invalid
      Since:
      8.13.0

    • property

      <T> Optional<T> property(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.

      The type mapping rules are the following: 

       | JavaScript         | Java           |
 |--------------------|----------------|
 | Number             | Double         |
 | BigInt             | BigInteger     |
 | String             | String         |
 | Boolean            | Boolean        |
 | Symbol             | JsSymbol       |
 | 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.

      Type Parameters:
      T - the result type according to the type mapping rules
      Parameters:
      name - a string that represents the name of the property or function
      Returns:
      an Optional 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
      Throws:
      IllegalArgumentException - when name is empty or blank
      ObjectClosedException - when the JavaScript object is already disposed or invalid
      See Also:

    • property

      <T> Optional<T> property(JsSymbol jsSymbol)
      Returns an Optional describing the value of the JavaScript object's property with the given jsSymbol key or an empty Optional if there is no such property or its value is undefined.
      Type Parameters:
      T - the result type according to the type mapping rules
      Parameters:
      jsSymbol - a symbol that represents the property key
      Returns:
      an Optional describing the value of the JavaScript object's property with the given jsSymbol key. If the object does not have this property or the property value is null or undefined, the method returns an empty Optional
      Throws:
      IllegalArgumentException - when jsSymbol is from a different web page or frame
      ObjectClosedException - when the JavaScript object or jsSymbol is already disposed or invalid
      Since:
      8.13.0
      See Also:

    • putProperty

      boolean putProperty(String name, @Nullable 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.

      The type mapping rules are the following: 

      
 | Java               | JavaScript                    |
 |--------------------|-------------------------------|
 | Number             | Double                        |
 | BigInt             | BigInteger                    |
 | String             | String                        |
 | Boolean            | Boolean                       |
 | Symbol             | JsSymbol                      |
 | 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.

      Parameters:
      name - a string that represents the property name
      value - a new value associated with the property with the given name
      Returns:
      true when property was created or updated successfully
      Throws:
      IllegalArgumentException - when name is empty or blank
      IllegalArgumentException - when value is a JsObject from a different web page or frame
      ObjectClosedException - when the JavaScript object is already disposed or invalid

    • putProperty

      boolean putProperty(JsSymbol jsSymbol, @Nullable Object value)
      Creates a new property with the given jsSymbol key 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 properties with Symbol keys are not enumerable and are not returned in propertyNames().

      Parameters:
      jsSymbol - a symbol that represents the property key
      value - a new value associated with the property with the given jsSymbol
      Returns:
      true when property was created or updated successfully
      Throws:
      IllegalArgumentException - when name is empty or blank
      IllegalArgumentException - when value is a JsObject from a different web page or frame, or jsSymbol is from a different web page or frame
      ObjectClosedException - when the JavaScript object or jsSymbol is already disposed or invalid
      Since:
      8.13.0

    • removeProperty

      boolean removeProperty(String name)
      Removes a property with the given 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.
      Parameters:
      name - a string that represents the name of the property or function
      Returns:
      true if the property was successfully removed
      Throws:
      IllegalArgumentException - when name is empty or blank
      ObjectClosedException - when the JavaScript object is already disposed or invalid

    • removeProperty

      boolean removeProperty(JsSymbol jsSymbol)
      Removes a property with the given jsSymbol key 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.
      Parameters:
      jsSymbol - a symbol that represents the property key
      Returns:
      true if the property was successfully removed
      Throws:
      IllegalArgumentException - when jsSymbol is from a different web page or frame
      ObjectClosedException - when the JavaScript object or jsSymbol is already disposed or invalid
      Since:
      8.13.0

    • call

      <T> T call(String methodName, Object... args)
      Executes the function with the given 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                        |
 | BigInt             | BigInteger                    |
 | String             | String                        |
 | Boolean            | Boolean                       |
 | Symbol             | JsSymbol                      |
 | 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         |
 | BigInt             | BigInteger     |
 | String             | String         |
 | Boolean            | Boolean        |
 | Symbol             | JsSymbol       |
 | 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.

      Type Parameters:
      T - the result of the JavaScript function execution
      Parameters:
      methodName - a string that represents a function name
      args - the input arguments that will be converted according to the mapping rules
      Throws:
      JsException - when an error occurs during function execution
      IllegalArgumentException - when methodName is empty or blank
      IllegalArgumentException - when args contains an unsupported type
      ObjectClosedException - when the JavaScript object is already disposed or invalid

    • close

      void close()
      Closes this JavaScript object.

      This method makes the underlying v8 object eligible for garbage collection, but does not guarantee that it will be destroyed. That is, if the object is still used by the JavaScript code on the web page (there are references to this object), you can obtain it again through the JavaScript API.

      Use this method to make unused JavaScript objects garbage collectable. This is especially useful when you transfer a large number of objects through the JavaScript-Java bridge, or when those are objects that can hold a large amount of memory: JsArrayBuffer, JsArray, JsSet, JsMap, etc.

      All JavaScript objects are closed automatically when you perform a navigation, reload the web page, or close the browser.

      Since:
      7.32