From 9a4d20e10eb4ab27f58b823956deb1d162de0c45 Mon Sep 17 00:00:00 2001 From: Aman Date: Sun, 21 Dec 2025 11:26:20 +0530 Subject: [PATCH 1/3] Documentation update --- .../SwiftJavaCommandLineTool.md | 100 ++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md b/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md index 823713836..44df251f7 100644 --- a/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md +++ b/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md @@ -214,6 +214,106 @@ The project is still very early days, however the general outline of using this You can then use Swift libraries in Java just by calling the appropriate methods and initializers. +#### Enable Java Callbacks Mode + +> **NOTE**: This feature requires disabling the SwiftPM Sandbox and is only supported in 'jni' mode. + +The `enableJavaCallbacks` mode is an advanced feature that allows Java classes to implement Swift protocols. When enabled, JExtract generates additional Java interface wrappers that enable bidirectional interoperability - not only can Java code call Swift functions, but Java classes can also implement Swift protocols and be passed back to Swift. + +**Key characteristics:** +- **Mode restriction**: Only available in JNI mode (will throw an error if used with FFM mode) +- **Sandbox requirement**: Requires disabling SwiftPM sandbox (`--disable-sandbox` or equivalent) +- **Protocol implementation**: Enables Java classes to implement Swift protocols +- **Bidirectional communication**: Allows callbacks from Swift back to Java implementations + +**How to enable:** + +In your `swift-java.config` file: +```json +{ + "enableJavaCallbacks": true, + "mode": "jni" +} +``` + +Or via command line: +```bash +swift-java jextract --enable-java-callbacks --mode jni ... +``` + +**How it works:** + +When `enableJavaCallbacks` is enabled, JExtract generates: +1. **Interface wrappers**: Java interfaces that correspond to Swift protocols +2. **Protocol implementations**: Generated Java classes that can be passed to Swift +3. **Bridge code**: JNI bridge code that allows Swift to call back into Java implementations + +**Example usage:** + +```swift +// Swift code defining a protocol +public protocol MySwiftProtocol { + func handleData(_ data: String) + func processNumber(_ value: Int) -> Bool +} + +// Swift code that uses the protocol +public class SwiftProcessor { + private var delegate: MySwiftProtocol? + + public func setDelegate(_ delegate: MySwiftProtocol) { + self.delegate = delegate + } + + public func doWork() { + delegate?.handleData("Hello from Swift") + let result = delegate?.processNumber(42) ?? false + print("Result: \(result)") + } +} +``` + +```java +// Java code that implements the Swift protocol +public class MyJavaImplementation implements MySwiftProtocol { + @Override + public void handleData(String data) { + System.out.println("Java received: " + data); + } + + @Override + public boolean processNumber(int value) { + System.out.println("Java processing: " + value); + return value > 0; + } +} + +// Java usage +public class Main { + public static void main(String[] args) { + MyJavaImplementation javaImpl = new MyJavaImplementation(); + SwiftProcessor processor = new SwiftProcessor(); + + // Pass Java implementation to Swift + processor.setDelegate(javaImpl); + processor.doWork(); + } +} +``` + +**Limitations:** +- Only supported in JNI mode +- Requires SwiftPM sandbox to be disabled +- Performance overhead compared to direct JNI calls +- Limited to protocol methods (not all Swift features) + +**When to use:** +- When you need Java classes to implement Swift protocols +- For event-driven architectures where Swift needs to call back into Java +- When building hybrid applications that require tight integration between languages + +For a complete working example, see `Samples/SwiftJavaExtractJNISampleApp` which demonstrates this feature in action. + ### Generating Java bindings for Swift libraries This repository also includes the `jextract-swift` tool which is similar to the JDK's [`jextract`](https://github.com/openjdk/jextract/). From 21b671f8ea1f5cfc6f1278aec40238b548c121a1 Mon Sep 17 00:00:00 2001 From: Aman Maurya Date: Sun, 21 Dec 2025 13:43:16 +0530 Subject: [PATCH 2/3] Revise Java Callbacks Mode documentation Updated the documentation for enabling Java Callbacks Mode, including configuration examples and usage details. --- .../SwiftJavaCommandLineTool.md | 106 +++--------------- 1 file changed, 17 insertions(+), 89 deletions(-) diff --git a/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md b/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md index 44df251f7..914397058 100644 --- a/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md +++ b/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md @@ -214,105 +214,33 @@ The project is still very early days, however the general outline of using this You can then use Swift libraries in Java just by calling the appropriate methods and initializers. -#### Enable Java Callbacks Mode +### Enable Java Callbacks Mode -> **NOTE**: This feature requires disabling the SwiftPM Sandbox and is only supported in 'jni' mode. +> **Note** -The `enableJavaCallbacks` mode is an advanced feature that allows Java classes to implement Swift protocols. When enabled, JExtract generates additional Java interface wrappers that enable bidirectional interoperability - not only can Java code call Swift functions, but Java classes can also implement Swift protocols and be passed back to Swift. +--- -**Key characteristics:** -- **Mode restriction**: Only available in JNI mode (will throw an error if used with FFM mode) -- **Sandbox requirement**: Requires disabling SwiftPM sandbox (`--disable-sandbox` or equivalent) -- **Protocol implementation**: Enables Java classes to implement Swift protocols -- **Bidirectional communication**: Allows callbacks from Swift back to Java implementations - -**How to enable:** - -In your `swift-java.config` file: -```json -{ - "enableJavaCallbacks": true, - "mode": "jni" -} -``` - -Or via command line: -```bash -swift-java jextract --enable-java-callbacks --mode jni ... -``` +## Overview -**How it works:** +One-line description of the feature. -When `enableJavaCallbacks` is enabled, JExtract generates: -1. **Interface wrappers**: Java interfaces that correspond to Swift protocols -2. **Protocol implementations**: Generated Java classes that can be passed to Swift -3. **Bridge code**: JNI bridge code that allows Swift to call back into Java implementations +--- -**Example usage:** +## Requirements -```swift -// Swift code defining a protocol -public protocol MySwiftProtocol { - func handleData(_ data: String) - func processNumber(_ value: Int) -> Bool -} +- Supported modes +- Sandbox requirements -// Swift code that uses the protocol -public class SwiftProcessor { - private var delegate: MySwiftProtocol? - - public func setDelegate(_ delegate: MySwiftProtocol) { - self.delegate = delegate - } - - public func doWork() { - delegate?.handleData("Hello from Swift") - let result = delegate?.processNumber(42) ?? false - print("Result: \(result)") - } -} -``` +--- -```java -// Java code that implements the Swift protocol -public class MyJavaImplementation implements MySwiftProtocol { - @Override - public void handleData(String data) { - System.out.println("Java received: " + data); - } - - @Override - public boolean processNumber(int value) { - System.out.println("Java processing: " + value); - return value > 0; - } -} +## How to Enable -// Java usage -public class Main { - public static void main(String[] args) { - MyJavaImplementation javaImpl = new MyJavaImplementation(); - SwiftProcessor processor = new SwiftProcessor(); - - // Pass Java implementation to Swift - processor.setDelegate(javaImpl); - processor.doWork(); - } +### Configuration file +```json +{ + "enableJavaCallbacks": true, + "mode": "jni" } -``` - -**Limitations:** -- Only supported in JNI mode -- Requires SwiftPM sandbox to be disabled -- Performance overhead compared to direct JNI calls -- Limited to protocol methods (not all Swift features) - -**When to use:** -- When you need Java classes to implement Swift protocols -- For event-driven architectures where Swift needs to call back into Java -- When building hybrid applications that require tight integration between languages - -For a complete working example, see `Samples/SwiftJavaExtractJNISampleApp` which demonstrates this feature in action. ### Generating Java bindings for Swift libraries @@ -364,4 +292,4 @@ You can refer to the `SwiftJavaConfigurationShared/Configuration` struct to lear Configuration from the config files may be overriden or augmented by explicit command line parameters, please refer to the options documentation for details on their behavior. -> Note: **Comments in configuration**: The configuration is a JSON 5 file, which among other things allows `//` and `/* */` comments, so feel free to add line comments explaining rationale for some of the settings in youf configuration. \ No newline at end of file +> Note: **Comments in configuration**: The configuration is a JSON 5 file, which among other things allows `//` and `/* */` comments, so feel free to add line comments explaining rationale for some of the settings in youf configuration. From 4e8a6088ebea11026e947a7087eb72a97eba4a26 Mon Sep 17 00:00:00 2001 From: Aman Maurya Date: Sun, 21 Dec 2025 13:53:58 +0530 Subject: [PATCH 3/3] Remove Java Callbacks Mode section from documentation Removed sections on enabling Java callbacks mode and configuration details. --- .../SwiftJavaCommandLineTool.md | 28 ------------------- 1 file changed, 28 deletions(-) diff --git a/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md b/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md index 914397058..fec378522 100644 --- a/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md +++ b/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaCommandLineTool.md @@ -214,34 +214,6 @@ The project is still very early days, however the general outline of using this You can then use Swift libraries in Java just by calling the appropriate methods and initializers. -### Enable Java Callbacks Mode - -> **Note** - ---- - -## Overview - -One-line description of the feature. - ---- - -## Requirements - -- Supported modes -- Sandbox requirements - ---- - -## How to Enable - -### Configuration file -```json -{ - "enableJavaCallbacks": true, - "mode": "jni" -} - ### Generating Java bindings for Swift libraries This repository also includes the `jextract-swift` tool which is similar to the JDK's [`jextract`](https://github.com/openjdk/jextract/).