From 05d88e203ebbc2ac3e9625f4c140c489fa0b77fd Mon Sep 17 00:00:00 2001 From: Rijul Shrestha Date: Wed, 29 Oct 2025 14:09:30 +0000 Subject: [PATCH 1/5] Standardized and fixed typos --- .../content/docs/11-guides/implementing-native-libraries.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sites/cheerpj/src/content/docs/11-guides/implementing-native-libraries.md b/sites/cheerpj/src/content/docs/11-guides/implementing-native-libraries.md index ef4c38ee..ab1ad414 100644 --- a/sites/cheerpj/src/content/docs/11-guides/implementing-native-libraries.md +++ b/sites/cheerpj/src/content/docs/11-guides/implementing-native-libraries.md @@ -23,7 +23,7 @@ In general, we can implement native libraries in CheerpJ by following these step 2. Create a JavaScript module that implements the native methods. 3. Load the native library in the Java class with CheerpJ. -### Loading native nibraries and declaring native methods in Java +### Loading native libraries and declaring native methods in Java To declare a native method in Java, use the `native` keyword in the method declaration. The method is defined in the Java class but is not implemented in Java. Instead, the implementation will be provided in the native library JavaScript module which is loaded with `System.loadLibrary`. @@ -39,7 +39,7 @@ public class ClassName { } ``` -### Creating a JavaScript module +### Creating a JavaScript module and implementing the native methods A JavaScript module is a file that contains code which can be exported and imported by other files for better organization and reuse. You create modules using the `export` keyword to expose classes, methods, or other resources, and you can use `export default` to make a primary, easy-to-import item from the module. For more information on JavaScript modules, check out the official [`documentation`]. @@ -49,7 +49,7 @@ export default { }; ``` -JavaScript functions that implement native methods should follow a specific naming convention - `Java__`. For instance, if `com.foo.Bar` has a native method called `baz`, the function will be called `Java_com_foo_Bar_baz` +To implement a native method in JavaScript, create an `async` function that follows the naming convention `Java__`. For instance, if `com.foo.Bar` has a native method called `baz`, the function will be called `Java_com_foo_Bar_baz`. The JavaScript function should accept the following parameters: From e9797b4215eee5ffa7d735452db859386a8c9197 Mon Sep 17 00:00:00 2001 From: Rijul Shrestha Date: Wed, 29 Oct 2025 14:12:09 +0000 Subject: [PATCH 2/5] Simplified code examples and updated the text --- .../11-guides/implementing-native-methods.md | 66 +++++++++---------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md b/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md index d74c6f8a..1c444191 100644 --- a/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md +++ b/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md @@ -3,6 +3,8 @@ title: Implementing Native Methods description: Java Native Interface (JNI) with CheerpJ --- +In this guide, we’ll explore how to use **native methods** in CheerpJ to implement Java native methods in JavaScript. + CheerpJ allows one to implement Java native methods (typically written in C/C++ or another AOT-compiled language) directly in JavaScript, similar to the Java Native Interface (JNI) in standard Java. In Java, native methods are identified by the `native` keyword in their declaration. These methods are not implemented in Java but are instead defined in an external language, which in the case of CheerpJ, is JavaScript. @@ -17,23 +19,20 @@ In general, we can implement native methods in CheerpJ by following these steps: ## Declaring Native Methods in Java -To declare a native method in Java, use the `native` keyword in the method declaration. Here’s an example of a Java class with a native method: - -```java title="Example.java" -public class Example { - public static void main(String[] args) { - nativeAlert("Hello, world!"); - } +To declare a native method in Java, use the `native` keyword in the method declaration. The method is defined in the Java class but is not implemented in Java. Instead, the implementation will be provided in JavaScript. - public static native void nativeAlert(String message); +```java +public class ClassName { + // Native method declaration + private native void methodName(param1, param2, ...); } ``` -The method is defined in the Java class but is not implemented in Java. Instead, the implementation will be provided in JavaScript. - ## Implementing Native Methods in JavaScript -To implement a native method in JavaScript, create an `async` function that follows the naming convention `Java__`. For instance, if `com.foo.Bar` has a native method called `baz`, its object key is `Java_com_foo_Bar_baz`. The function takes: +To implement a native method in JavaScript, create an `async` function that follows the naming convention `Java__`. For instance, if `com.foo.Bar` has a native method called `baz`, its object key is `Java_com_foo_Bar_baz`. + +The JavaScript function should accept the following parameters: - A [`CJ3Library`] object `lib` as the first parameter, which provides access to other classes and methods within the library. The `lib` parameter can be used to call back into the Java class that calls the native method. - `self` as the second parameter, the instance of the Java class calling the native method. This parameter can be omitted for static native methods. @@ -52,47 +51,48 @@ async function Java__(lib, self, param1 ## Calling back into Java from JavaScript -It is possible to call back into Java using the `lib` parameter received in the JavaScript implementation of the native Java method. +You can call back into Java from a JavaScript native method implementation using the `lib` parameter. The `lib` object exposes your Java classes so you can invoke their static methods. -Let’s take this simple Java class as an example: - -```java title="Example.java" -public class Example { - public static native void nativeFunction(); +```java +public class ClassName { + // Implemented in JavaScript + public static native void nativeMethodName(); - public static void printJava() { - System.out.println("Hello from Java!"); + public static void javaMethodName() { + // Your Java logic here } public static void main(String[] args) { - nativeFunction(); + nativeMethodName(); // Triggers the JS implementation } } ``` -The `Example` class includes a `native` function that will be implemented in JavaScript, and a public print function that outputs `Hello from Java!`. -In the JavaScript implementation of `nativeFunction`, we can use the `lib` parameter to call back into the `Example` Java class and invoke the `printJava()` function from JavaScript. +The `ClassName` class defines a `native method` called `nativeMethodName`, which will be implemented in JavaScript. It also includes a public method, `javaMethodName`, that performs some Java logic. + +In the JavaScript implementation of `nativeMethodName`, you can use the `lib` parameter to access the `ClassName` Java class and call its methods from JavaScript. This allows JavaScript code to call back into Java and execute Java logic directly from the browser. ```js -async function Java_Example_nativeFunction(lib) { - const Example = await lib.Example; - await Example.printJava(); +// Example placeholders — replace ClassName/javaMethodName with your own +async function Java_ClassName_nativeMethodName(lib) { + const ClassName = await lib.ClassName; // Access your Java class + await ClassName.javaMethodName(); // Call a Java static method } ``` This functionality is useful when you need to call back into the Java class in response to a native function call. If you need to call back into Java outside the context of a native function, you can use a long-running Java thread. You can learn more about how to achieve this in our [`Java and JavaScript Interoperability`] tutorial. -## Passing Native Functions to CheerpJ +## Initializing CheerpJ with the `natives` option -To use the native method in CheerpJ, pass the function to the [`cheerpjInit`] function as a property of the [`natives`] option. You can pass: +To use the native method in CheerpJ, pass the function to the [`cheerpjInit`] function as a property of the [`natives`] option. There are two ways in which you can do this. -1. **The function definition directly**: +1. **In the function definition directly**: ```js await cheerpjInit({ natives: { - async Java_Example_nativeAlert(lib, str) { - window.alert(str); + async Java_Example_nativeMethodName(lib, str) { + // Implementation }, }, }); @@ -101,11 +101,11 @@ await cheerpjInit({ 2. **Or just the function name if it was defined earlier**: ```js -async function Java_Example_nativeAlert(lib, str) { - window.alert(str); +async function Java_Example_nativeMethodName(lib, str) { + // Implementation } -await cheerpjInit({ natives: { Java_Example_nativeAlert } }); +await cheerpjInit({ natives: { Java_Example_nativeMethodName } }); ``` ## Converting Parameters and Return Values From c61e309a7d4febcf2663f79e6912d40cbe691b6d Mon Sep 17 00:00:00 2001 From: Rijul Shrestha Date: Wed, 29 Oct 2025 14:23:50 +0000 Subject: [PATCH 3/5] Updated example and formatted code --- .../11-guides/implementing-native-methods.md | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md b/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md index 1c444191..c4d1ae2d 100644 --- a/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md +++ b/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md @@ -75,8 +75,8 @@ In the JavaScript implementation of `nativeMethodName`, you can use the `lib` pa ```js // Example placeholders — replace ClassName/javaMethodName with your own async function Java_ClassName_nativeMethodName(lib) { - const ClassName = await lib.ClassName; // Access your Java class - await ClassName.javaMethodName(); // Call a Java static method + const ClassName = await lib.ClassName; // Access your Java class + await ClassName.javaMethodName(); // Call a Java static method } ``` @@ -86,7 +86,7 @@ This functionality is useful when you need to call back into the Java class in r To use the native method in CheerpJ, pass the function to the [`cheerpjInit`] function as a property of the [`natives`] option. There are two ways in which you can do this. -1. **In the function definition directly**: +1. **In the function definition directly** ```js await cheerpjInit({ @@ -98,7 +98,7 @@ await cheerpjInit({ }); ``` -2. **Or just the function name if it was defined earlier**: +2. **Or just the function name if it was defined earlier** ```js async function Java_Example_nativeMethodName(lib, str) { @@ -121,22 +121,22 @@ Here’s a full example that demonstrates the native method setup in Java and it ```java title="Example.java" public class Example { public static void main(String[] args) { - nativeAlert("Hello, world!"); + Alert("Hello, world!"); } - public static native void nativeAlert(String message); + public static native void Alert(String message); } ``` 2. Implement the native method by creating an `async` function in JavaScript that follows the naming convention `Java__`. ```js title="index.html" -async function Java_Example_nativeAlert(lib, str) { +async function Java_Example_Alert(lib, str) { window.alert(str); } ``` -Here, we provide an implementation for the `nativeAlert` method in the `Example` class, by creating a function named `Java_Example_nativeAlert`. The function displays an alert dialog with the message using `window.alert`. +Here, we provide an implementation for the `Alert` method in the `Example` class, by creating a function named `Java_Example_Alert`. The function displays an alert dialog with the message using `window.alert`. 3. Initialize CheerpJ with the `natives` option and pass the native method implementation to [`cheerpjInit`]: @@ -148,13 +148,15 @@ Here, we provide an implementation for the `nativeAlert` method in the `Example` - From 9b1588bac45cab429d2e39885d6ac3c118c5bbf7 Mon Sep 17 00:00:00 2001 From: Rijul Shrestha Date: Thu, 30 Oct 2025 09:30:53 +0000 Subject: [PATCH 4/5] Added 'naitve' prefix to the native funtion for consistency --- .../docs/11-guides/implementing-native-methods.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md b/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md index c4d1ae2d..f2fb5b35 100644 --- a/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md +++ b/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md @@ -121,22 +121,22 @@ Here’s a full example that demonstrates the native method setup in Java and it ```java title="Example.java" public class Example { public static void main(String[] args) { - Alert("Hello, world!"); + nativeAlert("Hello, world!"); } - public static native void Alert(String message); + public static native void nativeAlert(String message); } ``` 2. Implement the native method by creating an `async` function in JavaScript that follows the naming convention `Java__`. ```js title="index.html" -async function Java_Example_Alert(lib, str) { +async function Java_Example_nativeAlert(lib, str) { window.alert(str); } ``` -Here, we provide an implementation for the `Alert` method in the `Example` class, by creating a function named `Java_Example_Alert`. The function displays an alert dialog with the message using `window.alert`. +Here, we provide an implementation for the `nativeAlert` method in the `Example` class, by creating a function named `Java_Example_nativeAlert`. The function displays an alert dialog with the message using `window.alert`. 3. Initialize CheerpJ with the `natives` option and pass the native method implementation to [`cheerpjInit`]: @@ -154,7 +154,7 @@ Here, we provide an implementation for the `Alert` method in the `Example` class } // Init CheerpJ and register natives, then run your main await cheerpjInit({ - natives: { Java_Example_Alert }, + natives: { Java_Example_nativeAlert }, }); await cheerpjRunMain("Example", "/app"); From 96021a44751b128817ae619508d3e78eb6431b40 Mon Sep 17 00:00:00 2001 From: Rijul Shrestha Date: Thu, 30 Oct 2025 09:48:20 +0000 Subject: [PATCH 5/5] Changed the content order of the page --- .../11-guides/implementing-native-methods.md | 82 +++++++++---------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md b/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md index f2fb5b35..ed27e2ba 100644 --- a/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md +++ b/sites/cheerpj/src/content/docs/11-guides/implementing-native-methods.md @@ -9,7 +9,7 @@ CheerpJ allows one to implement Java native methods (typically written in C/C++ In Java, native methods are identified by the `native` keyword in their declaration. These methods are not implemented in Java but are instead defined in an external language, which in the case of CheerpJ, is JavaScript. -## Overview +## Steps to implement native methods in CheerpJ In general, we can implement native methods in CheerpJ by following these steps: @@ -17,7 +17,7 @@ In general, we can implement native methods in CheerpJ by following these steps: 2. Implement the native method in JavaScript. 3. Pass the native function to CheerpJ. -## Declaring Native Methods in Java +### Declaring Native Methods in Java To declare a native method in Java, use the `native` keyword in the method declaration. The method is defined in the Java class but is not implemented in Java. Instead, the implementation will be provided in JavaScript. @@ -28,7 +28,7 @@ public class ClassName { } ``` -## Implementing Native Methods in JavaScript +### Implementing Native Methods in JavaScript To implement a native method in JavaScript, create an `async` function that follows the naming convention `Java__`. For instance, if `com.foo.Bar` has a native method called `baz`, its object key is `Java_com_foo_Bar_baz`. @@ -49,40 +49,7 @@ async function Java__(lib, self, param1 > [!info] Handling Static Native Methods > If the native method is static, the `self` parameter can be omitted. -## Calling back into Java from JavaScript - -You can call back into Java from a JavaScript native method implementation using the `lib` parameter. The `lib` object exposes your Java classes so you can invoke their static methods. - -```java -public class ClassName { - // Implemented in JavaScript - public static native void nativeMethodName(); - - public static void javaMethodName() { - // Your Java logic here - } - - public static void main(String[] args) { - nativeMethodName(); // Triggers the JS implementation - } -} -``` - -The `ClassName` class defines a `native method` called `nativeMethodName`, which will be implemented in JavaScript. It also includes a public method, `javaMethodName`, that performs some Java logic. - -In the JavaScript implementation of `nativeMethodName`, you can use the `lib` parameter to access the `ClassName` Java class and call its methods from JavaScript. This allows JavaScript code to call back into Java and execute Java logic directly from the browser. - -```js -// Example placeholders — replace ClassName/javaMethodName with your own -async function Java_ClassName_nativeMethodName(lib) { - const ClassName = await lib.ClassName; // Access your Java class - await ClassName.javaMethodName(); // Call a Java static method -} -``` - -This functionality is useful when you need to call back into the Java class in response to a native function call. If you need to call back into Java outside the context of a native function, you can use a long-running Java thread. You can learn more about how to achieve this in our [`Java and JavaScript Interoperability`] tutorial. - -## Initializing CheerpJ with the `natives` option +### Initializing CheerpJ with the `natives` option To use the native method in CheerpJ, pass the function to the [`cheerpjInit`] function as a property of the [`natives`] option. There are two ways in which you can do this. @@ -108,10 +75,6 @@ async function Java_Example_nativeMethodName(lib, str) { await cheerpjInit({ natives: { Java_Example_nativeMethodName } }); ``` -## Converting Parameters and Return Values - -Parameters and return values of JNI calls are automatically converted between JavaScript and Java types based on [`conversion rules`]. - ## Example Walkthrough Here’s a full example that demonstrates the native method setup in Java and its JavaScript implementation. @@ -164,6 +127,43 @@ Here, we provide an implementation for the `nativeAlert` method in the `Example` In this setup, [`cheerpjInit`] loads `Java_Example_nativeAlert` as the native method implementation. When `Example.nativeAlert` is called in Java, it triggers the JavaScript `Java_Example_nativeAlert` function, displaying an alert dialog with the message. +## Calling back into Java from JavaScript + +You can call back into Java from a JavaScript native method implementation using the `lib` parameter. The `lib` object exposes your Java classes so you can invoke their static methods. + +```java +public class ClassName { + // Implemented in JavaScript + public static native void nativeMethodName(); + + public static void javaMethodName() { + // Your Java logic here + } + + public static void main(String[] args) { + nativeMethodName(); // Triggers the JS implementation + } +} +``` + +The `ClassName` class defines a `native method` called `nativeMethodName`, which will be implemented in JavaScript. It also includes a public method, `javaMethodName`, that performs some Java logic. + +In the JavaScript implementation of `nativeMethodName`, you can use the `lib` parameter to access the `ClassName` Java class and call its methods from JavaScript. This allows JavaScript code to call back into Java and execute Java logic directly from the browser. + +```js +// Example placeholders — replace ClassName/javaMethodName with your own +async function Java_ClassName_nativeMethodName(lib) { + const ClassName = await lib.ClassName; // Access your Java class + await ClassName.javaMethodName(); // Call a Java static method +} +``` + +This functionality is useful when you need to call back into the Java class in response to a native function call. If you need to call back into Java outside the context of a native function, you can use a long-running Java thread. You can learn more about how to achieve this in our [`Java and JavaScript Interoperability`] tutorial. + +## Converting Parameters and Return Values + +Parameters and return values of JNI calls are automatically converted between JavaScript and Java types based on [`conversion rules`]. + [`natives`]: /docs/reference/cheerpjInit#natives [`CJ3Library`]: /docs/reference/CJ3Library [`conversion rules`]: /docs/reference/CJ3Library#conversion-rules