feat(javagen): generate Java adapter classes for abstract callback classes

The specgen now detects abstract classes (e.g. ScanCallback,
BluetoothGattCallback) and emits abstract_callbacks entries in the YAML
specs. The javagen reads these entries and generates Java adapter classes
that extend the abstract class, delegating all methods to
GoAbstractDispatch.invoke(handlerID, methodName, args). The generated
adapters are placed in a java/ subdirectory alongside the Go output and
follow the center.dx.jni.generated package convention.

The adapter naming (SimpleClassName + "Adapter") matches the naming
convention that tryAbstractAdapter in proxy.go already searches for,
so no changes to the runtime proxy fallback logic are needed beyond
adding a secondary search pattern.

Author: xaionaro@dx.center

proxy.go

@@ -547,9 +547,12 @@ func tryAbstractAdapter(
 		simpleName = fullName[idx+1:]
 	}
 
-	// Try adapter class names.
+	// Try adapter class names. The first pattern matches adapters generated
+	// by javagen (e.g. ScanCallbackAdapter). The second pattern matches
+	// the legacy hand-written naming in the gatt repo.
 	adapterNames := []string{
 		"center/dx/jni/generated/" + simpleName + "Adapter",
+		"center/dx/jni/generated/Go" + simpleName + "Adapter",
 		"center/dx/gatt/internal/Go" + simpleName,
 	}
 

templates/java/abstract_adapter.java.tmpl

@@ -0,0 +1,24 @@
+package center.dx.jni.generated;
+
+import {{.JavaClass}};
+import center.dx.jni.internal.GoAbstractDispatch;
+
+public class {{.AdapterClassName}} extends {{.JavaClass}} {
+    private final long handlerID;
+
+    public {{.AdapterClassName}}(long handlerID) {
+        this.handlerID = handlerID;
+    }
+{{range .Methods}}
+    @Override
+    public {{.JavaReturnType}} {{.JavaMethod}}({{.JavaParamList}}) {
+        {{- if .HasReturn}}
+        return {{.JavaCastReturn}} GoAbstractDispatch.invoke(
+            handlerID, "{{.JavaMethod}}", new Object[]{ {{.JavaArgList}} }){{.JavaUnboxReturn}};
+        {{- else}}
+        GoAbstractDispatch.invoke(
+            handlerID, "{{.JavaMethod}}", new Object[]{ {{.JavaArgList}} });
+        {{- end}}
+    }
+{{end -}}
+}

tools/pkg/javagen/abstract_callback.go

@@ -0,0 +1,9 @@
+package javagen
+
+// AbstractCallback describes an abstract Java class whose abstract methods
+// are delegated to Go via GoAbstractDispatch.
+type AbstractCallback struct {
+	JavaClass string                   `yaml:"java_class"`
+	GoType    string                   `yaml:"go_type"`
+	Methods   []AbstractCallbackMethod `yaml:"methods"`
+}

tools/pkg/javagen/abstract_callback_method.go

@@ -0,0 +1,9 @@
+package javagen
+
+// AbstractCallbackMethod describes a single abstract method in an abstract callback class.
+type AbstractCallbackMethod struct {
+	JavaMethod string   `yaml:"java_method"`
+	Params     []string `yaml:"params"`
+	Returns    string   `yaml:"returns"`
+	GoField    string   `yaml:"go_field"`
+}

tools/pkg/javagen/abstract_callback_render.go

