Faster Java to JavaScript with better interop, exception handling, resource preloading

Stefano De Rossi
Jul 24, 2018 · 4 min read

Today we are excited to announce a new stable release of CheerpJ, our solution to convert existing, unmodified Java applications to HTML5/JavaScript from bytecode. CheerpJ 1.1 can be downloaded here.

CheerpJ 1.1 introduces several major new features, performance improvements on many different areas, as well as fixing quite a few bugs which started emerging in the last months due to an increased adoption (thanks to all bug reporters!).

Let’s unpack CheerpJ 1.1 new features:

  • Support for the parallel preloading of resources that can be known before runtime. When an application is converted with CheerpJ, the list of required resources can be known after a first test run. This list can be used to instruct CheerpJ to preload those resources in parallel at application start. This typically leads to a major improvement in startup time, and has been very useful in production for several users of CheerpJ.
  • New JavaScript to Java interoperability API based on standard promises, enabling the use of the async/await operators, and with better support for method resolution and overloading;
  • Support for promise chaining and exception handling when calling Java from JavaScript
  • Dramatically improved code generation for low-level drawing routines. This translates to a large performance improvement for applications drawing many FPS (e.g. video playback, videogames)

We are also pleased to report that the commercial adoption of CheerpJ has been increasing steadily over the last six months, and we will soon be able to announce some exciting partnership on which we have been working on recently.

Java-JavaScript interoperability, promises and exception handling

CheerpJ 1.1 features a new API based on standard promises to call Java methods (converted by CheerpJ) from HTML5/JavaScript.

The standard API available in CheerpJ 1.0 (based oncjCall and cjNew) is convenient, and is based under the hood on Java reflection to resolve methods. When planning to invoke many Java methods from JavaScript, or when performance is important, this can lead to an unacceptable overhead. This is particularly relevant when using CheerpJ to convert a Java library.

The new APIs available in CheerpJ 1.1 — named cjResolveCall and cjResolveNew — are optimised to rely on reflection only once, and avoid any overhead in further calls to the same method.

This is an example of the new APIs:

cjResolveCall supports both instance and static methods of classes. The third parameter (for both APIs) is an array of Java types and it is only required for overloaded method names.

cjResolveCall and cjResolveNew are asynchronous, like most of CheerpJ's APIs. To get the actual result you can either use .then() or — better — the async / await functionality of JavaScript. For example:

The returned value is an opaque handle to the desired method (or constructor), which can now be called an arbitrary number of times very efficiently.

Alternatively resolvedMethod can also be used directly as a function, for example:

resolvedMethod(arg1, arg2, arg3);

Please note that this convenient form can unfortunately only be used on the main thread, not on Workers. For more information see WebWorker API.

Starting from CheerpJ 1.1, these APIs return standard JavaScript promises. While before only the basic then(...) pattern could be used, now the full suite of Promise capabilities are available including chaining, async / await and exception handling using catch. For example:

The catch callback will receive the error message (i.e. the detail message if the Java Exception). This is also supported when using the WebWorker API to run Java code in a separate worker.

Optimising startup time through resource preloading

CheerpJ (similarly to the JVM) cannot predict which runtime resources will be required by an arbitrary application. Resources are therefore loaded on demand, one after the other, depending on the requirements of the application at run time.

To reduce download and startup time by taking advantage of parallel preloading — particularly useful in production — CheerpJ 1.1 allows to pre-specify a list of resources (CheerpJ runtime modules) to be loaded at startup.

This list of resources is to be specified manually when starting the CheerpJ environment in an HTML page. CheerpJ 1.1 also provides a simple profiling tool to automatically record and output a list of used resources during the execution of an application.

By combining the use of this profiler together with the preloader, one can highly optimise the initial download and startup time of a converted application. Taking advantage of this is a simple 2-step process:

  1. Run the application normally using CheerpJ. After the application is loaded, open the JavaScript console of the browser (e.g. Ctrl+Shift+I on many browsers), and type:


The result will look like this:


The JavaScript console may enclose the string between quotes ("), which you should ignore. See here for more information.

2. Modify the CheerpJ integration to enable preloading. You will only need to change the cheerpjInit call, to pass the preloadResources option. For example:


See here for more information. When preloading is enabled CheerpJ will be able to download multiple resources in parallel with the execution of the program. This will greatly improve loading time.

Changelog — CheerpJ 1.1

  • Introduced parallel preloading of resources that are known to be needed before starting the application (useful in production);
  • New, faster API for JavaScript to Java interoperability based on standard promises (allowing async/await)
  • Exception handling when calling Java from JavaScript
  • Improved support for reflection
  • Improved code generation, particularly for low-level graphical routines
  • Improved HTTP/HTTPs connections
  • Support for time zones
  • Improved startup time
  • Support for custom cursors


Cheerp 1.1 is available to download for Linux, Windows and macOS. To get started with CheerpJ, please visit the main documentation page.

Want to know more?

For more information on CheerpJ, check out our website at Follow us on twitter (@leaningtech), visit our website, or drop us a line on Gitter!


Leaning Technologies' Blog - everything Cheerp, CheerpJ, compile-to-JavaScript and compile-to-WebAssembly

Thanks to Alessandro Pignotti

Stefano De Rossi

Written by


Leaning Technologies' Blog - everything Cheerp, CheerpJ, compile-to-JavaScript and compile-to-WebAssembly

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade