TeaVM for OpenJDK: JEP Draft 2

jpackage allows packaging Java applications for several platforms. This proposal adds a new platform: JavaScript.

Summary

Add a JavaScript type option to jpackage. This will convert bytecode from the provided classes into JavaScript, and generate the required HTML to invoke the specified main method when opened in a web browser. These files will be bundled into a WAR file for easy deployment.

Goals

Enabling JVM languages to build client-side web applications
Allow easy generation of JavaScript from JVM bytecode
Allow easy deployment and execution of generated JavaScript in web browsers
Allow easy deployment of the generated JavaScript in all web server environments
- Java web application container (like Tomcat)
- Static file web servers
- Static file web hosting services

Non-Goals

Allowing execution of JavaScript server-side. (Java already has numerous options for executing bytecode server-side.)

Motivation

Java was once used to create client-side web applications via applets that could be launched by visiting a web page. Applets could draw on an area of the screen (like HTML5 Canvas) or manipulate the page DOM to create dynamic front-end applications (like JS single-page apps).

However, as evident in JEP 398 (https://openjdk.java.net/jeps/398), applets are no longer feasible due to the actions of browser vendors. While browsers have lost the ability to execute Java bytecode or invoke methods from the Java class libraries, they do have mature engines for executing a different sort of code (JavaScript) and an extensive list of useful APIs. By converting class files to JavaScript, and providing mechanisms to invoke browser APIs, Java can again be used to create in-browser applications. TeaVM has demonstrated that this is feasible and has numerous benefits:

Provides a strongly-typed language for client-side web development
Provides a wealth of IDEs, build, and testing tools for client-side web development
Allows teams with Java experience to produce apps with familiar technology
Allows sharing of POJO and business logic classes, simplifying development
Allows options for porting applet- and JNLP-based systems to present-day browsers

Details

An additional jpackage option for type will be added: js

jpackage will use a JavaScript AOT compiler (TeaVM) to convert the Java code to JavaScript, with the main class compiled to a JavaScript method called 'main()'.

jpackage bundles application code, runtime, and resources into a platform-specific format. For this new JavaScript type, the layout will be either a ZIP file or a standard WAR file. The ZIP format will contain the files ready to be extracted to a static file webserver or HTML hosting service. Generated WARs will have the required structure to be deployable in a Java web application container.

WAR layout

HelloApp.war
- index.html (Main application page, loads classes.js and invokes main())
- teavm
  - classes.js (Class files, templates, and resources compiled to JavaScript)
- css
  - (CSS files from application)
- META-INF
  - MANIFEST.MF
- WEB-INF
  - web.xml

ZIP Layout

HelloApp.zip
- index.html (Main application page, loads classes.js and invokes main())
- teavm
  - classes.js (Class files, templates, and resources compiled to JavaScript)
- css
  - (CSS files from application)

Processing

Conversion of the input JAR files to the classes.js file will be done by TeaVM. It will

Convert provided class files to JavaScript
Expose the specified main method as main()
Provide implementation of selected core Java classes that function in a browser environment
Bundle resources into the generated JavaScript
Include images, css, and web.xml into the generated package, if provided
Provide default index.html if omitted
Provide default web.xml if omitted and WAR format specified
Optionally minify the generated JavaScript

js-specific options

--minify: Perform a minification pass after generating JavaScript, renaming classes and methods to short, generated names to reduce download sizes and provide some obfuscation.
--debug: Enable generation of source maps.
--debug-full: Enable generation of source maps and bundled source files.
--optimization: Choose simple, advanced, or full. (TBD: provide descriptions from TeaVM)
--timezone-support: Enables timezone support, at the cost of increased application size
--locale-list: Add extra locales via a list, at the cost of increased application size. (TBD: Specify locale list format)

Caveats

Certain Java classes are not feasible to implement in a browser setting. Socket, for example, is not useful in a browser setting since JavaScript cannot open arbitrary socket connections. Code using unavailable classes will fail during packaging time with warnings about the missing classes.

Testing

Many tests can build on existing TeaVM test suites. (TBD: Is a browser used in current JDK testing? Will that be a new requirement?)

More TBD

Dependencies

The jpackage js type will require TeaVM binaries to be present.

Implementation options:

Download TeaVM on-demand and cache it.
- Look for TeaVM in local repositories for popular build tools like Maven and Gradle
- If not found locally, download TeaVM binaries from a central repository and store in the cache folder
- Invoke TeaVM from the local repository or cache
Require that TeaVM binaries be installed locally
- Provide the path to TeaVM binaries on the command line
Bundle TeaVM
- Challenging due to incompatible licenses (Apache v2 vs. GPL v2 with CPE)
- Probably unnecessary given the options above. Other jpackage options require pre-installed tools, this will be no different.