This doesn’t seem like something that should be the job of jpackage. The
jpackage tool is currently used for producing platform-specific packages or
installers targeted at end-users that include native launchers and a JRE.
Web-based applications are an entirely different beast. This seems like
more of a job for a Maven or Gradle plugin.
Regards,
Scott
On Apr 24, 2021, at 5:59 PM, Andrew Oliver <93q...@gmail.com> wrote:
Below is a Java Enhancement Proposal for your consideration to add
JavaScript to jpackage as a new target platform. I would appreciate
feedback on the proposal contents. I am also interested in learning
about
the process, specifically what approvals are required prior to start of
implementation, should sufficient consensus be reached.
( To view this proposal as a web page, please visit:
https://frequal.com/TeaVM/openjdk/jdk-list-draft1.html )
Thank you!
-Andrew Oliver
Title: Add JavaScript platform to jpackage
Author: Andrew Oliver
Created: 2021/04/24
Type: Feature
State: Draft
Exposure: Open
Component: tools/jpackage
Scope: JDK
Discussion: core-libs-dev@openjdk.java.net
Template: 1.0
Summary
-------
jpackage already allows packaging Java applications for several
platforms.
This proposal adds a new platform: JavaScript.
This effort will enable jpackage to 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](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](https://teavm.org) 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 tools, 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)
Basic usage: Non-modular applications
-------------------------------------
Command-line usage is similar to jpackage today, except you use the
`--type
js`. For example, if you have your application JARs in a folder called
`lib` and the JAR with the declared `main()` method is `main.jar`, you
could use this command:
```
$ jpackage --type js --name myapp --input lib --main-jar main.jar
```
This will produce `myapp.war` in the current directory. This is a
standard
WAR file ready for deployment in any web application container (like
Tomcat). When myapp/index.html is opened in a browser, the code in main()
will be executed, in-browser. A typical Hello World main() method like
```
public static void main(String args\[\]) {
System.out.println("Hello, Browser!");
}
```
will print the message on the browser developer console.
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 in 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
1. `--minify`: Perform a minification pass after generating JavaScript,
renaming classes and methods to short, generated names to reduce download
sizes and provide some obfuscation.
2. `--debug`: Enable generation of source maps.
3. `--debug-full`: Enable generation of source maps and bundled source
files.
4. `--optimization`: Choose simple, advanced, or full.
* simple: Perform only basic optimizations
* advanced: Perform more optimizations. Recommended for production.
* full: Perform aggressive optimizations. Increases compilation
time.
5. `--timezone-support`: Enables timezone support, at the cost of
increased application size
6. `--locale-list`: Add extra locales via a list, at the cost of
increased
application size. Format: comma-separated list of locale IDs like
"en\_US,
ru\_RU"
### Unsupported options for the JavaScript type
These options are unsupported for `--type js`
* `--file-associations`: Not yet meaningful for a web-based app, though
it may be in the future once PWAs support file types: [
https://github.com/WICG/file-handling](https://github.com/WICG/file-handling)
* `--app-version, --copyright, --description, --license-file,
--vendor`:
jpackage will only support --name initially. Users can customize
index.html
(and the rest of the application) to show branding and metadata as
desired.
* `--java-options`: Not yet supported, use `--arguments` instead.
Caveats
-------
Certain Java classes are not feasible to implement in a browser setting.
Socket, for example, is not useful in a browser since JavaScript cannot
open arbitrary socket connections. Code using unavailable classes will
fail
during packaging time with warnings about the missing classes.
Testing
-------
Since TeaVM is Java-based, tests will be able to run on any platform.
Testing will focus on the new jpackage code and added functionality.
Tests
will confirm that when valid parameters are provided, that output is
generated with the right name and in the right folder. Contents of the
generated ZIP and WAR files will be checked for the presence of expected
files. Testing generated files in a browser will be done manually.
A thorough test of TeaVM itself is out of scope for the jpackage testing.
This is in line with jpackage testing for other platforms, in which the
external packaging tool (like Wix on Windows) isn't exhaustively tested.
Dependencies
------------
The jpackage `js` type will require TeaVM binaries to be present.
Implementation options:
* Download TeaVM on-demand and cache it. (This is the likely option.)
* Look for TeaVM in local repositories for popular build tools like
Maven and Gradle
* If not found locally, download TeaVM binaries from the read-only
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.
High-Level Design
-----------------
A new bundler will be added to the jpackage Java source code.
It will first ensure that TeaVM binaries (JAR files) are available
locally,
as described in the section above.
The new bundler will use TeaVM's TeaVMRunner ([
https://github.com/konsoletyper/teavm/blob/master/tools/cli/src/main/java/org/teavm/cli/TeaVMRunner.java](https://github.com/konsoletyper/teavm/blob/master/tools/cli/src/main/java/org/teavm/cli/TeaVMRunner.java)
),
which conveniently accepts options similar to jpackage itself.
TeaVMRunner
will do the heavy lifting of converting the application JAR files and
resources into `classes.js`.
The bundler will provide additional files required to make a web
application, including an `index.html` to launch the `main()` method. The
bundler will create the final archive (ZIP or WAR) using Java's
ZipOutputStream. For the WAR format, the bundler will also add `web.xml`
and `MANIFEST.MF` if not present to create a deployable, standard WAR
file.