@@ -0,0 +1,90 @@
+package javagen
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"path/filepath"
+	"text/template"
+)
+
+// javaGeneratedHeader is prepended to all generated Java files.
+var javaGeneratedHeader = "// Code generated by javagen. DO NOT " + "EDIT.\n\n"
+
+// renderAbstractAdapters generates a Java adapter class for each abstract
+// callback. The Java files are placed in a java/ subdirectory alongside the
+// Go output, and follow the center.dx.jni.generated package convention.
+func renderAbstractAdapters(
+	templatesDir string,
+	merged *MergedSpec,
+	pkgDir string,
+) error {
+	tmplPath := filepath.Join(templatesDir, "abstract_adapter.java.tmpl")
+	tmplData, err := os.ReadFile(tmplPath)
+	if err != nil {
+		// Template not found: nothing to render.
+		return nil
+	}
+
+	funcMap := template.FuncMap{
+		"javaClassToSlash": JavaClassToSlash,
+	}
+
+	tmpl, err := template.New("abstract_adapter.java.tmpl").Funcs(funcMap).Parse(string(tmplData))
+	if err != nil {
+		return fmt.Errorf("parse abstract adapter template: %w", err)
+	}
+
+	javaDir := filepath.Join(pkgDir, "java")
+	if err := os.MkdirAll(javaDir, dirPerm); err != nil {
+		return fmt.Errorf("mkdir java: %w", err)
+	}
+
+	cleanStaleJavaFiles(javaDir)
+
+	for i := range merged.AbstractCallbacks {
+		acb := &merged.AbstractCallbacks[i]
+		outputFile := filepath.Join(javaDir, acb.AdapterClassName()+".java")
+		if err := renderJavaTemplate(tmpl, acb, outputFile); err != nil {
+			return fmt.Errorf("render adapter %s: %w", acb.GoType, err)
+		}
+	}
+
+	return nil
+}
+
+// renderJavaTemplate executes a Java template and writes the result.
+func renderJavaTemplate(
+	tmpl *template.Template,
+	data any,
+	outputPath string,
+) error {
+	var buf bytes.Buffer
+	if err := tmpl.Execute(&buf, data); err != nil {
+		return fmt.Errorf("execute template: %w", err)
+	}
+
+	src := javaGeneratedHeader + buf.String()
+	return os.WriteFile(outputPath, []byte(src), filePerm)
+}
+
+// cleanStaleJavaFiles removes generated .java files from a directory.
+func cleanStaleJavaFiles(dir string) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	for _, e := range entries {
+		if e.IsDir() || filepath.Ext(e.Name()) != ".java" {
+			continue
+		}
+		path := filepath.Join(dir, e.Name())
+		data, err := os.ReadFile(path)
+		if err != nil {
+			continue
+		}
+		if bytes.Contains(data, []byte("Code generated by javagen. DO NOT EDIT.")) {
+			_ = os.Remove(path)
+		}
+	}
+}

tools/pkg/javagen/e2e_test.go

@@ -428,6 +428,84 @@ func TestGenerate_ContentPatterns(t *testing.T) {
 	}
 }
 
