implemented dynamic exception mapping through the @Platform-annotation

Author: FITOR

src/main/java/org/bytedeco/javacpp/ClassProperties.java

@@ -22,6 +22,7 @@
 
 package org.bytedeco.javacpp;
 
+import org.bytedeco.javacpp.annotation.ExceptionMapper;
 import org.bytedeco.javacpp.annotation.Platform;
 import org.bytedeco.javacpp.tools.Logger;
 
@@ -227,7 +228,19 @@ public void load(Class cls, boolean inherit) {
                 if (!match) {
                     continue;
                 }
-                if (p.exceptionMappings().length > 0) { exceptionMappings = p.exceptionMappings(); }
+
+                if (p.exceptionMappings().length > 0) {
+                    List<String> exceptionMappingsList = new LinkedList<>();
+                    for (ExceptionMapper mapper : p.exceptionMappings()) {
+                        final String cppException = mapper.cppException();
+                        final String javaException = mapper.javaExceptionClass().getName().replace('.', '/');
+
+                        exceptionMappingsList.add(cppException);
+                        exceptionMappingsList.add(javaException);
+                    }
+                    exceptionMappings = exceptionMappingsList.toArray(new String[0]);
+                }
+
                 if (p.pragma().length > 0) { pragma = p.pragma(); }
                 if (p.define().length > 0) { define = p.define(); }
                 if (p.exclude().length > 0) { exclude = p.exclude(); }

src/main/java/org/bytedeco/javacpp/annotation/ExceptionMapper.java

@@ -0,0 +1,29 @@
+package org.bytedeco.javacpp.annotation;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Exception Mapper maps a C/C++ exception to the given java exception.
+ * Will overwrite any existing exception-mappings.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({})
+public @interface ExceptionMapper {
+
+    /**
+     * The C/C++ exception to be mapped (e.g.: std::runtime_error).
+     *
+     * @return A String representation of the C/C++ exception to be mapped.
+     */
+    String cppException();
+
+    /**
+     * The corresponding java-exception.
+     *
+     * @return The corresponding java-exception.
+     */
+    Class<? extends Throwable> javaExceptionClass();
+}
+

src/main/java/org/bytedeco/javacpp/annotation/Platform.java

@@ -181,7 +181,7 @@
 
     /**
      * Mappings for custom exceptions.
-     * // TODO(Fitor) finish doc, also see whether you can replace String[] with a more fitting datatype (needs to be turned into String[] in {@link org.bytedeco.javacpp.ClassProperties eventually}
+     * @return An array of {@link ExceptionMapper}, which determines the mapping of custom native exceptions to any javaException.
      */
-    String[] exceptionMappings() default "";
+    ExceptionMapper[] exceptionMappings() default {};
 }

src/main/java/org/bytedeco/javacpp/tools/Generator.java

@@ -251,11 +251,6 @@ boolean classes(boolean handleExceptions, boolean defineAdapters, boolean conver
             out.println("#define " + s);
         }
 
-        out.println("FITORR");
-        for(String s : clsProperties.get("platform.exceptionMappings")) {
-            out.println(s);
-        }
-
         out.println();
         out.println("#ifdef _WIN32");
         out.println("    #define _JAVASOFT_JNI_MD_H_");
@@ -1089,7 +1084,31 @@ boolean classes(boolean handleExceptions, boolean defineAdapters, boolean conver
         out.println("};");
         out.println();
 
+        //////////////////// EXCEPTION HANDLER ////////////////////
         if (handleExceptions) {
+            // Build a function which maps custom java Exceptions to corresponding native exceptions.
+            out.println("static JavaCPP_noinline jclass JavaCPP_mapCustomExceptions(JNIEnv *env, const std::exception& e) {");
+
+            final String ifCondition = "  if(dynamic_cast<const %s*>(&e)){";
+            final String elifCondition = "  else if(dynamic_cast<const %s*>(&e)){";
+            final String returnVal = "      return env->FindClass(\"%s\");";
+
+            List<String> exceptionMappings = clsProperties.get("platform.exceptionMappings");
+            for (int i = 0; i < exceptionMappings.size(); i += 2) {
+                final String cppException = exceptionMappings.get(i);
+                final String javaException = exceptionMappings.get(i + 1);
+
+                out.println(i == 0 ?
+                        String.format(ifCondition, cppException) :
+                        String.format(elifCondition, cppException));
+
+                out.println(String.format(returnVal, javaException));
+                out.println("   }");
+            }
+            out.println("   return nullptr;");
+            out.println("}");
+
+            // "Import" the remaining exception-specific functions.
             try (InputStream inputStream = Generator.class.getResourceAsStream("/org/bytedeco/javacpp/jniTemplates/JNIExceptionHandler.h");
                  BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream))) {
 
@@ -1101,6 +1120,7 @@ boolean classes(boolean handleExceptions, boolean defineAdapters, boolean conver
                 throw new RuntimeException("Unable to find template 'JNIExceptionHandler'", e);
             }
         }
+        //////////////////// EXCEPTION HANDLER ////////////////////
 
         Class deallocator, nativeDeallocator;
         try {

src/main/resources/org/bytedeco/javacpp/jniTemplates/JNIExceptionHandler.h

@@ -1,3 +1,4 @@
+// Function finds the right java-exception to the most common native std::exceptions
 static JavaCPP_noinline jclass JavaCPP_mapJavaExceptions(JNIEnv *env, const std::exception& e){
         if (dynamic_cast<const std::invalid_argument*>(&e)) {
             return env->FindClass("java/lang/IllegalArgumentException");
@@ -10,9 +11,11 @@ static JavaCPP_noinline jclass JavaCPP_mapJavaExceptions(JNIEnv *env, const std:
         }
         return env->FindClass("java/lang/Exception");
 }
-
+// Function creates a jobject (extends Throwable) from the passed std::exception
 static JavaCPP_noinline jthrowable JavaCPP_createJavaException(JNIEnv *env, const std::exception& e, jthrowable cause = nullptr) {
-    jclass exClass = JavaCPP_mapJavaExceptions(env, e);
+    jclass exClass = JavaCPP_mapCustomExceptions(env, e);
+    exClass = exClass ? exClass : JavaCPP_mapJavaExceptions(env, e);
+
     jstring message = env->NewStringUTF(e.what());
     jmethodID constructor = env->GetMethodID(exClass, "<init>", "(Ljava/lang/String;)V");
 
@@ -24,7 +27,7 @@ static JavaCPP_noinline jthrowable JavaCPP_createJavaException(JNIEnv *env, cons
     }
     return  static_cast<jthrowable>(env->NewObject(exClass, constructor, message));
 }
-
+// Function unrolls native exceptions and builds the corresponding java exception
 static JavaCPP_noinline jthrowable JavaCPP_handleException(JNIEnv *env, const std::exception& e) {
         try {
             std::rethrow_if_nested(e);