FFMSwift2JavaGenerator+JavaTranslation.swift

//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2024-2025 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 SwiftJavaConfigurationShared
import SwiftJavaJNICore

extension FFMSwift2JavaGenerator {
  func translatedDecl(
    for decl: ImportedFunc
  ) -> TranslatedFunctionDecl? {
    if let cached = translatedDecls[decl] {
      return cached
    }

    let translated: TranslatedFunctionDecl?
    do {
      let translation = JavaTranslation(
        config: self.config,
        knownTypes: SwiftKnownTypes(symbolTable: lookupContext.symbolTable),
        javaIdentifiers: self.currentJavaIdentifiers
      )
      translated = try translation.translate(decl)
    } catch {
      self.log.info("Failed to translate: '\(decl.swiftDecl.qualifiedNameForDebug)'; \(error)")
      translated = nil
    }

    translatedDecls[decl] = translated
    return translated
  }

  /// Represent a Swift API parameter translated to Java.
  struct TranslatedParameter {
    /// Java parameter(s) mapped to the Swift parameter.
    ///
    /// Array because one Swift parameter can be mapped to multiple parameters.
    var javaParameters: [JavaParameter]

    /// Describes how to convert the Java parameter to the lowered arguments for
    /// the foreign function.
    var conversion: JavaConversionStep

    /// Whether this parameter requires 32-bit integer overflow checking
    var needs32BitIntOverflowCheck: OverflowCheckType = .none
  }

  enum OverflowCheckType {
    case none
    case signedInt // Int: -2147483648 to 2147483647
    case unsignedInt // UInt: 0 to 4294967295
  }

  /// Represent a Swift API result translated to Java.
  struct TranslatedResult {
    /// Java type that represents the Swift result type.
    var javaResultType: JavaType

    /// Java annotations that should be propagated from the result type onto the method
    var annotations: [JavaAnnotation] = []

    /// Required indirect return receivers for receiving the result.
    ///
    /// 'JavaParameter.name' is the suffix for the receiver variable names. For example
    ///
    ///   var result$_pointer = MemorySegment.allocate(...)
    ///   var result$_count = MemorySegment.allocate(...)
    ///   downCall(result$_pointer, result$_count)
    ///   return constructResult(result$_pointer, result$_count)
    ///
    /// This case, there're two out parameter, named '_pointer' and '_count'.
    var outParameters: [JavaParameter]

    /// Similar to out parameters, but instead of parameters we "fill in" in native,
    /// we create an upcall handle before the downcall and pass it to the downcall.
    /// Swift then invokes the upcall in order to populate some data in Java (our callback).
    ///
    /// After the call is made, we may need to further extact the result from the called-back-into
    /// Java function class, for example:
    ///
    ///   var result$initialize = new result$initialize.Function();
    ///   downCall(result$initialize.toUpcallHandle(result$initialize, arena))
    ///   return result$initialize.result
    ///
    var outCallback: OutCallback?

    /// Describes how to construct the Java result from the foreign function return
    /// value and/or the out parameters.
    var conversion: JavaConversionStep

    /// Whether this result requires 32-bit integer overflow checking
    var needs32BitIntOverflowCheck: OverflowCheckType = .none
  }

  /// Translated Java API representing a Swift API.
  ///
  /// Since this holds the lowered signature, and the original `SwiftFunctionSignature`
  /// in it, this contains all the API information (except the name) to generate the
  /// cdecl thunk, Java binding, and the Java wrapper function.
  struct TranslatedFunctionDecl {
    /// Java function name.
    let name: String

    /// Functional interfaces required for the Java method.
    let functionTypes: [TranslatedFunctionType]

    /// Function signature.
    let translatedSignature: TranslatedFunctionSignature

    /// Cdecl lowered signature.
    let loweredSignature: LoweredFunctionSignature

    /// Annotations to include on the Java function declaration
    var annotations: [JavaAnnotation] {
      self.translatedSignature.annotations
    }
  }

  /// Function signature for a Java API.
  struct TranslatedFunctionSignature {
    var selfParameter: TranslatedParameter?
    var parameters: [TranslatedParameter]
    var result: TranslatedResult
    var isThrowing: Bool = false

    /// Whether any parameter or the result requires a 32-bit integer overflow check,
    /// which means the Java method must declare `throws SwiftIntegerOverflowException`
    var canThrowSwiftIntegerOverflowException: Bool {
      parameters.contains { $0.needs32BitIntOverflowCheck != .none }
        || result.needs32BitIntOverflowCheck != .none
    }

    // if the result type implied any annotations,
    // propagate them onto the function the result is returned from
    var annotations: [JavaAnnotation] {
      self.result.annotations
    }
  }

  /// Represent a Swift closure type in the user facing Java API.
  ///
  /// Closures are translated to named functional interfaces in Java.
  struct TranslatedFunctionType {
    var name: String
    var parameters: [TranslatedParameter]
    var result: TranslatedResult
    var swiftType: SwiftFunctionType
    var cdeclType: SwiftFunctionType