+// TestGenerate_AbstractCallbackAdapters verifies that abstract callback
+// entries in a spec produce Java adapter files in a java/ subdirectory.
+func TestGenerate_AbstractCallbackAdapters(t *testing.T) {
+	root := findRepoRoot(t)
+	templatesDir := filepath.Join(root, "templates", "java")
+	outputDir := t.TempDir()
+
+	specYAML := `
+package: test_le
+go_import: github.com/AndroidGoLab/jni/test_le
+classes:
+  - java_class: android.bluetooth.le.BluetoothLeScanner
+    go_type: Scanner
+    methods:
+      - java_method: startScan
+        go_name: StartScan
+        params:
+          - java_type: android.bluetooth.le.ScanCallback
+            go_name: arg0
+        returns: void
+        error: true
+abstract_callbacks:
+  - java_class: android.bluetooth.le.ScanCallback
+    go_type: ScanCallbackCB
+    methods:
+      - java_method: onScanFailed
+        params:
+          - int
+        returns: void
+        go_field: OnScanFailed
+      - java_method: onScanResult
+        params:
+          - int
+          - android.bluetooth.le.ScanResult
+        returns: void
+        go_field: OnScanResult
+`
+	specPath := filepath.Join(t.TempDir(), "test.yaml")
+	if err := os.WriteFile(specPath, []byte(specYAML), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	overlayPath := filepath.Join(t.TempDir(), "nonexistent.yaml")
+	if err := Generate(specPath, overlayPath, templatesDir, outputDir, testGoModule); err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+
+	// Verify Java adapter file was generated.
+	javaFile := filepath.Join(outputDir, "test_le", "java", "ScanCallbackAdapter.java")
+	data, err := os.ReadFile(javaFile)
+	if err != nil {
+		t.Fatalf("expected Java adapter file at %s: %v", javaFile, err)
+	}
+
+	content := string(data)
+	if !strings.Contains(content, "Code generated by javagen. DO NOT EDIT.") {
+		t.Error("missing generated header")
+	}
+	if !strings.Contains(content, "extends android.bluetooth.le.ScanCallback") {
+		t.Error("missing extends clause")
+	}
+	if !strings.Contains(content, "ScanCallbackAdapter") {
+		t.Error("missing adapter class name")
+	}
+	if !strings.Contains(content, "GoAbstractDispatch.invoke") {
+		t.Error("missing GoAbstractDispatch.invoke")
+	}
+	if !strings.Contains(content, `"onScanFailed"`) {
+		t.Error("missing onScanFailed dispatch")
+	}
+	if !strings.Contains(content, `"onScanResult"`) {
+		t.Error("missing onScanResult dispatch")
+	}
+	if !strings.Contains(content, "Integer.valueOf(arg0)") {
+		t.Error("missing int autoboxing")
+	}
+}
+
 func readFile(t *testing.T, path string) string {
 	t.Helper()
 	data, err := os.ReadFile(path)

tools/pkg/javagen/merge.go

@@ -53,6 +53,11 @@ func Merge(spec *Spec, overlay *Overlay) (*MergedSpec, error) {
 		merged.Callbacks = append(merged.Callbacks, *mcb)
 	}
 
+	for _, acb := range spec.AbstractCallbacks {
+		macb := mergeAbstractCallback(&acb, overlay)
+		merged.AbstractCallbacks = append(merged.AbstractCallbacks, *macb)
+	}
+
 	merged.ConstantGroups = mergeConstants(spec.Constants)
 
 	resolveConstantTypeCollisions(merged)
@@ -316,6 +321,45 @@ func mergeCallback(cb *Callback, overlay *Overlay) (*MergedCallback, error) {
 	return mcb, nil
 }
 
+func mergeAbstractCallback(acb *AbstractCallback, overlay *Overlay) *MergedAbstractCallback {
+	macb := &MergedAbstractCallback{
+		JavaClass:      acb.JavaClass,
+		JavaClassSlash: JavaClassToSlash(acb.JavaClass),
+		GoType:         acb.GoType,
+	}
+
+	for _, m := range acb.Methods {
+		var params []MergedParam
+		for i, jt := range m.Params {
+			goName := fmt.Sprintf("arg%d", i)
+			isString := jt == "String" || jt == "java.lang.String" || jt == "java.lang.CharSequence" || jt == "CharSequence"
+			goType := "*jni.Object"
+			if isString {
+				goType = "string"
+			}
+			params = append(params, MergedParam{
+				JavaType: jt,
+				GoName:   goName,
+				GoType:   goType,
+				IsString: isString,
+				IsObject: true,
+			})
+		}
+
+		goParams := buildGoParamList(params)
+
+		macb.Methods = append(macb.Methods, MergedAbstractCallbackMethod{
+			JavaMethod: m.JavaMethod,
+			GoField:    m.GoField,
+			Params:     params,
+			GoParams:   goParams,
+			Returns:    m.Returns,
+		})
+	}
+
+	return macb
+}
+
 // deriveJavaPackageDesc extracts the Java package name from the first
 // class in the spec to produce a human-readable description for the
 // doc.go package comment. Returns the Java package (e.g.
@@ -429,6 +473,9 @@ func resolveConstantTypeCollisions(merged *MergedSpec) {
 	for _, cb := range merged.Callbacks {
 		typeNames[cb.GoType] = struct{}{}
 	}
+	for _, acb := range merged.AbstractCallbacks {
+		typeNames[acb.GoType] = struct{}{}
+	}
 	for _, grp := range merged.ConstantGroups {
 		if grp.GoType != "" {
 			typeNames[grp.GoType] = struct{}{}