Essential support for those who write native methods communicating directly with JavaScript.
Mix your Java and JavaScript code seamlessly - perform calls from Java to JavaScript and back with as much freedom as JavaScript gives you and as much type safety you can get from Java. Execute your code in a headless testing environment or in a JavaFX WebView. When done, deploy to real browsers.

### Simple Meaning of World

The whole support is build around @JavaScriptBody annotation. Use it to create parametrised JavaScript snippet easily accessible from Java:

    {@code @}{@link net.java.html.js.JavaScriptBody}(args = {"x", "y"}, body = "return x + y;")
    private static native int meaning(int x, int y);

The above defines method meaning which sums two JavaScript objects together (being invoked inside of a JavaScript interpreter). The meaning method now becomes a properly typed Java surface to your JavaScript code which can be directly called from the rest of your Java code:

    public static void main(String... args) {
      assert 42 == meaning(40, 2) : "Meaning of World should be 42!";
    }

Real code tip: real classes using this technique are available online: JsMethods and Bodies.

Editing hint: one can see the list of arguments of the meaning is now duplicated - it is once specified in Java, and once inside of the {@link net.java.html.js.JavaScriptBody} array of `args`. This is necessary to keep the names of arguments accessible during runtime. However don't despair - there is a code completion for the value of `args` attribute! Just type the Java signature first and then press Ctrl+Space and the right parameter names will be inserted for you.

### Including JavaScript Libraries

Large amount of JavaScript code is easier to be delivered in whole files rather than {@link net.java.html.js.JavaScriptBody small code snippets} - that is also possible thanks to {@link net.java.html.js.JavaScriptResource} annotation. Imagine file `mul.js` with following content:

    function mul(x, y) { return x * y; }

Place the file next to your class and reference it with {@link net.java.html.js.JavaScriptResource the annotation}:

    {@code @}{@link net.java.html.js.JavaScriptResource}("mul.js") class Mul {

      {@code @}{@link net.java.html.js.JavaScriptBody}(args = { "x", "y" }, body = "return mul(x, y);")
      public static native int multiply(int x, int y);

      public static void main(String... args) {
        assert 42 == multiply(6, 7) : "Meaning of World should be 42!";
      }
    }

All the Java methods annotated {@link net.java.html.js.JavaScriptBody} can now reference everything that is in the `mul.js` file - e.g. the body of the `multiply` method can reference the function `mul` and use it.

Real code tip: this is the way the knockout.js library is included in its ko4j library.

### Callback to Java