    /// Whether or not this functional interface with C ABI compatible.
    var isCompatibleWithC: Bool {
      result.conversion.isPlaceholder && parameters.allSatisfy(\.conversion.isPlaceholder)
    }
  }

  // ==== -------------------------------------------------------------------
  // MARK: Java translation

  struct JavaTranslation {
    let config: Configuration
    var knownTypes: SwiftKnownTypes
    var javaIdentifiers: JavaIdentifierFactory

    init(config: Configuration, knownTypes: SwiftKnownTypes, javaIdentifiers: JavaIdentifierFactory) {
      self.config = config
      self.knownTypes = knownTypes
      self.javaIdentifiers = javaIdentifiers
    }

    func translate(_ decl: ImportedFunc) throws -> TranslatedFunctionDecl {
      let lowering = CdeclLowering(knownTypes: knownTypes)
      let loweredSignature = try lowering.lowerFunctionSignature(decl.functionSignature)

      // Name.
      let javaName = javaIdentifiers.makeJavaMethodName(decl)

      // Signature.
      let translatedSignature = try translate(loweredFunctionSignature: loweredSignature, methodName: javaName)

      // Closures.
      var funcTypes: [TranslatedFunctionType] = []
      for (idx, param) in decl.functionSignature.parameters.enumerated() {
        switch param.type {
        case .function(let funcTy):
          let paramName = param.parameterName ?? "_\(idx)"
          guard case .function(let cdeclTy) = loweredSignature.parameters[idx].cdeclParameters[0].type else {
            preconditionFailure("closure parameter wasn't lowered to a function type; \(funcTy)")
          }
          let translatedClosure = try translateFunctionType(name: paramName, swiftType: funcTy, cdeclType: cdeclTy)
          funcTypes.append(translatedClosure)
        case .tuple:
          // Tuple-typed closure parameters are not supported (same as JNI / lowering).
          break
        default:
          break
        }
      }

      return TranslatedFunctionDecl(
        name: javaName,
        functionTypes: funcTypes,
        translatedSignature: translatedSignature,
        loweredSignature: loweredSignature
      )
    }

    /// Translate Swift closure type to Java functional interface.
    func translateFunctionType(
      name: String,
      swiftType: SwiftFunctionType,
      cdeclType: SwiftFunctionType
    ) throws -> TranslatedFunctionType {
      var translatedParams: [TranslatedParameter] = []

      for (i, param) in swiftType.parameters.enumerated() {
        let paramName = param.parameterName ?? "_\(i)"
        translatedParams.append(
          try translateClosureParameter(param.type, convention: param.convention, parameterName: paramName)
        )
      }

      guard let resultCType = try? CType(cdeclType: swiftType.resultType) else {
        throw JavaTranslationError.unhandledType(.function(swiftType))
      }

      let transltedResult = TranslatedResult(
        javaResultType: resultCType.javaType,
        outParameters: [],
        conversion: .placeholder
      )

      return TranslatedFunctionType(
        name: name,
        parameters: translatedParams,
        result: transltedResult,
        swiftType: swiftType,
        cdeclType: cdeclType
      )
    }

    func translateClosureParameter(
      _ type: SwiftType,
      convention: SwiftParameterConvention,
      parameterName: String
    ) throws -> TranslatedParameter {
      if let cType = try? CType(cdeclType: type) {
        return TranslatedParameter(
          javaParameters: [
            JavaParameter(name: parameterName, type: cType.javaType)
          ],
          conversion: .placeholder
        )
      }

      switch type {
      case .nominal(let nominal):
        if let knownType = nominal.nominalTypeDecl.knownTypeKind {
          switch knownType {
          case .unsafeRawBufferPointer, .unsafeMutableRawBufferPointer:
            return TranslatedParameter(
              javaParameters: [
                JavaParameter(name: parameterName, type: .javaForeignMemorySegment)
              ],
              conversion: .method(
                .explodedName(component: "pointer"),
                methodName: "reinterpret",
                arguments: [
                  .explodedName(component: "count")
                ],
                withArena: false
              )
            )
          default:
            break
          }
        }
      default:
        break
      }
      throw JavaTranslationError.unhandledType(type)
    }

