diff --git a/sites/cheerpj/public/cheerpj3/tutorials/CheerpJInteroperabilityTutorial.zip b/sites/cheerpj/public/cheerpj3/tutorials/CheerpJInteroperabilityTutorial.zip new file mode 100644 index 00000000..2e6daabb Binary files /dev/null and b/sites/cheerpj/public/cheerpj3/tutorials/CheerpJInteroperabilityTutorial.zip differ diff --git a/sites/cheerpj/src/content/docs/13-tutorials/05-interoperability-tutorial.mdx b/sites/cheerpj/src/content/docs/13-tutorials/05-interoperability-tutorial.mdx new file mode 100644 index 00000000..bf0d632d --- /dev/null +++ b/sites/cheerpj/src/content/docs/13-tutorials/05-interoperability-tutorial.mdx @@ -0,0 +1,204 @@ +--- +title: Java and JavaScript Interoperability +description: Learn how to enable Java and JavaScript communication using CheerpJ +--- + +import Callout from "@leaningtech/astro-theme/components/Callout.astro"; + +With CheerpJ, a Java application can interact with JavaScript in a browser environment, enabling seamless interaction between Java and JavaScript code. + +In this tutorial, we’ll teach you how to create a two-way communication channel between Java and JavaScript using CheerpJ. This setup will allow a Java class to access JavaScript functions and vice versa, enabling data exchange between the two environments. + +## Prerequisites + +- [Download the template project](/docs/cheerpj3/tutorials/CheerpJInteroperabilityTutorial.zip) and unzip it. +- [Node.js](https://nodejs.org/en/) (>= 18) + +## Project structure + +The project consists of the following files and directories: + +```plaintext +CheerpJInteroperabilityTutorial/ +├── com/example +│ └── Example.java +│ └── manifest.txt +│ └── Example.class (and other compiled .class files) +├── index.html +└── example.jar +└── Makefile + +``` + +In this tutorial, we will implement the native methods in JavaScript in the `index.html` file to enable communication between Java and JavaScript. + +You can see the fully implemented example on [GitHub](https://github.com/leaningtech/cheerpj-meta/tree/main/examples/Interoperability). + +## Java source code: `Example.java` + +Let's start by examining the source code of the Java class that will interact with JavaScript. This class will receive input from JavaScript, process it, and send a response back to JavaScript. + +```java title="Example.java" +package com.example; + +public class Example { + public static native void sendToHTML(String s); + + public String processInput(String input) { + sendToHTML(input); + return "Java received: " + input; + } + + public static native void nativeSetApplication(Example myApplication); + + public static void main(String[] args) { + Example app = new Example(); + new Thread(() -> { + nativeSetApplication(app); + System.out.println("Starting Thread"); + }).start(); + } +} +``` + +This Java class contains the following methods: + +- `sendToHTML`: A native method implemented in JavaScript, called to send data to the JavaScript environment. +- `processInput`: Receives data from JavaScript, passes it to `sendToHTML`, and returns a response. +- `nativeSetApplication`: Captures the running Java thread for persistent communication with JavaScript. + + + There is **no need to recompile the Java code** for this tutorial, as a + precompiled file is provided in the template project. However, if you want to + modify the Java code, you will need to recompile it. To do so, follow the + instructions in the [Running the example](#running-the-example) section. + + +## JavaScript native method implementation + +To enable Java and JavaScript communication, we need to implement the [`native`] methods in JavaScript. These methods will handle the data exchange between the two environments. + +We will do this in the `index.html` file, which is part of the template project `.zip` file. In this file, you will find useful comments to guide you through the implementation process described below. + +### 1. Define JavaScript native methods + +In the ` +``` + +To load CheerpJ, we initialize it in the HTML file with specific configurations for native methods. + +```js title="index.html" +(async () => { + await cheerpjInit({ + version: 8, + natives: { + Java_com_example_Example_sendToHTML, + Java_com_example_Example_nativeSetApplication, + }, + }); + cheerpjCreateDisplay(800, 600); + await cheerpjRunJar("/app/example.jar"); +})(); +``` + +Explanation: + +- `cheerpjInit`: Initializes CheerpJ with the specified configurations: + - `version`: Specifies the Java version to use. + - `natives`: Lists JavaScript implementations of native Java methods. +- `cheerpjCreateDisplay`: Creates a display area for any graphical output (optional in this example). +- `cheerpjRunJar`: Loads and runs the provided JAR file. + +## Running the example + +1. There is **no need to recompile the Java code** for this tutorial as we only changed the JavaScript code and you can use the precompiled `example.jar` file provided in the template project. However, if you want to modify the Java code, you can recompile it using the provided `Makefile` (requires Java installed): + +```bash +make +``` + +Alternatively, compile and package manually: + +```bash +javac Example.java +jar cvfm example.jar manifest.txt com/example/*.class +``` + +2. **Start a Local Server**: Serve the files using a simple HTTP server like [`http-server`]: + +```bash +npx http-server -p 8080 +``` + +3. **Run the Example**: Open http://localhost:8080/index.html in your browser. + +## The result + + + +## Source code + +[View full source code on GitHub](https://github.com/leaningtech/cheerpj-meta/tree/main/examples/Interoperability) + +[`http-server`]: https://www.npmjs.com/package/http-server +[`native`]: /docs/guides/implementing-native-methods +[`native method`]: /docs/guides/implementing-native-methods