CJ3 docs (#19)

Co-authored-by: Alex Bates <[email protected]>
leaningtech · Oct 12, 2023 · 217ce48 · 217ce48
1 parent de3ed3f
commit 217ce48
Show file tree

Hide file tree

Showing 24 changed files with 1,289 additions and 7 deletions.
diff --git a/lychee.toml b/lychee.toml
@@ -8,4 +8,13 @@ remap = [ "https://labs.leaningtech.com http://127.0.0.1:4321" ]
 # Check links inside `<code>` and `<pre>` blocks
 include_verbatim = true
 
-exclude = [ '.*(twitter|github|linkedin)\.com.*', 'http://127\.0\.0\.1:(8000|8080).*', '.*rpm\.leaningtech\.com.*', '.*mydomain\.com.*', '.*microsoft\.com.*', 'file://.*' ]
+exclude = [
+	'.*(twitter|github|linkedin)\.com.*',
+	'http://127\.0\.0\.1:(8000|8080).*',
+	'.*rpm\.leaningtech\.com.*',
+	'.*mydomain\.com.*',
+	'.*microsoft\.com.*',
+	'file://.*',
+	'chrome://.*',
+	'wss?://*'
+]
diff --git a/public/cheerpj3/examples/swingset3-template.zip b/public/cheerpj3/examples/swingset3-template.zip
diff --git a/src/content/docs/cheerpj2/03-getting-started/01-Java-applet.mdx b/src/content/docs/cheerpj2/03-getting-started/01-Java-applet.mdx
@@ -21,7 +21,7 @@ CheerpJ can run Java applets in the browser seamlessly. This page will help you
 
 ### 1. Create a basic HTML file
 
-```html title="index.html" {6-9, 12-20}
+```html title="index.html" {6-9,12-19}
 <!doctype html>
 <html lang="en">
 	<head>

diff --git a/src/content/docs/cheerpj3/00-faq.md b/src/content/docs/cheerpj3/00-faq.md
@@ -0,0 +1,55 @@
+---
+title: FAQ
+---
+
+## What is CheerpJ?
+
+CheerpJ is a solution for running unmodified Java client applications into browser-based HTML5/JavaScript web applications. CheerpJ consists of a full Java runtime environment in JavaScript, and of a on-the-fly compiler for dynamic class generation, to be deployed alongside the application.
+
+## What parts of the Java SE runtime are supported?
+
+The CheerpJ runtime environment is a full Java SE runtime in JavaScript. Differently from other technologies which provide a partial re-implementation written manually in JavaScript, we opted to replace the entire OpenJDK Java SE runtime to JavaScript and WebAssembly. The CheerpJ runtime is constituted of both JavaScript files and .jar archives. All CheerpJ runtime components are dynamically downloaded on demand by the application to minimise total download size. The CheerpJ runtime library is hosted by us on a dedicated CDN-backed domain, and we invite users to link to it in order to take advantage of caching and cross-application resource sharing.
+
+## Can I self-host the CheerpJ runtime?
+
+Please [contact us](https://cheerpj.com/contact/) to discuss self-hosting CheerpJ and its runtime on your infrastructure.
+
+## Can I use CheerpJ to run my legacy Java application in the browser? I have no longer access to the source code.
+
+Yes, you can run any Java SE application with CheerpJ without touching the source code. You only need all the .jar archives of your application.
+
+## Can I use Java libraries and integrate them in my HTML5 application using CheerpJ?
+
+Yes. Java methods can be exposed to JavaScript with an interface compatible with async/await for convenience.
+
+## Can I call JavaScript libraries or web APIs from Java?
+
+Yes, CheerpJ allows you to interoperate with any JavaScript or browser API. Java native methods implemented in JavaScript are supported.
+
+## Does CheerpJ support reflection?
+
+Yes.
+
+## Does CheerpJ support dynamic class generation?
+
+Yes.
+
+## When I run CheerpJ I see 404/403 errors in the browser console. What's going on?
+
+Ignore those errors. CheerpJ provides a filesystem implementation on top of HTTP. In this context it is absolutely ok for some files to be missing. CheerpJ will correctly interpret 404 errors as a file not found condition.
+
+## My application compiled with CheerpJ does not work and I just see the "CheerpJ runtime ready" on the top of the screen. What's going on?
+
+Many first time users get stuck at this point. The most common issues are:
+
+- Opening the HTML page directly from disk: The URL in the browser should always start with http:// or https://, if it starts with file:// CheerpJ will not work. You need to use a local web server during testing.
+- Forgetting to add "/app/" prefix to the JAR files used in Web page. CheerpJ implements a virtual filesystem with multiple mount points, the "/app/" prefix is required.
+- More in general, you can use the "Network tab" of the developer tools in the browser to check if the JAR is being correctly downloaded. If the JAR is never downloaded, or a 404 error is returned, something is wrong with the JAR path. If you don't see anything in the "Network tab", please reload the page while keeping the developer tools open.
+
+## Can I play Old School RuneScape using CheerpJ or the CheerpJ Applet Runner extension?
+
+Not yet. The main problem is that RuneScape requires low level network connections primitives (sockets) which are not provided by browsers at this time due to security concerns. In the future we might provide a paid add-on to the CheerpJ Applet Runner extension to support this use case via tunneling.
+
+## What is the status of CheerpJ?
+
+CheerpJ is actively developed by [Leaning Technologies Ltd](https://leaningtech.com), a British-Dutch company focused on compile-to-JavaScript and compile-to-WebAssembly solutions.
diff --git a/src/content/docs/cheerpj3/01-changelog.md b/src/content/docs/cheerpj3/01-changelog.md
@@ -0,0 +1,42 @@
+---
+title: Changelog
+---
+
+version 3.0 - September 22nd, 2023:
+
+```
+
+Focus on performance, particularly on startup time
+* Multiple fixes on the Cheerp compiler to better optimize JNI code
+* Multiple experiments on the JIT to better interact with V8 tiering
+```
+
+version 3.0 - September 15th, 2023:
+
+```
+Work on CJ3 Library mode, with a focus on performance and Java <-> JS type conversions
+* Optimized away context switching overhead on user native calls
+* Support many more type conversion between JS numbers/integers/booleans and Java primitive types
+* Support conversion between JS numbers and Java boxed types (i.e. java.lang.Integer)
+* JIT optimizations
+* Optimization of the core class loading code path
+```
+
+version 3.0 - September 8th, 2023:
+
+```
+JNLP support and performance work
+* Significant speed up of System.arrayCopy
+* JIT optimizations
+```
+
+version 3.0 - September 1st, 2023:
+
+```
+Focus on networking
+* Integrated Tailscale support for low level TCP/UDP traffic, same code we use for WebVM/CheerpX
+* Custom HTTP/HTTPS handlers are now enabled by default unless Tailscale is used. The handlers provide http/https support in common cases.
+* Optimized exception handling
+* Optimized code rendering
+* Multiple JIT optimizations
+```
diff --git a/src/content/docs/cheerpj3/02-migrating-from-cheerpj2.md b/src/content/docs/cheerpj3/02-migrating-from-cheerpj2.md
@@ -0,0 +1,58 @@
+---
+title: Migration from CheerpJ 2
+---
+
+CheerpJ 3 is a complete reimplementation of CheerpJ 2, and as such it is not fully backwards compatible. This page lists the API differences between the two versions.
+
+## `cheerpjify.py` removed
+
+No downloads are provided with CheerpJ 3.
+
+- AOT optimization: CheerpJ 3 uses a JIT compiler only, and as such it does not require any pre-processing of the jar files, like conversion to `.jar.js`.
+- `--natives`: JNI function implementations should be passed to `cheerpjInit` using the `natives` option. See the [JNI guide] for more information.
+
+## `cheerpjInit` and `cheerpjRunMain` are now asynchronous
+
+- The `cheerpjInit` function now returns a `Promise` that resolves when the initialization is complete.
+- The `cheerpjRunMain` function now returns a `Promise` that resolves when the jar has been loaded.
+
+## `cheerpjRunJarWithClasspath` removed
+
+Use [`cheerpjRunMain`] instead.
+
+## `cjNew` and `cjCall` replaced with CJ3Library API
+
+`cjNew` and `cjCall` have been removed in favour of [`cheerpjRunLibrary`].
+
+```js
+// CheerpJ 2
+cheerpjInit();
+cheerpjRunJar("/app/library.jar");
+let obj = await cjNew("com.library.MyClass");
+await cjCall(obj, "myMethod");
+
+// CheerpJ 3
+await cheerpjInit();
+const lib = await cheerpjRunLibrary("/app/library.jar");
+const MyClass = await lib.com.library.MyClass;
+const obj = await new MyClass();
+await obj.myMethod();
+```
+
+## `com.leaningtech.handlers` HTTP handler no longer needed
+
+Previously, CheerpJ 2 required a special Java property to be set in order for HTTP(S) requests to work. This is no longer needed.
+
+## WebWorker API not yet implemented
+
+This is a work-in-progress.
+
+## `cheerpj-dom.jar` removed
+
+Calling JavaScript functions from Java is now done using the `natives` option of `cheerpjInit`. See the [JNI guide] for more information.
+
+If you used the `com.leaningtech.client` package extensively, check out the [CJDom library](https://github.com/reportmill/CJDom) (not maintained by Leaning Technologies).
+
+[`cheerpjRunLibrary`]: /cheerpj3/reference/cheerpjRunLibrary
+[`cheerpjRunMain`]: /cheerpj3/reference/cheerpjRunMain
+[JNI guide]: /cheerpj3/guides/Implementing-Java-native-methods-in-JavaScript
diff --git a/src/content/docs/cheerpj3/10-getting-started/00-Java-app.md b/src/content/docs/cheerpj3/10-getting-started/00-Java-app.md
@@ -0,0 +1,84 @@
+---
+title: Run a Java application
+---
+
+CheerpJ can run a Java application in the browser with little to no modifications. This page will help you getting started with CheerpJ and running your first Java application in the browser.
+
+Java source code is not needed to use CheerpJ. If you are building your own application you should already have its `.jar` file(s).
+
+**To get started you will need:**
+
+- Your Java application file(s). You can also use this [TextDemo.jar](https://docs.oracle.com/javase/tutorialJWS/samples/uiswing/TextDemoProject/TextDemo.jar) sample.
+- An HTML file where your Java app will be wrapped
+- A simple HTTP server to test your webpage locally
+
+## 1. Create a project directory
+
+Let's start by creating a project folder where all your files will be. Please copy your java and future HTML files here.
+
+```shell
+
+mkdir directory_name
+
+```
+
+## 2. Create a basic HTML file
+
+Let's create a basic HTML file like the following example. Please notice the CheerpJ runtime environment has been integrated and initialized. In this example we are assuming your HTML file and your `.jar` files are under the project directory you just created.
+
+```html title="index.html" {6, 9-13}
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>CheerpJ test</title>
+		<script src="https://cjrtnc.leaningtech.com/3_20230819_174/cj3loader.js"></script>
+	</head>
+	<body>
+		<script>
+			(async function () {
+				await cheerpjInit();
+				cheerpjCreateDisplay(800, 600);
+				await cheerpjRunJar("/app/my_application_archive.jar");
+			})();
+		</script>
+	</body>
+</html>
+```
+
+Alternatively, if your application is not designed to be executed with the command `java -jar` you can replace `cheerpjRunJar()` for `cheerpjRunMain()` and pass your qualified class name as an argument. For example:
+
+```js
+cheerpjRunMain(
+	"com.application.MyClassName",
+	"/app/my_application_archive.jar:/app/my_dependency_archive.jar",
+);
+```
+
+## 3. Host your page
+
+You can now serve this web page on a simple HTTP server, such as the http-server utility.
+
+```shell
+npm install http-server
+http-server -p 8080
+```
+
+> To test CheerpJ you must use a web server. Opening the `.html` page directly from the disk (for example, by double-clicking on it) is not supported.
+
+## What's going on?
+
+- CheerpJ loader is included from our cloud runtime as
+  `<script src="https://cjrtnc.leaningtech.com/2.3/loader.js"></script>`.
+- CheerpJ runtime environment is initialized by `cheerpjInit()`.
+- `cheerpjCreateDisplay()` creates a graphical environment to contain all Java windows
+- `cheerpjRunMain()` executes the `main` method of `ChangeThisToYourClassName`. The second parameter is a `:` separated list of `.jar` files where application classes can be found (the classpath).
+- The `/app/` is a virtual file system mount point that reference the root of the web server this page is loaded from.
+
+## The result
+
+You will see the CheerpJ display on your browser with some loading messages before showing your application running. Depending on your application and the optimizations applied, this could take just a few seconds.
+
+## Further reading
+
+- [Runtime API reference](/cheerpj3/reference)
diff --git a/src/content/docs/cheerpj3/10-getting-started/01-Java-applet.mdx b/src/content/docs/cheerpj3/10-getting-started/01-Java-applet.mdx
@@ -0,0 +1,97 @@
+---
+title: Run a Java applet
+---
+
+import LinkButton from "../../../../components/LinkButton.astro";
+
+CheerpJ can run Java applets in the browser seamlessly. This page will help you getting started with CheerpJ for Java applets.
+
+**There are two different ways to run a Java Applet in the browser:**
+
+- [Running your own Java applet](/cheerpj3/getting-started/Java-applet#running-your-own-applet) using the CheerpJ runtime environment and the `<cheerpj-applet>` tag in your own webpage.
+- [Running a public applet](/cheerpj3/getting-started/Java-applet#running-a-public-applet) using the [CheerpJ Applet Runner](https://chrome.google.com/webstore/detail/cheerpj-applet-runner/bbmolahhldcbngedljfadjlognfaaein) Chrome extension for applets integrated with the applet tag `<applet>` on public websites.
+
+## Running your own applet
+
+**You will need:**
+
+- Your applet file(s)
+- An HTML file to wrap your applet
+- A basic HTTP server to test locally
+
+### 1. Create a basic HTML file
+
+```html title="index.html" {6, 9-17}
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>CheerpJ applet test</title>
+		<script src="https://cjrtnc.leaningtech.com/3_20230819_174/cj3loader.js"></script>
+	</head>
+	<body>
+		<cheerpj-applet
+			archive="Example.jar"
+			code="ExamplePath.ExampleApplet"
+			height="900"
+			width="900"
+		></cheerpj-applet>
+		<script>
+			cheerpjInit();
+		</script>
+	</body>
+</html>
+```
+
+### 2. Host your page locally
+
+You can now serve this web page on a simple HTTP server, such as the http-server utility.
+
+```shell
+npm install http-server
+http-server -p 8080
+```
+
+### What's going on?
+
+- The `cheerpjInit();` initializes CheerpJ runtime environment.
+- The `<cheerpj-applet>` tag specifies the code base in a similar manner as the now deprecated `<applet>` tag.
+
+> To avoid potential conflicts with native Java we recommend replacing the original HTML tag with `cheerpj-` prefixed version. You should use `<cheerpj-applet>`, `<cheerpj-object>` or `<cheerpj-embed>` depending on the original tag.
+
+## Running a public applet
+
+### 1. Install the CheerpJ applet runner
+
+CheerpJ Applet Runner is available for Chrome and Edge.
+
+<div class="flex flex-wrap gap-3">
+  <LinkButton
+    type="primary"
+    href="https://chrome.google.com/webstore/detail/cheerpj-applet-runner/bbmolahhldcbngedljfadjlognfaaein"
+    label="Add to Chrome"
+    iconLeft="openmoji:chrome"
+  />
+
+<LinkButton
+	type="primary"
+	href="https://microsoftedge.microsoft.com/addons/detail/cheerpj-applet-runner/ebfcpaoldmijengghefpohddmfpndmic"
+	label="Add to Microsoft Edge"
+	iconLeft="openmoji:edge"
+/>
+
+</div>
+
+### 2. Go to a website with an applet
+
+Visit a page with a Java applet, [such as this one](http://www.neilwallis.com/projects/java/water/index.php) and click on the CheerpJ Applet Runner icon in the toolbar and enable CheerpJ.
+
+![](/cheerpj2/assets/cheerpj_applet_demo.gif)
+
+## The result
+
+You will see the CheerpJ display on your browser with some loading messages before showing your applet running. Depending on your application and the optimizations applied, this could take just a few seconds.
+
+## Further reading
+
+- [Runtime API reference](/cheerpj3/reference)
diff --git a/src/content/docs/cheerpj3/10-getting-started/02-Java-library.md b/src/content/docs/cheerpj3/10-getting-started/02-Java-library.md
@@ -0,0 +1,31 @@
+---
+title: Run a Java library
+subtitle: Use Java classes in JavaScript
+---
+
+## 1. Include CheerpJ on your page
+
+```html
+<script src="https://cjrtnc.leaningtech.com/3_20230819_174/cj3loader.js"></script>
+```
+
+## 2. Initialize CheerpJ and load your Java library
+
+```js
+await cheerpjInit();
+const cj = await cheerpjRunLibrary("/app/library.jar");
+```
+
+This will load `library.jar` from the root of your web server.
+
+## 3. Call Java from JavaScript
+
+```js
+const MyClass = await cj.com.library.MyClass;
+const obj = await new MyClass();
+await obj.myMethod();
+```
+
+## Further reading
+
+- [`cheerpjRunLibrary` reference](/cheerpj3/reference/cheerpjRunLibrary)