    /// Translate a Swift API signature to the user-facing Java API signature.
    ///
    /// Note that the result signature is for the high-level Java API, not the
    /// low-level FFM down-calling interface.
    func translate(
      loweredFunctionSignature: LoweredFunctionSignature,
      methodName: String
    ) throws -> TranslatedFunctionSignature {
      let swiftSignature = loweredFunctionSignature.original

      // 'self'
      let selfParameter: TranslatedParameter?
      if case .instance(let convention, let swiftType) = swiftSignature.selfParameter {
        selfParameter = try self.translateParameter(
          type: swiftType,
          convention: convention,
          parameterName: "self",
          loweredParam: loweredFunctionSignature.selfParameter!,
          methodName: methodName,
          genericParameters: swiftSignature.genericParameters,
          genericRequirements: swiftSignature.genericRequirements
        )
      } else {
        selfParameter = nil
      }

      // Regular parameters.
      let parameters: [TranslatedParameter] = try swiftSignature.parameters.enumerated()
        .map { (idx, swiftParam) in
          let loweredParam = loweredFunctionSignature.parameters[idx]
          let parameterName = swiftParam.parameterName ?? "_\(idx)"
          return try self.translateParameter(
            type: swiftParam.type,
            convention: swiftParam.convention,
            parameterName: parameterName,
            loweredParam: loweredParam,
            methodName: methodName,
            genericParameters: swiftSignature.genericParameters,
            genericRequirements: swiftSignature.genericRequirements
          )
        }

      // Result.
      let result = try self.translateResult(
        swiftResult: swiftSignature.result,
        loweredResult: loweredFunctionSignature.result,
        methodName: methodName
      )

      return TranslatedFunctionSignature(
        selfParameter: selfParameter,
        parameters: parameters,
        result: result,
        isThrowing: loweredFunctionSignature.isThrowing
      )
    }

    /// Translate a Swift API parameter to the user-facing Java API parameter.
    func translateParameter(
      type swiftType: SwiftType,
      convention: SwiftParameterConvention,
      parameterName: String,
      loweredParam: LoweredParameter,
      methodName: String,
      genericParameters: [SwiftGenericParameterDeclaration],
      genericRequirements: [SwiftGenericRequirement]
    ) throws -> TranslatedParameter {
      // If the result type should cause any annotations on the method, include them here.
      let parameterAnnotations: [JavaAnnotation] = getTypeAnnotations(swiftType: swiftType, config: config)

      // If there is a 1:1 mapping between this Swift type and a C type, that can
      // be expressed as a Java primitive type.
      if let cType = try? CType(cdeclType: swiftType) {
        let javaType = cType.javaType
        let overflowCheck: OverflowCheckType
        if case .integral(.ptrdiff_t) = cType {
          overflowCheck = .signedInt
        } else if case .integral(.size_t) = cType {
          overflowCheck = .unsignedInt
        } else {
          overflowCheck = .none
        }
        return TranslatedParameter(
          javaParameters: [
            JavaParameter(
              name: parameterName,
              type: javaType,
              annotations: parameterAnnotations
            )
          ],
          conversion: .placeholder,
          needs32BitIntOverflowCheck: overflowCheck
        )
      }

      switch swiftType {
      case .metatype:
        // Metatype are expressed as 'org.swift.swiftkit.SwiftAnyType'
        return TranslatedParameter(
          javaParameters: [
            JavaParameter(
              name: parameterName,
              type: JavaType.class(package: "org.swift.swiftkit.ffm", name: "SwiftAnyType"),
              annotations: parameterAnnotations
            )
          ],
          conversion: .swiftValueSelfSegment(.placeholder)
        )

      case .nominal(let swiftNominalType):
        if let knownType = swiftNominalType.asKnownType {
          if convention == .inout {
            // FIXME: Support non-trivial 'inout' for builtin types.
            throw JavaTranslationError.inoutNotSupported(swiftType)
          }
          switch knownType {
          case .unsafePointer, .unsafeMutablePointer:
            // FIXME: Implement
            throw JavaTranslationError.unhandledType(swiftType)
          case .unsafeBufferPointer, .unsafeMutableBufferPointer:
            // FIXME: Implement
            throw JavaTranslationError.unhandledType(swiftType)

          case .unsafeRawBufferPointer, .unsafeMutableRawBufferPointer:
            return TranslatedParameter(
              javaParameters: [
                JavaParameter(name: parameterName, type: .javaForeignMemorySegment)
              ],
              conversion: .commaSeparated([
                .placeholder,
                .method(.placeholder, methodName: "byteSize", arguments: [], withArena: false),
              ])
            )

          case .optional(let wrapped):
            return try translateOptionalParameter(
              wrappedType: wrapped,
              convention: convention,
              parameterName: parameterName,
              loweredParam: loweredParam,
              methodName: methodName,
              genericParameters: genericParameters,
              genericRequirements: genericRequirements
            )

          case .string:
            return TranslatedParameter(
              javaParameters: [
                JavaParameter(
                  name: parameterName,
                  type: .javaLangString
                )
              ],
              conversion: .call(.placeholder, function: "SwiftStrings.toCString", withArena: true)
            )

          case .array(let element) where element == knownTypes.uint8:
            return TranslatedParameter(
              javaParameters: [
                JavaParameter(name: parameterName, type: .array(.byte), annotations: parameterAnnotations)
              ],
              conversion:
                .commaSeparated([
                  .call(
                    .commaSeparated([.constant("ValueLayout.JAVA_BYTE"), .placeholder]),
                    base: .temporaryArena,
                    function: "allocateFrom",
                    withArena: false // this would pass the arena as last argument, but instead we make a call on the arena
                  ),
                  .property(.placeholder, propertyName: "length"),
                ])
            )

          case .foundationData, .essentialsData:
            return TranslatedParameter(
              javaParameters: [
                JavaParameter(
                  name: parameterName,
                  type: .swiftkitFFMFoundationData
                )
              ],
              conversion: .swiftValueSelfSegment(.placeholder)
            )

          case .swiftJavaError:
            // SwiftJavaError is a class — treat as arbitrary nominal type below
            break

          default:
            throw JavaTranslationError.unhandledType(swiftType)
          }
        }

        // Generic types are not supported yet.
        guard swiftNominalType.genericArguments == nil else {
          throw JavaTranslationError.unhandledType(swiftType)
        }

        return TranslatedParameter(
          javaParameters: [
            JavaParameter(
              name: parameterName,
              type: try translate(swiftType: swiftType)
            )
          ],
          conversion: .swiftValueSelfSegment(.placeholder)
        )

      case .tuple([]):
        return TranslatedParameter(
          javaParameters: [
            JavaParameter(
              name: parameterName,
              type: .void,
              annotations: parameterAnnotations
            )
          ],
          conversion: .placeholder
        )

      case .tuple(let elements):
        return try translateTupleParameter(
          elements: elements,
          convention: convention,
          parameterName: parameterName,
          methodName: methodName,
          genericParameters: genericParameters,
          genericRequirements: genericRequirements
        )

      case .function:
        return TranslatedParameter(
          javaParameters: [
            JavaParameter(
              name: parameterName,
              type: JavaType.class(package: nil, name: "\(methodName).\(parameterName)")
            )
          ],
          conversion: .call(.placeholder, function: "\(methodName).$toUpcallStub", withArena: true)
        )

      case .existential, .opaque, .genericParameter:
        if let concreteTy = swiftType.representativeConcreteTypeIn(
          knownTypes: knownTypes,
          genericParameters: genericParameters,
          genericRequirements: genericRequirements
        ) {
          return try translateParameter(
            type: concreteTy,
            convention: convention,
            parameterName: parameterName,
            loweredParam: loweredParam,
            methodName: methodName,
            genericParameters: genericParameters,
            genericRequirements: genericRequirements
          )
        }

        // Otherwise, not supported yet.
        throw JavaTranslationError.unhandledType(swiftType)

      case .composite:
        throw JavaTranslationError.unhandledType(swiftType)
      }
    }

