Merge pull request #28159 from asmorkalov:as/java_cleaners

Introduce option to generate Java code with finalize() or Cleaners interface #28159
 
Closes https://github.com/opencv/opencv/issues/22260
Replaces https://github.com/opencv/opencv/pull/23467

The PR introduce configuration option to generate Java code with Cleaner interface for Java 9+ and old-fashion finalize() method for old Java and Android. Mat class and derivatives are manually written. The PR introduce 2 base classes for it depending on the generator configuration.

Pros:
1. No need to implement complex and error prone cleaner on library side.
2. No new CMake templates, easier to modify code in IDE.

Cons:
1. More generator branches and different code for modern desktop and Android.

TODO: 
- [x] Add Java version check to cmake
- [x] Use Cleaners for ANDROID API 33+

### Pull Request Readiness Checklist

See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request

- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [ ] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
      Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake

modules/java/generator/CMakeLists.txt

@@ -62,6 +62,24 @@ ocv_bindings_generator_populate_preprocessor_definitions(
   opencv_preprocessor_defs
 )
 
+if(OPENCV_JAVA_CLEANING_API)
+  if(OPENCV_JAVA_CLEANING_API STREQUAL "finalize")
+    set(opencv_supported_cleaners "false")
+  elseif(OPENCV_JAVA_CLEANING_API STREQUAL "cleaner")
+    set(opencv_supported_cleaners "true")
+  else()
+    message(FATAL_ERROR "OPENCV_JAVA_CLEANING_API should be one of \"finalize\" or \"cleaner\"")
+  endif()
+else()
+  if(ANDROID OR (Java_VERSION VERSION_LESS 9))
+    message(STATUS "Set Cleaners to False")
+    set(opencv_supported_cleaners "false")
+  else()
+  message(STATUS "Set Cleaners to True")
+    set(opencv_supported_cleaners "true")
+  endif()
+endif(OPENCV_JAVA_CLEANING_API)
+
 set(CONFIG_FILE "${CMAKE_CURRENT_BINARY_DIR}/gen_java.json")
 set(__config_str
 "{
@@ -74,7 +92,8 @@ ${opencv_preprocessor_defs}
   },
   \"files_remap\": [
 ${__remap_config}
-  ]
+  ],
+  \"support_cleaners\": ${opencv_supported_cleaners}
 }
 ")
 if(EXISTS "${CONFIG_FILE}")

modules/java/generator/gen_java.py

@@ -23,6 +23,7 @@ SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
 # list of modules + files remap
 config = None
 ROOT_DIR = None
+USE_CLEANERS = True
 FILES_REMAP = {}
 def checkFileRemap(path):
     path = os.path.realpath(path)
@@ -366,6 +367,7 @@ class ClassInfo(GeneralInfo):
                             module = m,
                             name = self.name,
                             jname = self.jname,
+                            jcleaner = "long nativeObjCopy = nativeObj;\n org.opencv.core.Mat.cleaner.register(this, () -> delete(nativeObjCopy));" if USE_CLEANERS else "",
                             imports = "\n".join(self.getAllImports(M)),
                             docs = self.docstring,
                             annotation = "\n" + "\n".join(self.annotation) if self.annotation else "",
@@ -948,6 +950,7 @@ class JavaWrapperGenerator(object):
                     tail = ")"
                 else:
                     ret_val = "nativeObj = "
+                    tail = ";\n long nativeObjCopy = nativeObj;\n org.opencv.core.Mat.cleaner.register(this, () -> delete(nativeObjCopy))" if USE_CLEANERS else ""
                 ret = ""
             elif self.isWrapped(ret_type): # wrapped class
                 constructor = self.getClass(ret_type).jname + "("
@@ -1214,8 +1217,9 @@ JNIEXPORT $rtype JNICALL Java_org_opencv_${module}_${clazz}_$fname
                 ci.cpp_code.write("\n".join(fn["cpp_code"]))
 
         if ci.name != self.Module or ci.base:
