Interoperability

JavaScript to Java

Load JAR files and use their classes, objects and arrays from JavaScript or TypeScript, with async and await.

Java to JavaScript

Implement Java native methods in JavaScript, so Java code can call JavaScript functions and libraries.

Java to the browser

Files, the network, the application’s display, the clipboard and external commands all go through the browser.

What JavaScript can do

• Load only the Java standard library, or the standard library and your JAR files
• Create objects with await new, and call static and instance methods
• Read and write fields and array elements directly
• Test Java types with instanceof, and catch Java exceptions in JavaScript

Native methods

Name an async function after the Java method, Java_<class>_<method>, and pass it to CheerpJ when it starts. It receives the library object and the Java object it was called on.

async function Java_Page_setTitle(lib, self, title) {
	document.title = title;
}
await cheerpjInit({ natives: { Java_Page_setTitle } });

Native libraries

System.loadLibrary loads a JavaScript module from java.library.path, and the native methods it exports can be shared across the whole application.

export default {
	async Java_Example_alert(lib, message) {
		window.alert(message);
	},
};

Into the application

• The upload button on every Java window’s title bar puts the user’s file in /files/uploads/, with no code
• cheerpOSAddStringFile passes text or binary data from JavaScript, such as a file from an <input type="file">
• Library mode can copy files from /app/ to /files/

Out of the application

• Files that Java saves in /files/downloads/ are downloaded to the user’s computer automatically
• cjFileBlob reads any file as a Blob, to download, display or upload it from JavaScript
• A native method lets Java code decide when to start a download

HTTP and HTTPS

Java’s HTTP connections are made with the browser’s fetch. Same-origin policy and CORS apply, and HTTP requests are upgraded to HTTPS on HTTPS pages.

TCP and UDP sockets

Browsers do not give web pages raw sockets. CheerpJ provides them through Tailscale, configured when CheerpJ starts with an auth key or a login callback, and a self-hosted Headscale control server if you use one.

Custom networking backends

Enterprise deployments can connect CheerpJ to a custom networking backend, for example to go through their own proxies or to use other transports such as WebSockets.

Tags run in place

CheerpJ finds the page’s <applet>, <object> and <embed> tags and runs each applet where its tag is, on Java 8.

Applet parameters

The applet reads its parameters from the page as before. appletParamFilter can rewrite them when CheerpJ starts, for example to change a server URL.

Calling the page

AppletContext.showDocument opens URLs, and javascript: URLs call the page’s JavaScript functions. Native methods cover anything else.

OpenJDK’s native code

OpenJDK’s own JNI code is compiled unmodified from OpenJDK to WebAssembly, so the Java class library behaves as it does on the desktop.

The application’s native code

Native methods run when they are compiled to WebAssembly or written in JavaScript. Pre-built platform binaries, such as Windows DLLs, cannot run in a browser.