    /// Tuple parameters: one `TupleN<…>` on the Java API; conversion reads `.$0`, `.$1`, … (mirrors JNI).
    func translateTupleParameter(
      elements: [SwiftTupleElement],
      convention: SwiftParameterConvention,
      parameterName: String,
      methodName: String,
      genericParameters: [SwiftGenericParameterDeclaration],
      genericRequirements: [SwiftGenericRequirement]
    ) throws -> TranslatedParameter {
      let lowering = CdeclLowering(knownTypes: knownTypes)
      var elementJavaTypes: [JavaType] = []
      var elementConversions: [JavaConversionStep] = []

      for (idx, element) in elements.enumerated() {
        let subLowered = try lowering.lowerParameter(
          element.type,
          convention: convention,
          parameterName: "\(parameterName)_\(idx)",
          genericParameters: genericParameters,
          genericRequirements: genericRequirements
        )
        let elementTranslated = try translateParameter(
          type: element.type,
          convention: convention,
          parameterName: "\(parameterName)_\(idx)",
          loweredParam: subLowered,
          methodName: methodName,
          genericParameters: genericParameters,
          genericRequirements: genericRequirements
        )
        guard elementTranslated.javaParameters.count == 1 else {
          throw JavaTranslationError.unhandledType(element.type)
        }
        let extraction = JavaConversionStep.replacingPlaceholder(
          elementTranslated.conversion,
          placeholder: "\(parameterName).$\(idx)"
        )
        elementConversions.append(extraction)
        elementJavaTypes.append(elementTranslated.javaParameters[0].type.javaType)
      }

      let javaType: JavaType = .tuple(elementTypes: elementJavaTypes)
      return TranslatedParameter(
        javaParameters: [
          JavaParameter(name: parameterName, type: javaType)
        ],
        conversion: .commaSeparated(elementConversions)
      )
    }