-            # finalize()
-            ci.j_code.write(
+            # finalize() for old Java
+            if not USE_CLEANERS:
+                ci.j_code.write(
 """
     @Override
     protected void finalize() throws Throwable {
@@ -1225,7 +1229,7 @@ JNIEXPORT $rtype JNICALL Java_org_opencv_${module}_${clazz}_$fname
 
             ci.jn_code.write(
 """
-    // native support for java finalize()
+    // native support for java finalize() or cleaner
     private static native void delete(long nativeObj);
 """ )
 
@@ -1233,7 +1237,7 @@ JNIEXPORT $rtype JNICALL Java_org_opencv_${module}_${clazz}_$fname
             ci.cpp_code.write(
 """
 //
-//  native support for java finalize()
+//  native support for java finalize() or cleaner
 //  static void %(cls)s::delete( __int64 self )
 //
 JNIEXPORT void JNICALL Java_org_opencv_%(module)s_%(j_cls)s_delete(JNIEnv*, jclass, jlong);
@@ -1454,6 +1458,12 @@ if __name__ == "__main__":
     FILES_REMAP = { os.path.realpath(os.path.join(ROOT_DIR, f['src'])): f['target'] for f in config['files_remap'] }
     logging.info("\nRemapped configured files (%d):\n%s", len(FILES_REMAP), pformat(FILES_REMAP))
 
+    USE_CLEANERS = config['support_cleaners']
+    if (USE_CLEANERS):
+        logging.info("\nUse Java 9+ cleaners\n")
+    else:
+        logging.info("\nUse old style Java finalize()\n")
+
     dstdir = "./gen"
     jni_path = os.path.join(dstdir, 'cpp'); mkdir_p(jni_path)
     java_base_path = os.path.join(dstdir, 'java'); mkdir_p(java_base_path)
@@ -1543,6 +1553,17 @@ if __name__ == "__main__":
                           preprocessor_definitions)
         else:
             logging.info("No generated code for module: %s", module)
+
+    # Copy Cleaner / finalize() related files
+    if USE_CLEANERS:
+        cleaner_src = os.path.join(SCRIPT_DIR, "src", "java9", "CleanableMat.java")
+    else:
+        cleaner_src = os.path.join(SCRIPT_DIR, "src", "java_classic", "CleanableMat.java")
+
+    cleaner_dst = os.path.join(java_base_path, "org", "opencv", "core", "CleanableMat.java")
+    print("cleaner_dst: ", cleaner_dst)
+    copyfile(cleaner_src, cleaner_dst)
+
     generator.finalize(jni_path)
 
     print('Generated files: %d (updated %d)' % (total_files, updated_files))

modules/java/generator/src/cpp/CleanableMat.cpp

@@ -0,0 +1,28 @@
+// This file is part of OpenCV project.
+// It is subject to the license terms in the LICENSE file found in the top-level directory
+// of this distribution and at http://opencv.org/license.html
+
+#include "opencv2/core.hpp"
+
+#define LOG_TAG "org.opencv.core.CleanableMat"
+#include "common.h"
+#include <iostream>
+
+using namespace cv;
+
+extern "C" {
+    //
+    //  native support for java finalize() or cleaners
+    //  static void CleanableMat::n_delete( __int64 self )
+    //
+
+    JNIEXPORT void JNICALL Java_org_opencv_core_CleanableMat_n_1delete
+    (JNIEnv*, jclass, jlong self);
+
+    JNIEXPORT void JNICALL Java_org_opencv_core_CleanableMat_n_1delete
+    (JNIEnv*, jclass, jlong self)
+    {
+        // LOGD("CleanableMat.n_delete() called\n");
+        delete (Mat*) self;
+    }
+}

modules/java/generator/src/cpp/Mat.cpp

@@ -2114,22 +2114,6 @@ JNIEXPORT jlong JNICALL Java_org_opencv_core_Mat_n_1zeros__I_3II
     return 0;
 }
 
-
-
-//
-//  native support for java finalize()
-//  static void Mat::n_delete( __int64 self )
-//
-
-JNIEXPORT void JNICALL Java_org_opencv_core_Mat_n_1delete
-  (JNIEnv*, jclass, jlong self);
-
-JNIEXPORT void JNICALL Java_org_opencv_core_Mat_n_1delete
-  (JNIEnv*, jclass, jlong self)
-{
-    delete (Mat*) self;
-}
-
 } // extern "C"
 
 namespace {

modules/java/generator/src/java9/CleanableMat.java

@@ -0,0 +1,23 @@
+package org.opencv.core;
+
+import java.lang.ref.Cleaner;
+
+public abstract class CleanableMat {
+    // A native memory cleaner for the OpenCV library
+    public static Cleaner cleaner = Cleaner.create();
+
+    protected CleanableMat(long obj) {
+        if (obj == 0)
+            throw new UnsupportedOperationException("Native object address is NULL");
+
+        nativeObj = obj;
+
+        // The n_delete action must not refer to the object being registered. So, do not use nativeObj directly.
+        long nativeObjCopy = nativeObj;
+        cleaner.register(this, () -> n_delete(nativeObjCopy));
+    }
+
+    private static native void n_delete(long nativeObj);
+
+    public final long nativeObj;
+}

modules/java/generator/src/java_classic/CleanableMat.java

@@ -0,0 +1,21 @@
+package org.opencv.core;
+
+public abstract class CleanableMat {
+
+    protected CleanableMat(long obj) {
+        if (obj == 0)
+            throw new UnsupportedOperationException("Native object address is NULL");
+
+        nativeObj = obj;
+    }
+
+    @Override
+    protected void finalize() throws Throwable {
+        n_delete(nativeObj);
+        super.finalize();
+    }
+
+    private static native void n_delete(long nativeObj);
+
+    public final long nativeObj;
+}

modules/java/generator/templates/java_class.prolog

@@ -9,7 +9,10 @@ $docs$annotation
 public class $jname {
 
     protected final long nativeObj;
-    protected $jname(long addr) { nativeObj = addr; }
+    protected $jname(long addr) {
+      nativeObj = addr;
+      $jcleaner
+    }
 
     public long getNativeObjAddr() { return nativeObj; }