Java2Swift: Produce a protocol to aid with native method implementation

When an imported Java class has native methods that we expect to implement
from Swift, create a protocol names <Swift Type>NativeMethods that declares
all of the methods that need to be implemented.

From the user perspective, one should make the `@JavaImplements` extension
conform to this protocol. Then, the compiler will ensure that the right
Swift methods exist with the right signatures. Note that the user is
still responsible for ensuring that the appropriate `@JavaImplements` and
`@JavaMethod` annotations are present.

Author: DougGregor

Plugins/Java2SwiftPlugin/Java2SwiftPlugin.swift

@@ -106,6 +106,23 @@ struct Java2SwiftBuildToolPlugin: BuildToolPlugin {
         classpath.deleteLastPathComponent()
       }
       arguments += [ "--classpath", classpath.path() ]
+
+      // For each of the class files, note that it can have Swift-native
+      // implementations. We figure this out based on the path.
+      for classFile in compiledClassFiles {
+        var classFile = classFile.deletingPathExtension()
+        var classNameComponents: [String] = []
+
+        while classFile.lastPathComponent != "Java" {
+          classNameComponents.append(classFile.lastPathComponent)
+          classFile.deleteLastPathComponent()
+        }
+
+        let className = classNameComponents
+          .reversed()
+          .joined(separator: ".")
+        arguments += [ "--swift-native-implementation", className]
+      }
     }
 
     return [

Samples/JavaKitSampleApp/Sources/JavaKitExample/JavaKitExample.swift

@@ -19,9 +19,9 @@ enum SwiftWrappedError: Error {
 }
 
 @JavaImplements("com.example.swift.HelloSwift")
-extension HelloSwift {
+extension HelloSwift: HelloSwiftNativeMethods {
   @JavaMethod
-  func sayHello(i: Int32, _ j: Int32) -> Int32 {
+  func sayHello(_ i: Int32, _ j: Int32) -> Int32 {
     print("Hello from Swift!")
     let answer = self.sayHelloBack(i + j)
     print("Swift got back \(answer) from Java")
@@ -75,7 +75,7 @@ extension HelloSwift {
   }
 
   @JavaMethod
-  func throwMessageFromSwift(message: String) throws -> String {
+  func throwMessageFromSwift(_ message: String) throws -> String {
     throw SwiftWrappedError.message(message)
   }
 }

Sources/Java2Swift/JavaToSwift.swift

@@ -48,6 +48,11 @@ struct JavaToSwift: ParsableCommand {
   )
   var classpath: [String] = []
 
+  @Option(
+    help: "The names of Java classes whose declared native methods will be implemented in Swift."
+  )
+  var swiftNativeImplementation: [String] = []
+
   @Option(name: .shortAndLong, help: "The directory in which to output the generated Swift files or the Java2Swift configuration file.")
   var outputDirectory: String? = nil
 
@@ -181,6 +186,10 @@ struct JavaToSwift: ParsableCommand {
       environment: environment
     )
 
+    // Keep track of all of the Java classes that will have
+    // Swift-native implementations.
+    translator.swiftNativeImplementations = Set(swiftNativeImplementation)
+
     // Note all of the dependent configurations.
     for (swiftModuleName, dependentConfig) in dependentConfigs {
       translator.addConfiguration(

Sources/Java2SwiftLib/JavaTranslator.swift

@@ -39,6 +39,10 @@ package class JavaTranslator {
   /// import declarations.
   package var importedSwiftModules: Set<String> = JavaTranslator.defaultImportedSwiftModules
 
+  /// The canonical names of Java classes whose declared 'native'
+  /// methods will be implemented in Swift.
+  package var swiftNativeImplementations: Set<String> = []
+
   package init(
     swiftModuleName: String,
     environment: JNIEnvironment,
@@ -229,9 +233,16 @@ extension JavaTranslator {
       interfacesStr = ", \(prefix): \(interfaces.joined(separator: ", "))"
     }
 
+    // The top-level declarations we will be returning.
+    var topLevelDecls: [DeclSyntax] = []
+
     // Members
     var members: [DeclSyntax] = []
-    
+
+    // Members that are native and will instead go into a NativeMethods
+    // protocol.
+    var nativeMembers: [DeclSyntax] = []
+
     // Fields
     var staticFields: [Field] = []
     var enumConstants: [Field] = []
@@ -268,12 +279,22 @@ extension JavaTranslator {
     members.append(
       contentsOf: javaClass.getConstructors().compactMap {
         $0.flatMap { constructor in
-          if constructor.isNative {
-            return nil
-          }
-
           do {
-            return try translateConstructor(constructor)
+            let implementedInSwift = constructor.isNative &&
+              constructor.getDeclaringClass()!.equals(javaClass.as(JavaObject.self)!) &&
+              swiftNativeImplementations.contains(javaClass.getCanonicalName())
+
+            let translated = try translateConstructor(
+              constructor,
+              implementedInSwift: implementedInSwift
+            )
+
+            if implementedInSwift {
+              nativeMembers.append(translated)
+              return nil
+            }
+
+            return translated
           } catch {
             logUntranslated("Unable to translate '\(fullName)' constructor: \(error)")
             return nil
@@ -286,22 +307,31 @@ extension JavaTranslator {
     var staticMethods: [Method] = []
     members.append(
       contentsOf: javaClass.getMethods().compactMap {
-        $0.flatMap { method in
-          if method.isNative {
-            return nil
-          }
-
-
+        $0.flatMap { (method) -> DeclSyntax? in
           // Save the static methods; they need to go on an extension of
           // JavaClass.
           if method.isStatic {
             staticMethods.append(method)
             return nil
           }
 
+          let implementedInSwift = method.isNative &&
+            method.getDeclaringClass()!.equals(javaClass.as(JavaObject.self)!) &&
+            swiftNativeImplementations.contains(javaClass.getCanonicalName())
+
           // Translate the method if we can.
           do {
-            return try translateMethod(method)
+            let translated = try translateMethod(
+              method,
+              implementedInSwift: implementedInSwift
+            )
+
+            if implementedInSwift {
+              nativeMembers.append(translated)
+              return nil
+            }
+
+            return translated
           } catch {
             logUntranslated("Unable to translate '\(fullName)' method '\(method.getName())': \(error)")
             return nil
@@ -356,10 +386,8 @@ extension JavaTranslator {
 
     // Format the class declaration.
     classDecl = classDecl.formatted(using: format).cast(DeclSyntax.self)
-    
-    if staticMethods.isEmpty && staticFields.isEmpty {
-      return [classDecl]
-    }
+
+    topLevelDecls.append(classDecl)
 
     // Translate static members.
     var staticMembers: [DeclSyntax] = []
@@ -381,7 +409,7 @@ extension JavaTranslator {
           // Translate each static method.
           do {
             return try translateMethod(
-              method,
+              method, implementedInSwift: /*FIXME:*/false,
               genericParameterClause: genericParameterClause,
               whereClause: staticMemberWhereClause
             )
@@ -392,46 +420,74 @@ extension JavaTranslator {
         }
     )
 
-    if staticMembers.isEmpty {
-      return [classDecl]
-    }
+    if !staticMembers.isEmpty {
+      // Specify the specialization arguments when needed.
+      let extSpecialization: String
+      if genericParameterClause.isEmpty {
+        extSpecialization = "<\(swiftTypeName)>"
+      } else {
+        extSpecialization = ""
+      }
 
-    // Specify the specialization arguments when needed.
-    let extSpecialization: String
-    if genericParameterClause.isEmpty {
-      extSpecialization = "<\(swiftTypeName)>"
-    } else {
-      extSpecialization = ""
+      let extDecl: DeclSyntax =
+        """
+        extension JavaClass\(raw: extSpecialization) {
+        \(raw: staticMembers.map { $0.description }.joined(separator: "\n\n"))
+        }
+        """
+
+      topLevelDecls.append(
+        extDecl.formatted(using: format).cast(DeclSyntax.self)
+      )
     }
 
-    let extDecl =
-      ("""
-    extension JavaClass\(raw: extSpecialization) {
-    \(raw: staticMembers.map { $0.description }.joined(separator: "\n\n"))
+    if !nativeMembers.isEmpty {
+      let protocolDecl: DeclSyntax =
+        """
+        /// Describes the Java `native` methods for \(raw: swiftTypeName).
+        ///
+        /// To implement all of the `native` methods for \(raw: swiftTypeName) in Swift,
+        /// extend \(raw: swiftTypeName) to conform to this protocol and mark
+        /// each implementation of the protocol requirement with
+        /// `@JavaMethod`.
+        protocol \(raw: swiftTypeName)NativeMethods {
+          \(raw: nativeMembers.map { $0.description }.joined(separator: "\n\n"))
+        }
+        """
+
+      topLevelDecls.append(
+        protocolDecl.formatted(using: format).cast(DeclSyntax.self)
+      )
     }
-    """ as DeclSyntax).formatted(using: format).cast(DeclSyntax.self)
 
-    return [classDecl, extDecl]
+    return topLevelDecls
   }
 }
 
 // MARK: Method and constructor translation
 extension JavaTranslator {
   /// Translates the given Java constructor into a Swift declaration.
-  package func translateConstructor(_ javaConstructor: Constructor<some AnyJavaObject>) throws -> DeclSyntax {
+  package func translateConstructor(
+    _ javaConstructor: Constructor<some AnyJavaObject>,
+    implementedInSwift: Bool
+  ) throws -> DeclSyntax {
     let parameters = try translateParameters(javaConstructor.getParameters()) + ["environment: JNIEnvironment? = nil"]
     let parametersStr = parameters.map { $0.description }.joined(separator: ", ")
     let throwsStr = javaConstructor.throwsCheckedException ? "throws" : ""
 
+    let javaMethodAttribute = implementedInSwift
+      ? ""
+      : "@JavaMethod\n"
+    let accessModifier = implementedInSwift ? "" : "public "
     return """
-      @JavaMethod
-      public init(\(raw: parametersStr))\(raw: throwsStr)
+      \(raw: javaMethodAttribute)\(raw: accessModifier) init(\(raw: parametersStr))\(raw: throwsStr)
       """
   }
 
   /// Translates the given Java method into a Swift declaration.
   package func translateMethod(
     _ javaMethod: Method,
+    implementedInSwift: Bool,
     genericParameterClause: String = "",
     whereClause: String = ""
   ) throws -> DeclSyntax {
@@ -451,10 +507,12 @@ extension JavaTranslator {
 
     let throwsStr = javaMethod.throwsCheckedException ? "throws" : ""
     let swiftMethodName = javaMethod.getName().escapedSwiftName
-    let methodAttribute: AttributeSyntax = javaMethod.isStatic ? "@JavaStaticMethod" : "@JavaMethod";
+    let methodAttribute: AttributeSyntax = implementedInSwift
+      ? ""
+      : javaMethod.isStatic ? "@JavaStaticMethod\n" : "@JavaMethod\n";
+    let accessModifier = implementedInSwift ? "" : "public "
     return """
-      \(methodAttribute)
-      public func \(raw: swiftMethodName)\(raw: genericParameterClause)(\(raw: parametersStr))\(raw: throwsStr)\(raw: resultTypeStr)\(raw: whereClause)
+      \(methodAttribute)\(raw: accessModifier)func \(raw: swiftMethodName)\(raw: genericParameterClause)(\(raw: parametersStr))\(raw: throwsStr)\(raw: resultTypeStr)\(raw: whereClause)
       """
   }
 

Sources/JavaKitReflection/JavaClass+Reflection.swift

@@ -17,6 +17,9 @@ import JavaKit
 // TODO: We should be able to autogenerate this as an extension based on
 // knowing that JavaClass was defined elsewhere.
 extension JavaClass {
+  @JavaMethod
+  public func equals(_ arg0: JavaObject?) -> Bool
+
   @JavaMethod
   public func getName() -> String
 

USER_GUIDE.md

@@ -249,7 +249,7 @@ public class HelloSwift {
 }
 ```
 
-On the Swift side, the Java class needs to have been exposed to Swift through `Java2Swift.config`, e.g.,:
+On the Swift side, the Java class needs to be exposed to Swift through `Java2Swift.config`, e.g.,:
 
 ```swift
 {
@@ -259,11 +259,11 @@ On the Swift side, the Java class needs to have been exposed to Swift through `J
 }
 ```
 
-Implementations of `native` methods are written in an extension of the Swift type that has been marked with `@JavaImplements`. The methods themselves must be marked with `@JavaMethod`, indicating that they are available to Java as well.  For example:
+Implementations of `native` methods are written in an extension of the Swift type that has been marked with `@JavaImplements`. The methods themselves must be marked with `@JavaMethod`, indicating that they are available to Java as well. To help ensure that the Swift code implements all of the `native` methods with the right signatures, JavaKit produces a protocol with the Swift type name suffixed by `NativeMethods`. Declare conformance to that protocol and implement its requirements, for example:
 
 ```swift
 @JavaImplements("org.swift.javakit.HelloSwift")
-extension Hello {
+extension Hello: HelloNativeMethods {
   @JavaMethod
   func reportStatistics(_ meaning: String, _ numbers: [Double]) -> String {
     let average = numbers.isEmpty ? 0.0 : numbers.reduce(0.0) { $0 + $1 } / Double(numbers.count)