    /// Translate an Optional Swift API parameter to the user-facing Java API parameter.
    func translateOptionalParameter(
      wrappedType swiftType: SwiftType,
      convention: SwiftParameterConvention,
      parameterName: String,
      loweredParam: LoweredParameter,
      methodName: String,
      genericParameters: [SwiftGenericParameterDeclaration],
      genericRequirements: [SwiftGenericRequirement]
    ) throws -> TranslatedParameter {
      // If there is a 1:1 mapping between this Swift type and a C type, that can
      // be expressed as a Java primitive type.
      if let cType = try? CType(cdeclType: swiftType) {
        let (translatedClass, lowerFunc) =
          switch cType.javaType {
          case .int: ("OptionalInt", "toOptionalSegmentInt")
          case .long: ("OptionalLong", "toOptionalSegmentLong")
          case .double: ("OptionalDouble", "toOptionalSegmentDouble")
          case .boolean: ("Optional<Boolean>", "toOptionalSegmentBoolean")
          case .byte: ("Optional<Byte>", "toOptionalSegmentByte")
          case .char: ("Optional<Character>", "toOptionalSegmentCharacter")
          case .short: ("Optional<Short>", "toOptionalSegmentShort")
          case .float: ("Optional<Float>", "toOptionalSegmentFloat")
          default: throw JavaTranslationError.unhandledType(known: .optional(swiftType))
          }
        return TranslatedParameter(
          javaParameters: [
            JavaParameter(name: parameterName, type: JavaType(className: translatedClass))
          ],
          conversion: .call(.placeholder, function: "SwiftRuntime.\(lowerFunc)", withArena: true)
        )
      }

      switch swiftType {
      case .nominal(let nominal):
        if let knownType = nominal.nominalTypeDecl.knownTypeKind {
          switch knownType {
          case .foundationData, .essentialsData:
            return TranslatedParameter(
              javaParameters: [
                JavaParameter(
                  name: parameterName,
                  type: .optional(.swiftkitFFMFoundationData)
                )
              ],
              conversion: .call(.placeholder, function: "SwiftRuntime.toOptionalSegmentInstance", withArena: false)
            )
          case .foundationDataProtocol, .essentialsDataProtocol:
            return TranslatedParameter(
              javaParameters: [
                JavaParameter(
                  name: parameterName,
                  type: .optional(.swiftkitFFMFoundationDataProtocol)
                )
              ],
              conversion: .call(.placeholder, function: "SwiftRuntime.toOptionalSegmentInstance", withArena: false)
            )
          default:
            throw JavaTranslationError.unhandledType(known: .optional(swiftType))
          }
        }

        let translatedTy = try self.translate(swiftType: swiftType)
        return TranslatedParameter(
          javaParameters: [
            JavaParameter(name: parameterName, type: .optional(translatedTy))
          ],
          conversion: .call(.placeholder, function: "SwiftRuntime.toOptionalSegmentInstance", withArena: false)
        )
      case .existential, .opaque, .genericParameter:
        if let concreteTy = swiftType.representativeConcreteTypeIn(
          knownTypes: knownTypes,
          genericParameters: genericParameters,
          genericRequirements: genericRequirements
        ) {
          return try translateOptionalParameter(
            wrappedType: concreteTy,
            convention: convention,
            parameterName: parameterName,
            loweredParam: loweredParam,
            methodName: methodName,
            genericParameters: genericParameters,
            genericRequirements: genericRequirements
          )
        }
        throw JavaTranslationError.unhandledType(known: .optional(swiftType))
      case .tuple(let tuple):
        if tuple.count == 1 {
          return try translateOptionalParameter(
            wrappedType: tuple[0].type,
            convention: convention,
            parameterName: parameterName,
            loweredParam: loweredParam,
            methodName: methodName,
            genericParameters: genericParameters,
            genericRequirements: genericRequirements
          )
        }
        throw JavaTranslationError.unhandledType(known: .optional(swiftType))
      default:
        throw JavaTranslationError.unhandledType(known: .optional(swiftType))
      }
    }

