Skip navigation links

HTML APIs via Java 1.5.1 API

The HTML/Java API provides basic building blocks as well as advanced high level concepts to make communication between JavaScript and Java as smooth as possible.

See: Description

JSON for Java 
Package Description
net.java.html.json
This API allows you to write your application logic in Java and present it using modern HTML rendering technologies like Knockout and communicate with a server via REST or WebSockets.
Core Client APIs 
Package Description
net.java.html
Representation of the browser context.
net.java.html.boot
Builder class to bootstrap your Java/HTML based application.
net.java.html.boot.fx
Implementation of BrowserBuilder that renders using JavaFX WebView and additional utilities to configure individual WebViews.
net.java.html.js
Essential support for those who write native methods communicating directly with JavaScript.
Geolocation API 
Package Description
net.java.html.geo
HTML Geo API for Java provides annotation based way of obtaining geolocation information from a browser or any other device capable of providing it.
Sound API 
Package Description
net.java.html.sound
Control sound in your HTML for Java applications.
Testing and Headless API 
Package Description
net.java.html.boot.script
Factories to create headless browser environment which is useful for testing.
Service Provider APIs (not commonly interesting) 
Package Description
org.netbeans.html.boot.spi
Interfaces for integrators of various execution environments.
org.netbeans.html.context.spi
Service provider classes to build BrwsrCtx instances.
org.netbeans.html.geo.spi
Service provider interfaces for those willing to provide their own way of obtaining proper geolocation.
org.netbeans.html.json.spi
Service Provider Interfaces for those who wish to integrate own technology with the HTML for Java API.
org.netbeans.html.json.tck
Entry point to the test compatibility kit.
org.netbeans.html.sound.spi
Give your AudioClip real behavior!

The HTML/Java API provides basic building blocks as well as advanced high level concepts to make communication between JavaScript and Java as smooth as possible.

Every browser widget Java API offers ways for communication between Java and JavaScript running in such widget. However, each of them is unique - e.g. one writes different code when communicating with JavaFX WebView, different one when communicating with Android WebView yet another one when talking to iOS WebView.