Often JavaScript code needs to call back into the Java classes. For example when a button in a browser is pressed and your code would like to invoke a runnable to handle such situation:

    {@code @}{@link net.java.html.js.JavaScriptBody}(args = {"id", "r"}, {@link net.java.html.js.JavaScriptBody#javacall() javacall} = true, body = "\n" +
    "       document.getElementById(id).onclick = function() {\n" +
    "        r.{@code @}java.lang.Runnable::run()();\n" +
    "       };\n" +
    "    ")
    public static native void onClick(String id, Runnable r);

As can be seen, there is a special syntax (starting with @) to properly identify the right Java method to call on a Java object passed into the JavaScript interpreter. The syntax starts with a fully qualified name of the class, followed by :: and name of the method including signature of its parameters. In case of runnable, this is just () as the method has no parameters, but the signature can be more complicated. For example in case of following method

    static int compare(int i1, String s1, int i2, String s2)

it would be (ILjava/lang/String;ILjava/lang/String;) (btw. the return type is not included in the signature). The actual parameters then follows. The JavaScript call to such compare method would then look like:

    {@code @}the.pkg.Clazz::compare(ILjava/lang/String;ILjava/lang/String;)(1, 'One', 2, 'Two');

This syntax gives enough flexibility, helps to properly select one of overloaded methods and follows the tradition of previous attempts to provide JavaScript to Java calling conventions.

Please note that to turn the special Java callback syntax on, one needs to set the {@link net.java.html.js.JavaScriptBody#javacall()} attribute to true. The callback syntax consists of following parts:

    [instance.]@classname::methodname(signature)(arguments)

- instance - must be present when calling an instance method and must be absent when calling a static method
- classname - fully qualified name of the class in which the method is declared
- signature - internal JVM method signature (as specified at JNI type Signatures) without the trailing signature of the method return type
- arguments - the actual values to pass to the called Java method

Here is the JNI type signatures table one can use to convert Java parameters to JVM's internal letter based representation:

Type Signature | Java Type
Z | boolean
B | byte
C | char
S | short
I | int
J | long
F | float
D | double
L fully-qualified-class ; | fully-qualified-class
[ type | type[]

Editing hint: The callback syntax may seem complicated at first, however there is an associated annotation processor that checks the syntax and verifies the referenced class and method with the requested signature exist. If it does not, the compilation fails offering correct alternatives. Thus don't despair seeing the syntax, make sure you get the fully qualified name of the callback class right. You'll get warning and help if there is a typo in the specified signature then - during compilation of your code.

### Overloaded Methods

Specifying the actual callback signature is important in case of overloaded methods. Imagine a class:

    package x.y.z;
    class Handler {
      int pulse() {
        return 1;
      }
      int pulse(int howMuch) {
        return howMuch;
      }
      int pulse(long evenMore) {
        return (int) (5 + evenMore);
      }
    }

you then need to choose in {@link net.java.html.js.JavaScriptBody} the appropriate method to call:

    {@code @}{@link net.java.html.js.JavaScriptBody}(args = { "h" }, javacall = true, // you want to process the @ syntax
      body = "return h.@x.y.z.Handler::pulse()() +" + // the call to no argument method
        "h.@x.y.z.Handler::pulse(I)(10) +" + // the call to method with integer argument
        "h.@x.y.z.Handler::pulse(J)(10);" // the call to method with long argument
      )
      static native void threePulsesFromJavaScript(Handler h);
      static {
        assert 26 == threePulsesFromJavaScript(new Handler());
      }

To avoid ambiguity, the specification of the correct signature is required on every call. However, to simplify the development, there is an annotation processor to verify the signature really refers to an existing method.

### Arrays by Copy

It is possible to exchange arrays between Java and JavaScript. Some implementations can pass arrays by reference, however in some systems this is hard to achieve. To choose the least common denominator, the TCK for behavior of {@link net.java.html.js.JavaScriptBody} requires the arrays to be always transfered by a copy. As such following code:

    {@code @}{@link net.java.html.js.JavaScriptBody}(args = {"arr"}, body = "arr[0] = null;")
    private static native void uselessModify(String[] arr);
    public static void main(String... args) {
      String[] hello = { "Hello", "World!" };
      uselessModify(arr);
      System.out.println(arr[0] + " " + arr[1]);
    }

will still print Hello World! in spite the JavaScript code sets the 0-th array element to `null`. Because the array is passed as a copy, such assignment has no effect on the Java array.

In case one needs to modify an array in a JavaScript and use its values in Java, one has to return the array back as a return value:

    {@code @}{@link net.java.html.js.JavaScriptBody}(args = {"arr"}, body = "arr[0] = 'Ahoy'; return arr;")
    private static native Object[] usefulModify(String[] arr);
    public static void main(String... args) {
      String[] hello = { "Hello", "World!" };
      Object[] ret = usefulModify(arr);
      System.out.println(ret[0] + " " + ret[1]);
    }

now the program prints Ahoy World! as the modified array is returned back and converted (by a copy) into a Java `Object[]` (but of course the `ret != hello`). Usually the copy based passing of arrays works OK. It is however good to keep it in mind to avoid unwanted surprises.

### Instance Reference to JavaScript Object

When writing wrappers around existing JavaScript libraries, it may be useful to hold a reference to some JavaScript object from a Java instance and use it later.

    class WrapperAroundJsObj {
      private final Object js;

      WrapperAroundJsObj() {
        js = initValue();
      }

      public void set(int v) {
        setValue(js, v);
      }

      {@link net.java.html.js.JavaScriptBody @JavaScriptBody}(args = {}, body = "return { value : 0 };")
      private static native Object initValue();

      {@link net.java.html.js.JavaScriptBody @JavaScriptBody}(
        args = { "js", "v" }, body = "js.value = v;", wait4js = false
      )
      private static native void setValue(Object js, int v);
    }

The type of the Java reference is {@link java.lang.Object}. From a Java perspective it has no additional methods or fields, however its properties can be manipulated from JavaScript. Send the object back to JavaScript by passing it as a parameter of some method (like the `setValue` one) and perform necessary JavaScript calls or changes on it.

### undefined === null

JavaScript recognizes two empty values: `null` and `undefined`. Java has just `null`. For purposes of simplicity and easier inter-operability, `undefined` values returned from {@link net.java.html.js.JavaScriptBody @JavaScriptBody} annotated methods are converted to `null`. In the following example both methods return `null`:

      {@link net.java.html.js.JavaScriptBody @JavaScriptBody}(
        args = {}, body = "var empty = {}; return empty.x;"
      )
      private static native Object returnUndefined();
      {@link net.java.html.js.JavaScriptBody @JavaScriptBody}(
        args = {}, body = "var empty = {}; empty.x = null; return empty.x;"
      )
      private static native Object returnNull();
    }

This is the behavior since version 1.4.

### Post Process Classes

Classes with {@link net.java.html.js.JavaScriptBody} annotated methods need to be post processed before they can be used - e.g. their `native` body needs to be generated to call into JavaScript (btw. the call is performed via {@link org.netbeans.html.boot.spi.Fn}). There are three ways such a post processing can be achieved.

#### Compile time

The Compile time is the preferred method of post-processing that most of the Html Java APIs are using. Just include following plugin configuration into your `pom.xml` and your classes will be ready for execution as soon as process-classes Maven phase is over:

    <plugin>
        <groupId>org.netbeans.html</groupId>
        <artifactId>html4j-maven-plugin</artifactId>
        <version>${net.java.html.version}</version>
        <executions>
            <execution>
                <id>js-classes</id>
                <goals>
                    <goal>process-js-annotations</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

This plugin works in orchestration with annotation processor associated with {@link net.java.html.js.JavaScriptBody} and {@link net.java.html.js.JavaScriptResource} - the processor creates list of files that need post-processing. The Maven plugin reads these files, processes classes mentioned in them and modifies (and deletes at the end) the files to not include classes already processed.

#### Instrumentation Agent

Instrumentation Agent can perform the post processing in runtime using JDK's {@link java.lang.instrument.ClassFileTransformer instrumentation} abilities. The JAR artifact of org.netbeans.html:net.java.html.boot contains an `Agent-Class` and `Premain-Class` attributes in its manifest. As such one can launch the Java virtual machine with

    $ java -javaagent:jarpath=net.java.html.boot-x.y.jar

and the runtime will take care of processing bytecode of classes before they are loaded into the virtual machine. Since version 1.8.2 this agent also changes retention of {@link net.java.html.js.JavaScriptBody} and {@link net.java.html.js.JavaScriptResource} annotations to {@link java.lang.annotation.RetentionPolicy#RUNTIME}. As such technologies that need access to these annotations during runtime can do so by using the `-javaagent` JVM switch.

#### Special classloading

There is a special implementation of dynamic classloader. When booting your application with {@link net.java.html.boot.BrowserBuilder} there is a 3rd option of processing the classes. If there are some classes not yet processed (remember the files listing them generated by the annotation processor), the {@link net.java.html.boot.BrowserBuilder#showAndWait() launching method} will create a special classloader to that does the processing before loading the bytecode into the virtual machine.

The options are rich, however to avoid any troubles (as the runtime processing needs to also include `asm-5.0.jar` on application classpath), it is recommended to perform the compile time processing.

### Getting Started

There are many ways to start developing Html for Java application. However to be sure one chooses the most recent setup, it is recommended to switch to good old command line and use a Maven archetype associated with every version of this project. Just type:

    $ mvn archetype:generate \
     -DarchetypeGroupId=org.apidesign.html \
     -DarchetypeArtifactId=knockout4j-archetype \
     -DarchetypeVersion=x.y

Answer few questions (for example choose myfirstbrwsrpage as artifactId) and then you can:

    $ cd myfirstbrwsrpage
    $ mvn process-classes exec:java

In a few seconds (or minutes if Maven decides to download the whole Internet of dependencies) you should see a sample Hello World application. It is basically composed from one Java and one HTML file:

    $ ls src/main/java/**/DataModel.java
    $ ls src/main/webapp/pages/index.html

Play with them, modify them and enjoy Html for Java!

### Mixed Java/JavaScript Debugging

The following video shows how easy it is to use NetBeans 8.0, JDK8 to debug an application that intermixes Java and JavaScript calls. One can put breakpoints into Java part, as well as JavaScript source code, inspect Java as well as JavaScript variables and switch between these two languages without any restrictions.