    /// Translate a Swift API result to the user-facing Java API result.
    func translateResult(
      swiftResult: SwiftResult,
      loweredResult: LoweredResult,
      methodName: String
    ) throws -> TranslatedResult {
      let swiftType = swiftResult.type
      // If the result type should cause any annotations on the method, include them here.
      let resultAnnotations: [JavaAnnotation] = getTypeAnnotations(swiftType: swiftType, config: config)

      // If there is a 1:1 mapping between this Swift type and a C type, that can
      // be expressed as a Java primitive type.
      if let cType = try? CType(cdeclType: swiftType) {
        let javaType = cType.javaType
        let overflowCheck: OverflowCheckType
        if case .integral(.ptrdiff_t) = cType {
          overflowCheck = .signedInt
        } else if case .integral(.size_t) = cType {
          overflowCheck = .unsignedInt
        } else {
          overflowCheck = .none
        }
        return TranslatedResult(
          javaResultType: javaType,
          annotations: resultAnnotations,
          outParameters: [],
          conversion: .placeholder,
          needs32BitIntOverflowCheck: overflowCheck
        )
      }

      switch swiftType {
      case .metatype(_):
        // Metatype are expressed as 'org.swift.swiftkit.SwiftAnyType'
        let javaType = JavaType.class(package: "org.swift.swiftkit.ffm", name: "SwiftAnyType")
        return TranslatedResult(
          javaResultType: javaType,
          annotations: resultAnnotations,
          outParameters: [],
          conversion: .construct(.placeholder, javaType)
        )

      case .nominal(let swiftNominalType):
        if let knownType = swiftNominalType.asKnownType {
          switch knownType {
          case .unsafeRawBufferPointer, .unsafeMutableRawBufferPointer:
            return TranslatedResult(
              javaResultType: .javaForeignMemorySegment,
              annotations: resultAnnotations,
              outParameters: [
                JavaParameter(name: "pointer", type: .javaForeignMemorySegment),
                JavaParameter(name: "count", type: .long),
              ],
              conversion: .method(
                .readMemorySegment(.explodedName(component: "pointer"), as: .javaForeignMemorySegment),
                methodName: "reinterpret",
                arguments: [
                  .readMemorySegment(.explodedName(component: "count"), as: .long)
                ],
                withArena: false
              )
            )

          case .foundationData, .essentialsData:
            let javaType: JavaType = .swiftkitFFMFoundationData
            return TranslatedResult(
              javaResultType: javaType,
              annotations: resultAnnotations,
              outParameters: [
                JavaParameter(name: "", type: javaType)
              ],
              conversion: .wrapMemoryAddressUnsafe(.placeholder, javaType)
            )

          case .unsafePointer, .unsafeMutablePointer:
            // FIXME: Implement
            throw JavaTranslationError.unhandledType(swiftType)
          case .unsafeBufferPointer, .unsafeMutableBufferPointer:
            // FIXME: Implement
            throw JavaTranslationError.unhandledType(swiftType)
          case .string:
            return TranslatedResult(
              javaResultType: .javaLangString,
              annotations: resultAnnotations,
              outParameters: [],
              conversion: .call(.placeholder, function: "SwiftStrings.fromCString", withArena: false)
            )

          case .array(let element) where element == knownTypes.uint8:
            return TranslatedResult(
              javaResultType:
                .array(.byte),
              annotations: [.unsigned],
              outParameters: [], // no out parameters, but we do an "out" callback
              outCallback: OutCallback(
                name: "result$initialize",
                members: [
                  "byte[] result = null"
                ],
                parameters: [
                  JavaParameter(name: "pointer", type: .javaForeignMemorySegment),
                  JavaParameter(name: "count", type: .long),
                ],
                cFunc: CFunction(
                  resultType: .void,
                  name: "apply",
                  parameters: [
                    CParameter(type: .pointer(.void)),
                    CParameter(type: .integral(.size_t)),
                  ],
                  isVariadic: false
                ),
                body:
                  "this.result = _0.reinterpret(_1).toArray(ValueLayout.JAVA_BYTE); // copy native Swift array to Java heap array"
              ),
              conversion: .initializeResultWithUpcall(
                [
                  .introduceVariable(
                    name: "result$initialize",
                    initializeWith: .javaNew(
                      .commaSeparated(
                        [
                          // We need to refer to the nested class that is created for this function.
                          // The class that contains all the related functional interfaces is called the same
                          // as the downcall function, so we use the thunk name to find this class/
                          .placeholderForSwiftThunkName, .constant("result$initialize.Function$Impl()"),
                        ],
                        separator: "."
                      )
                    )
                  ),
                  .placeholderForDowncall, // perform the downcall here
                ],
                extractResult: .property(.constant("result$initialize"), propertyName: "result")
              )
            )

          default:
            throw JavaTranslationError.unhandledType(swiftType)
          }
        }

        // Generic types are not supported yet.
        guard swiftNominalType.genericArguments == nil else {
          throw JavaTranslationError.unhandledType(swiftType)
        }

        let javaType: JavaType = .class(package: nil, name: swiftNominalType.nominalTypeDecl.qualifiedName)
        return TranslatedResult(
          javaResultType: javaType,
          annotations: resultAnnotations,
          outParameters: [
            JavaParameter(name: "", type: javaType)
          ],
          conversion: .wrapMemoryAddressUnsafe(.placeholder, javaType)
        )

      case .tuple([]):
        return TranslatedResult(
          javaResultType: .void,
          annotations: resultAnnotations,
          outParameters: [],
          conversion: .placeholder
        )

      case .tuple(let elements):
        return try translateTupleResult(
          methodName: methodName,
          elements: elements,
          resultAnnotations: resultAnnotations
        )

      case .genericParameter, .function, .existential, .opaque, .composite:
        throw JavaTranslationError.unhandledType(swiftType)
      }

    }

    /// Tuple results: indirect `MemorySegment` per element, then `new TupleN<…>(…)` (mirrors JNI out-arrays).
    func translateTupleResult(
      methodName: String,
      elements: [SwiftTupleElement],
      resultAnnotations: [JavaAnnotation]
    ) throws -> TranslatedResult {
      var outParameters: [JavaParameter] = []
      var tupleElements: [(outParamName: String, elementConversion: JavaConversionStep)] = []
      var elementJavaTypes: [JavaType] = []

      for (idx, element) in elements.enumerated() {
        let (javaType, elementConversion) = try translateTupleElementResult(type: element.type)
        outParameters.append(JavaParameter(name: "\(idx)", type: javaType))
        tupleElements.append((outParamName: "result$_\(idx)", elementConversion: elementConversion))
        elementJavaTypes.append(javaType)
      }

      let javaResultType: JavaType = .tuple(elementTypes: elementJavaTypes)
      let fullTupleClassName = javaResultType.fullyQualifiedClassName!

      return TranslatedResult(
        javaResultType: javaResultType,
        annotations: resultAnnotations,
        outParameters: outParameters,
        conversion: .tupleFromOutParams(
          tupleClassName: "new \(fullTupleClassName)",
          elements: tupleElements
        )
      )
    }

