Annotation Interface JS

@Retention(RUNTIME) @Target(METHOD) public @interface JS
Replaces the body of a Java method with JavaScript code. The JavaScript code is specified by the value() of this annotation. A method with this annotation can be made native, since its Java body is not used at run-time (this is the convention). Examples: 
@JS("console.log('User message: '.concat(message));")
public static native void reportToUser(String message);

@JS("return obj.hashCode();")
public static native Integer hashCode(Object obj);
The data types in JavaScript are different from the data types in Java, so this annotation defines a mapping between the Java and the JavaScript data types. The mapping is 1:1, meaning that each Java data type maps to exactly one JavaScript, and vice versa. This mapping determines how Java arguments are converted to JavaScript, and how JavaScript return values are converted back to Java values. The following Java and JavaScript type pairs correspond to each other:
  • Java null value and the JavaScript null value.
  • Java JSUndefined and JavaScript Undefined.
  • Java JSBoolean and JavaScript Boolean.
  • Java JSNumber and JavaScript Number.
  • Java JSBigInt and JavaScript BigInt.
  • Java JSString and JavaScript String.
  • Java JSSymbol and JavaScript Symbol.
  • Java JSObject and JavaScript Object.
  • Any other Java class and the corresponding JavaScript Proxy for that class.
The Java class JSValue is the common supertype of JSUndefined, JSBoolean, JSNumber, JSBigInt, JSString, JSSymbol and JSObject. It defined conversion methods such as JSValue.asInt() and JSValue.asString(), which allow converting certain JSValue objects to corresponding Java objects (for example, JSNumber can be converted to most Java numeric types). Other Java classes are transformed to JavaScript Proxy objects, which expose JavaScript keys that correspond to methods of the underlying Java object. Such an object behaves as if it were a regular JavaScript object, but its internal behavior is defined by the corresponding Java code.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    JS.Code
    A snippet of JavaScript code that must be included in the image.
    static @interface 
    JS.Coerce
    When this annotation is used together with the JS annotation, the arguments and return values of the respective method undergo implicit Java-to-JavaScript and JavaScript-to-Java conversions.
    static @interface 
    JS.Export
    Denotes that the annotated Java class should be exported from the VM class.
    static @interface 
    JS.Import
    Denotes that the annotated class represents a JavaScript class from the global scope.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    DEFAULT_ARGUMENTS
    The default arguments string is an empty string used to denote the default value of the args member.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    value
    JavaScript statements that form the body of this method.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String[]
    args
    If specified, overrides parameter names seen by the JavaScript code.

  • Field Details

    • DEFAULT_ARGUMENTS

      static final String DEFAULT_ARGUMENTS
      The default arguments string is an empty string used to denote the default value of the args member. It is an error for the user of the JS annotation to specify an empty-string name of an argument, hence this special value is used to denote the defaults.
      See Also:

  • Element Details

    • value

      String value
      JavaScript statements that form the body of this method. When returning a value, the return keyword must not be omitted. The JavaScript code can use parameters using their names specified in args(). In non-static methods, it can also access the receiver using this keyword.
      Returns:
      a snippet of JavaScript source code

    • args

      String[] args
      If specified, overrides parameter names seen by the JavaScript code. By default, Web Image will try to infer the original argument names in the method header from the method bytecode. If that is not possible, the argument names must be specified here. The target method must be compiled with javac -parameters in order for the argument names to be available in the bytecode. The this parameter cannot be renamed.
      Returns:
      the new parameter names (their count must match the number of parameters), or DEFAULT_ARGUMENTS if the original names should be used (this is the default)
      Default:
      {""}