JavaKit: Rework @ImplementsJava to be more like @implements language feature

The `@ImplementsJava` macro had an odd formulation where it was used similarly
to `@JavaMethod`, but was actually interpreted by the outer `@JavaClass` macro.
Completely rework the way `@ImplementsJava` is used to make it more like the
`@implements` feature introduced in SE-0436, and rename it to `@JavaImplements`
to more closely match the canonical spelling for `@implementation` with a
language and make use of the `@Java...` as a common prefix.

In this new design, one places `@JavaImplements` on an extension of the Swift
type and marks the implementing methods with `@JavaMethod`. For example:

    @JavaImplements("org.swift.javakit.HelloSwift")
    extension Hello {
      @JavaMethod
      func reportStatistics(_ meaning: String, _ numbers: [Double]) -> String {
        let average = numbers.isEmpty ? 0.0 : numbers.reduce(0.0) { $0 + $1 } / Double(numbers.count)
        return "Average of \(meaning) is \(average)"
      }
    }

This also means that we can generate most of the `@JavaClass` definition
for a given Java class, and leave the native methods to be implemented
by an `@JavaImplements` extension. Update the JavaKitSampleApp to use the
Java compilation plugin to compile the Java files in the target. Automatically
feed those into the Java2Swift plugin to generate the Swift
representations of the Java classes, skipping the native methods
(since they'll be implemented here).

The user guide / tutorial is a bit behind the implementation here as I
smooth out more corners.

Author: DougGregor

Plugins/Java2SwiftPlugin/Java2SwiftPlugin.swift

@@ -93,6 +93,21 @@ struct Java2SwiftBuildToolPlugin: BuildToolPlugin {
       outputDirectory.appending(path: "\(swiftName).swift")
     }
 
+    // Find the Java .class files generated from prior plugins.
+    let compiledClassFiles = sourceModule.pluginGeneratedResources.filter { url in
+      url.pathExtension == "class"
+    }
+
+    if let firstClassFile = compiledClassFiles.first {
+      // Keep stripping off parts of the path until we hit the "Java" part.
+      // That's where the class path starts.
+      var classpath = firstClassFile
+      while classpath.lastPathComponent != "Java" {
+        classpath.deleteLastPathComponent()
+      }
+      arguments += [ "--classpath", classpath.path() ]
+    }
+
     return [
       .buildCommand(
         displayName: "Wrapping \(config.classes.count) Java classes target \(sourceModule.name) in Swift",

Samples/JavaKitSampleApp/Package.swift

@@ -4,6 +4,42 @@
 import CompilerPluginSupport
 import PackageDescription
 
+import class Foundation.FileManager
+import class Foundation.ProcessInfo
+
+// Note: the JAVA_HOME environment variable must be set to point to where
+// Java is installed, e.g.,
+//   Library/Java/JavaVirtualMachines/openjdk-21.jdk/Contents/Home.
+func findJavaHome() -> String {
+  if let home = ProcessInfo.processInfo.environment["JAVA_HOME"] {
+    return home
+  }
+
+  // This is a workaround for envs (some IDEs) which have trouble with
+  // picking up env variables during the build process
+  let path = "\(FileManager.default.homeDirectoryForCurrentUser.path()).java_home"
+  if let home = try? String(contentsOfFile: path, encoding: .utf8) {
+    if let lastChar = home.last, lastChar.isNewline {
+      return String(home.dropLast())
+    }
+
+    return home
+  }
+
+  fatalError("Please set the JAVA_HOME environment variable to point to where Java is installed.")
+}
+let javaHome = findJavaHome()
+
+let javaIncludePath = "\(javaHome)/include"
+#if os(Linux)
+  let javaPlatformIncludePath = "\(javaIncludePath)/linux"
+#elseif os(macOS)
+  let javaPlatformIncludePath = "\(javaIncludePath)/darwin"
+#else
+  // TODO: Handle windows as well
+  #error("Currently only macOS and Linux platforms are supported, this may change in the future.")
+#endif
+
 let package = Package(
   name: "JavaKitSampleApp",
   platforms: [
@@ -34,11 +70,12 @@ let package = Package(
         .product(name: "JavaKitJar", package: "swift-java"),
       ],
       swiftSettings: [
-        .swiftLanguageMode(.v5)
+        .swiftLanguageMode(.v5),
+        .unsafeFlags(["-I\(javaIncludePath)", "-I\(javaPlatformIncludePath)"])
       ],
       plugins: [
+        .plugin(name: "JavaCompilerPlugin", package: "swift-java"),
         .plugin(name: "Java2SwiftPlugin", package: "swift-java"),
-        .plugin(name: "JavaCompilerPlugin", package: "swift-java")
       ]
     ),
   ]

Samples/JavaKitSampleApp/Sources/JavaKitExample/Java2Swift.config

@@ -1,5 +1,8 @@
 {
   "classes" : {
-    "java.util.ArrayList" : "ArrayList"
+    "java.util.ArrayList" : "ArrayList",
+    "com.example.swift.HelloSwift" : "HelloSwift",
+    "com.example.swift.HelloSubclass" : "HelloSubclass",
+    "com.example.swift.JavaKitSampleMain" : "JavaKitSampleMain"
   }
 }

Samples/JavaKitSampleApp/Sources/JavaKitExample/JavaKitExample.swift

@@ -18,30 +18,9 @@ enum SwiftWrappedError: Error {
   case message(String)
 }
 
-@JavaClass("com.example.swift.HelloSwift")
-struct HelloSwift {
+@JavaImplements("com.example.swift.HelloSwift")
+extension HelloSwift {
   @JavaMethod
-  init(environment: JNIEnvironment)
-
-  @JavaMethod
-  func sayHelloBack(_ i: Int32) -> Double
-
-  @JavaMethod
-  func greet(_ name: String)
-
-  @JavaMethod
-  func doublesToStrings(doubles: [Double]) -> [String]
-
-  @JavaMethod
-  func throwMessage(message: String) throws
-
-  @JavaField
-  var value: Double
-
-  @JavaField
-  var name: String
-
-  @ImplementsJava
   func sayHello(i: Int32, _ j: Int32) -> Int32 {
     print("Hello from Swift!")
     let answer = self.sayHelloBack(i + j)
@@ -65,7 +44,7 @@ struct HelloSwift {
     self.name = "a 🗑️-collected language"
     _ = self.sayHelloBack(42)
 
-    let strings = doublesToStrings(doubles: [3.14159, 2.71828])
+    let strings = doublesToStrings([3.14159, 2.71828])
     print("Converting doubles to strings: \(strings)")
 
     // Try downcasting
@@ -83,42 +62,24 @@ struct HelloSwift {
     assert(!newHello.is(HelloSubclass.self))
 
     // Create a new instance.
-    let helloSubFromSwift = HelloSubclass(greeting: "Hello from Swift", environment: javaEnvironment)
+    let helloSubFromSwift = HelloSubclass("Hello from Swift", environment: javaEnvironment)
     helloSubFromSwift.greetMe()
 
     do {
-      try throwMessage(message: "I am an error")
+      try throwMessage("I am an error")
     } catch {
       print("Caught Java error: \(error)")
     }
 
     return i * j
   }
 
-  @ImplementsJava
+  @JavaMethod
   func throwMessageFromSwift(message: String) throws -> String {
     throw SwiftWrappedError.message(message)
   }
 }
 
-extension JavaClass<HelloSwift> {
-  @JavaStaticField
-  var initialValue: Double
-}
-
-@JavaClass("com.example.swift.HelloSubclass", extends: HelloSwift.self)
-struct HelloSubclass {
-  @JavaField
-  var greeting: String
-
-  @JavaMethod
-  func greetMe()
-
-  @JavaMethod
-  init(greeting: String, environment: JNIEnvironment)
-}
-
-
 func removeLast(arrayList: ArrayList<JavaClass<HelloSwift>>) {
   if let lastObject = arrayList.getLast() {
     _ = arrayList.remove(lastObject)

Samples/JavaKitSampleApp/Sources/JavaKitExample/com/example/swift/HelloSubclass.java

@@ -21,7 +21,7 @@ public HelloSubclass(String greeting) {
         this.greeting = greeting;
     }
 
-    private void greetMe() {
+    public void greetMe() {
         super.greet(greeting);
     }
 }

Samples/JavaKitSampleApp/Sources/JavaKitExample/com/example/swift/HelloSwift.java

@@ -15,9 +15,9 @@
 package com.example.swift;
 
 public class HelloSwift {
-    private double value;
-    private static double initialValue = 3.14159;
-    private String name = "Java";
+    public double value;
+    public static double initialValue = 3.14159;
+    public String name = "Java";
 
     static {
         System.loadLibrary("JavaKitExample");
@@ -31,7 +31,7 @@ public HelloSwift() {
     public native String throwMessageFromSwift(String message) throws Exception;
 
     // To be called back by the native code
-    private double sayHelloBack(int i) {
+    public double sayHelloBack(int i) {
         System.out.println("And hello back from " + name + "! You passed me " + i);
         return value;
     }
@@ -40,7 +40,7 @@ public void greet(String name) {
         System.out.println("Salutations, " + name);
     }
 
-    String[] doublesToStrings(double[] doubles) {
+    public String[] doublesToStrings(double[] doubles) {
         int size = doubles.length;
         String[] strings = new String[size];
 

Samples/JavaKitSampleApp/Sources/JavaKitExample/com/example/swift/JavaKitSampleMain.java

@@ -19,7 +19,6 @@
  * For the Swift implementation refer to
  */
 public class JavaKitSampleMain {
-
     public static void main(String[] args) {
         int result = new HelloSubclass("Swift").sayHello(17, 25);
         System.out.println("sayHello(17, 25) = " + result);

Sources/Java2SwiftLib/JavaTranslator.swift

@@ -268,6 +268,10 @@ extension JavaTranslator {
     members.append(
       contentsOf: javaClass.getConstructors().compactMap {
         $0.flatMap { constructor in
+          if constructor.isNative {
+            return nil
+          }
+
           do {
             return try translateConstructor(constructor)
           } catch {
@@ -283,6 +287,11 @@ extension JavaTranslator {
     members.append(
       contentsOf: javaClass.getMethods().compactMap {
         $0.flatMap { method in
+          if method.isNative {
+            return nil
+          }
+
+
           // Save the static methods; they need to go on an extension of
           // JavaClass.
           if method.isStatic {

Sources/JavaKit/Macros.swift

@@ -41,7 +41,6 @@
   named(`as`)
 )
 @attached(extension, conformances: AnyJavaObject)
-@attached(peer)
 public macro JavaClass(
   _ fullClassName: String,
   extends: (any AnyJavaObject.Type)? = nil,
@@ -143,23 +142,27 @@ public macro JavaMethod() = #externalMacro(module: "JavaKitMacros", type: "JavaM
 @attached(body)
 public macro JavaStaticMethod() = #externalMacro(module: "JavaKitMacros", type: "JavaMethodMacro")
 
-/// Macro that exposes the given Swift method as a native method in Java.
-///
-/// The macro must be used within a struct type marked with `@JavaClass`, and there
-/// must be a corresponding Java method declared as `native` for it to be called from
-/// Java. For example, given this Swift method:
-///
-/// ```swift
-/// @ImplementsJava
-/// func sayHello(i: Int32, _ j: Int32) -> Int32 {
-///   // swift implementation
-/// }
+/// Macro that marks extensions to specify that all of the @JavaMethod
+/// methods are implementations of Java methods spelled as `native`.
 ///
-/// inside a struct with `@JavaClass("com.example.swift.HelloSwift")`, the
-/// corresponding `HelloSwift` Java class should have:
+/// For example, given a Java native method such as the following in
+/// a Java class `org.swift.example.Hello`:
 ///
 /// ```java
 /// public native int sayHello(int i, int j);
 /// ```
+///
+/// Assuming that the Java class with imported into Swift as `Hello`, t
+/// the method can be implemented in Swift with the following:
+///
+/// ```swift
+/// @JavaImplements
+/// extension Hello {
+///   @JavaMethod
+///   func sayHello(i: Int32, _ j: Int32) -> Int32 {
+///     // swift implementation
+///   }
+/// }
+/// ```
 @attached(peer)
-public macro ImplementsJava() = #externalMacro(module: "JavaKitMacros", type: "ImplementsJavaMacro")
+public macro JavaImplements(_ fullClassName: String) = #externalMacro(module: "JavaKitMacros", type: "JavaImplementsMacro")

Sources/JavaKitMacros/GenerationMode.swift

@@ -0,0 +1,76 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift.org project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of Swift.org project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftSyntax
+import SwiftSyntaxMacros
+
+/// The mode of code generation being used for macros.
+enum GenerationMode {
+  /// This macro is describing a Java class in Swift.
+  case importFromJava
+
+  /// This macro is describing a Swift type that will be represented by
+  /// a generated Java class.
+  case exportToJava
+
+  /// This macro is describing an extension that is implementing the native
+  /// methods of a Java class.
+  case JavaImplements
+
+  /// Determine the mode for Java class generation based on an attribute.
+  init?(attribute: AttributeSyntax) {
+    switch attribute.attributeName.trimmedDescription {
+    case "JavaClass", "JavaInterface":
+      self = .importFromJava
+
+    case "ExportToJavaClass":
+      self = .exportToJava
+
+    case "JavaImplements":
+      self = .JavaImplements
+
+    default:
+      return nil
+    }
+  }
+
+  /// Determine the mode for Java class generation based on the the macro
+  /// expansion context.
+  init?(expansionContext: some MacroExpansionContext) {
+    for lexicalContext in expansionContext.lexicalContext {
+      // FIXME: swift-syntax probably needs an AttributedSyntax node for us
+      // to look at. For now, we can look at just structs and extensions.
+      let attributes: AttributeListSyntax
+      if let structSyntax = lexicalContext.as(StructDeclSyntax.self) {
+        attributes = structSyntax.attributes
+      } else if let extSyntax = lexicalContext.as(ExtensionDeclSyntax.self) {
+        attributes = extSyntax.attributes
+      } else {
+        continue
+      }
+
+      // Look for the first attribute that is associated with a mode, and
+      // return that.
+      for attribute in attributes {
+        if case .attribute(let attribute) = attribute,
+           let mode = GenerationMode(attribute: attribute) {
+          self = mode
+          return
+        }
+      }
+    }
+
+    return nil
+  }
+}