    /// Single tuple element for the Java result (mirrors JNI `translateTupleElementResult`).
    private func translateTupleElementResult(type: SwiftType) throws -> (JavaType, JavaConversionStep) {
      switch type {
      case .nominal(let nominalType):
        if nominalType.nominalTypeDecl.knownTypeKind != nil {
          if let cType = try? CType(cdeclType: type) {
            return (cType.javaType, .readMemorySegment(.placeholder, as: cType.javaType))
          }
          throw JavaTranslationError.unhandledType(type)
        }

        guard !nominalType.isSwiftJavaWrapper else {
          throw JavaTranslationError.unhandledType(type)
        }

        let javaType: JavaType = .class(package: nil, name: nominalType.nominalTypeDecl.qualifiedName)
        return (javaType, .wrapMemoryAddressUnsafe(.placeholder, javaType))

      default:
        throw JavaTranslationError.unhandledType(type)
      }
    }

    func translate(
      swiftType: SwiftType
    ) throws -> JavaType {
      guard let nominalName = swiftType.asNominalTypeDeclaration?.name else {
        throw JavaTranslationError.unhandledType(swiftType)
      }
      return .class(package: nil, name: nominalName)
    }
  }

  /// Describes how to convert values between Java types and FFM types.
  enum JavaConversionStep {
    /// The input
    case placeholder

    /// The "downcall", e.g. `swiftjava_SwiftModule_returnArray.call(...)`.
    /// This can be used in combination with aggregate conversion steps to prepare a setup and processing of the downcall.
    case placeholderForDowncall

    /// Placeholder for Swift thunk name, e.g. "swiftjava_SwiftModule_returnArray".
    ///
    /// This is derived from the placeholderForDowncall substitution - could be done more cleanly,
    /// however this has the benefit of not needing to pass the name substituion separately.
    case placeholderForSwiftThunkName

    /// The temporary `arena$` that is necessary to complete the conversion steps.
    ///
    /// This is distinct from just a constant 'arena$' string, since it forces the creation of a temporary arena.
    case temporaryArena

    /// The input exploded into components.
    case explodedName(component: String)

    /// A fixed value
    case constant(String)

    /// The result of the function will be initialized with a callback to Java (an upcall).
    ///
    /// The `extractResult` is used for the actual `return ...` statement, because we need to extract
    /// the return value from the called back into class, e.g. `return result$initialize.result`.
    indirect case initializeResultWithUpcall([JavaConversionStep], extractResult: JavaConversionStep)

    /// 'value.$memorySegment()'
    indirect case swiftValueSelfSegment(JavaConversionStep)

    /// Call specified function using the placeholder as arguments.
    ///
    /// The 'base' is if the call should be performed as 'base.function',
    /// otherwise the function is assumed to be a free function.
    ///
    /// If `withArena` is true, `arena$` argument is added.
    indirect case call(JavaConversionStep, base: JavaConversionStep?, function: String, withArena: Bool)

    static func call(_ step: JavaConversionStep, function: String, withArena: Bool) -> Self {
      .call(step, base: nil, function: function, withArena: withArena)
    }

    // TODO: just use make call more powerful and use it instead?
    /// Apply a method on the placeholder.
    /// If `withArena` is true, `arena$` argument is added.
    indirect case method(JavaConversionStep, methodName: String, arguments: [JavaConversionStep] = [], withArena: Bool)

    /// Fetch a property from the placeholder.
    /// Similar to 'method', however for a property i.e. without adding the '()' after the name
    indirect case property(JavaConversionStep, propertyName: String)

    /// Call 'new \(Type)(\(placeholder), swiftArena)'.
    indirect case constructSwiftValue(JavaConversionStep, JavaType)

    /// Construct the type using the placeholder as arguments.
    indirect case construct(JavaConversionStep, JavaType)

    /// Call the `MyType.wrapMemoryAddressUnsafe` in order to wrap a memory address using the Java binding type
    indirect case wrapMemoryAddressUnsafe(JavaConversionStep, JavaType)

    /// Introduce a local variable, e.g. `var result = new Something()`
    indirect case introduceVariable(name: String, initializeWith: JavaConversionStep)

    /// Casting the placeholder to the certain type.
    indirect case cast(JavaConversionStep, JavaType)

