Skip navigation links

HTML APIs via Java 1.7 API

The HTML/Java API is an alternative to Swing and JavaFX for creating applications with a graphical user interface.

See: Description

JSON for Java 
Package Description
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
Representation of the browser context.
Builder class to bootstrap your Java/HTML based application. See BrowserBuilder for description how to launch your application.
Implementation of BrowserBuilder that renders using JavaFX WebView and additional utilities to configure individual WebViews.
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.
Geolocation API 
Package Description
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
Control sound in your HTML for Java applications.
Testing and Headless API 
Package Description
Factories to create headless browser environment which is useful for testing.
Service Provider APIs (not commonly interesting) 
Package Description
Interfaces for integrators of various execution environments. Not really interesting for clients.
Service provider classes to build BrwsrCtx instances.
Service provider interfaces for those willing to provide their own way of obtaining proper geolocation.
Service Provider Interfaces for those who wish to integrate own technology with the HTML for Java API.
Entry point to the test compatibility kit.
Give your AudioClip real behavior!
Build Your Own Presenter! 
Package Description
Generic Browser presenter and its configuration.
Show a browser component.
The prototypical presenter based on textual protocol between JavaScript VM and Java VM.
Native WebKitPresenter for Linux and Mac OS X.

The HTML/Java API is an alternative to Swing and JavaFX for creating applications with a graphical user interface. It's major strengths is the intelligent combination of existing technologies.
With HTML/Java, the proven model used on servers for many years, has been ported to the client. Java is used for developing business and view logic, while HTML5, CSS and JavaScript are used to render the UI. 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 motivation for this project is the inability of Swing and JavaFX to keep up with the rapid development of browser based technologies, and the uncertain future of Swing and JavaFX. The logical solution is to simply use these technologies from Java instead of trying to build a whole own alternative stack. With Java/HTML we created a better and more powerful alternative, which is still small and easy to maintain.

Model View ViewModel Pattern

For this Java/HTML makes use of the Model View ViewModel (MVVM) pattern to separate the view from the logic of the application. This approach is different from Swing or JavaFX, as the Java code doesn't require any references to the widgets that are displayed in the view. The Java code instead exposes properties for the View to bind to, and functions that can be called in response to user interactions. This keeps the Java API small and simple to learn.

Supported Platforms

This architecture also makes it easy to port the technology to different platforms. Porting of HTML/Java is as easy as implementing Fn.Presenter interface and successfully passing the test compatibility kit. 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.

Getting started

The easiest way to get started is following the getting started tutorial. If you prefer commandline you can also use the Maven Archetypes. Just type:
$ mvn archetype:generate \
    -DarchetypeGroupId=com.dukescript.archetype \
    -DarchetypeArtifactId=knockout4j-archetype \ -DartifactId=test -Dversion=1.0-SNAPSHOT 
    -DarchetypeVersion=0.30 \ # or newer version, if available
and then you can:
$ cd test
$ mvn install
$ mvn -f client/pom.xml process-classes exec:exec

More Information

We tried to make our API Docs as useful as possible, so they contain lots of valuable information. So this should be your first stop when looking for information: Current development version

The DukeScript project contains a lot of information for Java/HTML developers. There's a Blog with the latest news and tips and tricks how to get the most out of these APIs and also an extensive getting started guide explaining all the concepts and walking you through code examples. For advanced users there's an in depth tutorial on the Knockout For Java API with many examples and tipps and tricks.

Try it

And finally, if you want to see this API in action, look no further, here's an example application running with the Bck2Brwsr VM directly in your browser.

New in version 1.7

New modules are provided since PR #23:

New in version 1.6.1

One model instance can be used in two views (PR #14). GC related behavior has been improved (PR #19). Safe and sanitized builder to create ScriptEngine-based execution environment (PR #15). Switching to knockout.js version 3.5.0 (PR #20).

New in version 1.6

Compiles on JDK11 while using Open JavaFX 11 when necessary. Computed properties can depend on other computed properties - PR #3. JavaScriptResource annotation has been made repeatable - PR #4. @Model annotation processor bugfix #621.

New in version 1.5.1

The project has been donated to Apache Foundation and the code is now hosted in the 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.

What's new in older versions?

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

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:
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 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.

Other Resources

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

Copyright © 2019 The Apache Software Foundation. All rights reserved.