The goal of HTML/Java API is to unify this communication. By providing simple and highly portable basic building blocks one can create sophisticated APIs (like UI bindings, charts, maps, canvas, or SnapSVG that can be embedded into Swing or JavaFX applications, executed headlessly on a server or executed anywhere HTML/Java API was ported.

Various ports of this rendering pipeline were built including support for pure "webkit desktop rendring Android WebView and iOS WebView developed by DukeScript project.

This technology has also been adopted by some Java bytecode to JavaScript transpilers - for example TeaVM or Bck2Brwsr VM - as such you can also run the same Java application in a pluginless browser.

Porting of HTML/Java rendering pipeline is as easy as implementing Fn.Presenter interface and successfully passing the test compatibility kit.

Highlights

The HTML/Java API lets you easily mix Java and JavaScript:

Get the best of both worlds by combining the industry stability of Java and richness of JavaScript ecosystem when it comes to UI and rendering frameworks.

The HTML/Java API offers you unified access to full featured Java runtime (like real HotSpot VM) and very lightweight rendering technology (so it can potentially fit Bck2Brwsr and definitely to various types of phones - e.g. Android and iOS). What can be more lightweight (from a browser perspective) than HTML!? Speed up your development with JavaFX's WebView component to display the HTML, get browser inspect features, CSS navigation and IDE integration.

New in version 1.5.1

The project has been donated to Apache Foundation and the code is now hosted in the incubator repository along other Apache incubating projects. Contribute to the project by forking its GitHub repository.

Using Android JSON parsing library as it is Apache licensed - bug #89. It is acceptable to read properties of a model when computing a property. Regular subclassing of Proto.Type is possible. Bugfix #99 - better garbage collector related behavior of ko4j instances thanks to introduction of Technology.ToJavaScript. Mentioning knockout.js license in the ko4j artifact - bug #98. Simplifying dependencies of org.netbeans.html.json.tck - bug #111

Bug fix for multiple observers on a single model object. Better GC behavior specified in TCK and used in Knockout for Java implementation. Removing dependency on Java collection classes implementations. Adding Models.asList(T...) factory method to a create simple list implementation. Simplifying KnockoutTCK to avoid usage of URI, etc.

New features in version 1.4

Both values null and undefined are treated as null. Better behavior under multi-threaded load. Workaround for garbage collector behavior of modern JavaFX WebView implementations (JDK8 u112 and newer). JavaFX Presenter can show popup window. Development has switched to Git repository thanks to conversion by Emilian Bold. Better support for obfuscation of knockout module (bug 270013).

Improvements in version 1.3

Model classes can have per-instance private data. Model classes can generate builder-like construction methods if builder prefix is specified. Property.mutable() can be false to define a non-mutable (almost constant) property. That in case of Knockout bindings means: the property is represented by a plain value rather than an observable in the JavaScript object. The JavaFX presenter can be executed in headless mode - just specify -Dfxpresenter.headless=true when launching its virtual machine and no window will be shown. This is particularly useful for testing. Configure your surefire or failsafe plugins like:
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>2.13</version>
  <configuration>
      <systemPropertyVariables>
          <fxpresenter.headless>true</fxpresenter.headless>
      </systemPropertyVariables>
  </configuration>
</plugin>
OSGi headers are now enterprise OSGi ready. Switched to minified version 3.4.0 of knockout.js. Better support for recursive @Model definitions. New module org.netbeans.html:xhr4j provides implementation of Transfer with technology identifier xhr4j - this module can be used to workaround limitations of CORS by handling the OnReceive connections in Java.

What's new in older versions?

Click the link to view even more historic changes...

What's Been Improved in Version 1.2.3?

One can control HTTP request headers when connecting to server using the OnReceive annotation. It is possible to have writable computed properties. There is an easy way to enable Firebug in the JavaFX based Web View - just run with -Dfirebug.lite=true as this video demonstrates. Bugfix of issues 250503, 252987.

What's New in Version 1.1?

The content of a context can be selected by registering implementations under specific technology identifiers and requesting them during construction of the context. org.netbeans.html:ko4j module's implementation offers ko4j, xhr and websocket identifiers for its registered services (e.g. Technology, Transfer and WSTransfer). org.netbeans.html:ko-ws-tyrus module registers its Java based JSON and WebSocket implementations under the name tyrus.

A particular DOM subtree that a knockout.js model gets applied to can be selected by using Models.applyBindings(m, id) with an id of an HTML element. There is new Model.targetId() attribute which controls behavior of the generated applyBindings method. If specified and non-empty, then the generated method will call Models.applyBindings(java.lang.Object,java.lang.String) with this and the provided target id. If specified, but left empty, then the generated method calls Models.applyBindings(java.lang.Object). If unspecified, the method will not be generated at all (a change with respect to older versions). However one can still use Models.applyBindings(java.lang.Object) or Models.applyBindings(java.lang.Object,java.lang.String) to perform the association of any model with the page element.

Memory model when using Knockout bindings has been improved (required additions of two new methods: PropertyBinding.weak() and FunctionBinding.weak()) and now the Java models can garbage collect, when no longer used. Library writers that use JavaScriptBody annotation can also control garbage collection behavior of method arguments by setting keepAlive=false attribute.

What's New in Version 1.0?

Array properties are now mutable from the knockout.js point of view (required one SPI change). The page lookup mechanism can use locale to load localized a page with appropriate suffix. All SPI were moved under the NetBeans namespace - e.g. org.netbeans.html.boot.spi, org.netbeans.html.context.spi, org.netbeans.html.json.spi, org.netbeans.html.sound.spi, and also org.netbeans.html.json.tck. Methods annotated with JavaScriptBody annotation and without fallback Java code now throw IllegalStateException with a message suggesting to switch to proper browser context to prevent endless debugging when one forgets to do so.

What's New in Version 0.9?

System can run in Felix OSGi container (originally only Equinox). Derived properties now deeply check changes in other model classes they depend on and recompute their values accordingly. Knockout.js library has been updated to version 3.2.0.

What's New in 0.8.x Versions?

Setters or array properties on classes generated by Model annotation can be accessed from any thread. AudioEnvironment can be registered into BrwsrCtx. There is a method to parse a JSON array and convert it into model classes. Improved behavior of enum values in knockout bindings.

Few bugfixes for better portability. New API for headless execution on top of Nashorn - does not run knockout for Java fully yet (reported as JDK-8046013), however even in current state it is quite useful for testing of Java/JavaScript interactions.

FXBrowsers has been extended with new helper methods to make it easier to use HTML+Java API in existing JavaFX applications. The annotation processor is made more robust with respect to errors in callback syntax of JavaScriptBody body parameter. Javadoc of BrwsrCtx.execute(java.lang.Runnable) method has been improved based on a failure of its usability study. There can be additional parameters to methods annotated by OnReceive that allows one to pass state when a JSON call is made and use it when it finishes. The mechanism of discovery of sibling HTML page has been extended to work on systems that don't support Class.getProtectionDomain().

The first argument of method annotated by OnReceive annotation has to be the associated model class.

OnReceive annotation now accepts List of data values as second argument (previously required an array).

What's New in 0.7.x Versions?

JavaScriptBody annotation has new attribute JavaScriptBody.wait4js() which allows asynchronous execution. Libraries using JavaScriptBody are urged to use this new attribute as much as possible, as it can speed up execution in certain environments.

Use BrwsrCtx.execute(java.lang.Runnable) in multi-threaded environment to execute your code on the browser thread. See example using Java timer.

Interesting Entry Points

Learn how to animate an HTML page from Java without referencing single HTML element from the Java code.

Use JSON to communicate with REST based server API.

Use WebSockets and JSON.

Call JavaScript methods from Java and vice versa, via JavaScriptBody.

Getting Started

This HTML/Java API is used by NetBeans Platform as well as other project. The smoothest way to get started is to follow the getting started tutorial. In case one wants to stick with a Maven and command line, one can follow these instructions, make sure at least JDK7 is your installed Java and type:
$ mvn archetype:generate \
 -DarchetypeGroupId=com.dukescript.archetype \
 -DarchetypeArtifactId=knockout4j-archetype \
 -DarchetypeVersion=0.16 # or newer version, if available
        
Answer few questions (for example choose myfirstbrwsrpage as artifactId) and then you can:
$ cd myfirstbrwsrpage
$ mvn install
$ mvn -f client/pom.xml process-classes exec:exec
        
In a few seconds (or minutes if Maven decides to download the whole Internet of dependencies) you should see a sample Hello World application. Immediatelly you can be productive without any redeploys - even more productive than with plain JavaScript!

The application is rendered in a JavaFX web view component (that of course requires your JDK to come with JavaFX; JDK7 and JDK8 from Oracle contain everything that is needed). The generated application is built around one Java source (uses the Model annotation to auto-generate another Data.java class during compilation) and one HTML file (uses the Knockout syntax to data-bind the HTML elements to the generated Data model):

$ ls client/src/main/java/**/DataModel.java
$ ls client/src/main/webapp/pages/index.html
        
That is all you need to get started. Play with the sources, modify them and enjoy Html for Java!

IDE Support

This API is part of NetBeans.org project and as such it works naturally with the NetBeans IDE. On the other hand, the API is using nothing NetBeans specific, it builds on standard Java6 APIs and as such it shall work fine in any IDE.

A lot of work is done by annotation processors that generate various boiler plate code during compilation. This is a standard part of Java since JDK6, but for example Eclipse is known not to deal with processors well and developers using it need to be careful. IntelliJ users hasn't reported any issues and of course, NetBeans IDE support for processors is outstanding.

When using JavaScriptBody annotation, it is useful to do a bit of post processing of classes. There is a Maven plugin for that. NetBeans IDE will invoke it when doing a build. Other IDEs may need some hint to do so. Anyway: If one does not see all (generated) sources or is getting LinkageErrors when executing the application, switch to command line and do clean build from there:

$ mvn clean install

If that succeeds, your IDE of choice will hopefully pick the generated sources up and present the result of the build properly. If not, download NetBeans, you will be pleasantly surprised - for example with our excellent Java/JavaScript debugging support.

Deploy Your Application

It is not goal of this documentation to list all possible ways to package and deploy applications which use this API. However it is important for new comers to see the benefits of using the HTML for Java API and as such let's list at least few bundling options, known to work at the time of writing this documentation.

First of all, this is a client technology. You write client applications with it which may, but need not connect to a server. You don't need Tomcat or WebLogic to deploy HTML for Java applications.

The sample project generated by org.apidesign.html knockout4j-archetype is configured to use JavaFX as the rendering technology. This setup is primarily suitable for development - it needs no special packaging, starts quickly and allows you to use classical HotSpot VM debuggers. A final artifact from the build is also a ZIP file which you can use and distribute to your users. Good for desktop applications.

All the HTML for Java libraries are packaged as OSGi bundles and as such they can easily be run in NetBeans as well as in Eclipse. As a result one can use OSGi and have a common module system for both platforms. In addition to that one can render using HTML and have a common UI in both platforms. In such case your application would be packaged as a set of OSGi bundles. Read more...

There is more and more attempts to execute Java bytecode in a browser, without any special Java plugin installed. The HTML for Java is carefully designed to produce lightweight, well performing applications even on such restricted environments. It uses no reflection calls and that allows to statically pre-compile the applications into JavaScript. One of such environments is called Bck2Brwsr, another TeaVM. Both support the JavaScriptBody annotation. Read more or play a minesweeper game packaged for your browser (of course written in Java):

Now when we have seen that the HTML for Java applications can run on any modern browser, we can ask whether they can also fit into a phone!? Yes, they can and especially to phones that can execute Java code already! Just by changing your packaging you can create an APK file and deploy it to your Android phone. Read more or install Fair Minesweeper for Android...

In case you'd like your application to reach out to second biggest group of smartphone users, don't despair: It seems the set of devices that can execute HTML for Java applications has been extended to iPads and iPhones. Get the details here and play Fair Minesweeper on iOS!

Convinced it makes sense to use HTML for Java APIs for writing applications that are written once, displayed anywhere? Or do you have an environment which is not supported? In such case you can bring HTML for Java to your environment yourself. Just implement your own Fn.Presenter!

Other Resources

Duke and HTML5. Together at last! The javadoc for latest and previous versions is also available online:
Skip navigation links

Copyright © 2018 NetBeans. All rights reserved.