    /// Prefix the conversion step with a java `new`.
    ///
    /// This is useful if constructing the value is complex and we use
    /// a combination of separated values and constants to do so; Generally prefer using `construct`
    /// if you only want to construct a "wrapper" for the current `.placeholder`.
    indirect case javaNew(JavaConversionStep)

    /// Convert the results of the inner steps to a comma separated list.
    indirect case commaSeparated([JavaConversionStep], separator: String = ", ")

    /// Refer an exploded argument suffixed with `_\(name)`.
    indirect case readMemorySegment(JavaConversionStep, as: JavaType)

    /// Use `placeholder` as the root when rendering `inner` (same idea as JNI `replacingPlaceholder`).
    indirect case replacingPlaceholder(JavaConversionStep, placeholder: String)

    /// Build `org.swift.swiftkit.core.tuple.TupleN` from indirect `MemorySegment` out params (JNI `tupleFromOutParams`).
    case tupleFromOutParams(
      tupleClassName: String,
      elements: [(outParamName: String, elementConversion: JavaConversionStep)]
    )

    var isPlaceholder: Bool {
      if case .placeholder = self { true } else { false }
    }
  }
}

extension FFMSwift2JavaGenerator.TranslatedFunctionSignature {
  /// Whether or not if the down-calling requires temporary "Arena" which is
  /// only used during the down-calling.
  var requiresTemporaryArena: Bool {
    if self.isThrowing {
      return true
    }
    if self.parameters.contains(where: { $0.conversion.requiresTemporaryArena }) {
      return true
    }
    if self.selfParameter?.conversion.requiresTemporaryArena ?? false {
      return true
    }
    if self.result.conversion.requiresTemporaryArena {
      return true
    }
    return false
  }

  /// Whether if the down-calling requires "SwiftArena" or not, which should be
  /// passed-in by the API caller. This is needed if the API returns a `SwiftValue`
  var requiresSwiftArena: Bool {
    self.result.conversion.requiresSwiftArena
  }
}

extension CType {
  /// Map lowered C type to Java type for FFM binding.
  var javaType: JavaType {
    switch self {
    case .void: return .void

    case .integral(.bool): return .boolean
    case .integral(.signed(bits: 8)): return .byte
    case .integral(.signed(bits: 16)): return .short
    case .integral(.signed(bits: 32)): return .int
    case .integral(.signed(bits: 64)): return .long
    case .integral(.unsigned(bits: 8)): return .byte
    case .integral(.unsigned(bits: 16)): return .char // char is Java's only unsigned primitive, we can use it!
    case .integral(.unsigned(bits: 32)): return .int
    case .integral(.unsigned(bits: 64)): return .long

    case .floating(.float): return .float
    case .floating(.double): return .double

    // FIXME: 32 bit consideration.
    // The 'FunctionDescriptor' uses 'SWIFT_INT' which relies on the running
    // machine arch. That means users can't pass Java 'long' values to the
    // function without casting. But how do we generate code that runs both
    // 32 and 64 bit machine?
    case .integral(.ptrdiff_t), .integral(.size_t):
      return .long

    case .pointer(_), .function(resultType: _, parameters: _, variadic: _):
      return .javaForeignMemorySegment

    case .qualified(const: _, volatile: _, let inner):
      return inner.javaType

    case .tag(_):
      fatalError("unsupported")
    case .integral(.signed(bits: _)), .integral(.unsigned(bits: _)):
      fatalError("unreachable")
    }
  }

  /// Map lowered C type to FFM ValueLayout.
  var foreignValueLayout: ForeignValueLayout {
    switch self {
    case .integral(.bool): return .SwiftBool
    case .integral(.signed(bits: 8)): return .SwiftInt8
    case .integral(.signed(bits: 16)): return .SwiftInt16
    case .integral(.signed(bits: 32)): return .SwiftInt32
    case .integral(.signed(bits: 64)): return .SwiftInt64

    case .integral(.unsigned(bits: 8)): return .SwiftUInt8
    case .integral(.unsigned(bits: 16)): return .SwiftUInt16
    case .integral(.unsigned(bits: 32)): return .SwiftUInt32
    case .integral(.unsigned(bits: 64)): return .SwiftUInt64

    case .floating(.double): return .SwiftDouble
    case .floating(.float): return .SwiftFloat

    case .integral(.ptrdiff_t), .integral(.size_t):
      return .SwiftInt

    case .pointer(_), .function(resultType: _, parameters: _, variadic: _):
      return .SwiftPointer

    case .qualified(const: _, volatile: _, type: let inner):
      return inner.foreignValueLayout

    case .tag(_):
      fatalError("unsupported")
    case .void, .integral(.signed(bits: _)), .integral(.unsigned(bits: _)):
      fatalError("unreachable")
    }
  }
}

enum JavaTranslationError: Error {
  case inoutNotSupported(SwiftType, file: String = #file, line: Int = #line)
  case unhandledType(SwiftType, file: String = #file, line: Int = #line)
  case unhandledType(known: SwiftKnownType, file: String = #file, line: Int = #line)
}