JNI improvements (#886)

Large refactoring of the Java Wrapper, focussing on error handling,
documentation, completeness, and usability improvements. Fixes #880.

This includes several breaking changes. Not all breaking changes are listed
here explicitly. But in all cases, it should be easy for clients to update
their code to the new state. The most important changes for the Java
Wrapper are:

- Made `deflateZstd`, `deflateZLIB`, and `createFromMemory` available
  in the `KtxTexture2` class
- Fixed a bug where the `KtxBasisParams#setInputSwizzle` function caused
  data corruption
- Increased the consistency of the naming and handling of constants:
  - All constant names are `UPPER_SNAKE_CASE`, omitting common prefixes
  - Classes that define constants offer a `stringFor` function that returns the
    string representation of a constant
  - The `KtxCreateStorage` class was renamed to `KtxTextureCreateStorage`
  - The `KtxPackUASTCFlagBits` class was renamed to `KtxPackUastcFlagBits`
- Improved error handling:
  - When functions receive a parameter that is `null`, then this will no longer
    crash the JVM, but throw a `NullPointerException` instead
  - When `setInputSwizzle` receives invalid arguments, then an
    `IllegalArgumentException` will be thrown
  - When one of the `create...` family of functions causes an error, meaning
    that the respective `KtxTexture2` object cannot be created, then a
    `KtxException` will be thrown
- Added JavaDocs, and enabled the generation of JavaDocs as part of the Maven build process
- Internal improvements (like JNI field caching, and avoiding to call JNI functions with pending exceptions)

Author: javagl

interface/java_binding/CMakeLists.txt

@@ -28,6 +28,7 @@ add_library(ktx-jni SHARED
     src/main/cpp/KtxTexture.cpp
     src/main/cpp/KtxTexture1.cpp
     src/main/cpp/KtxTexture2.cpp
+    src/main/cpp/KtxErrorCode.cpp
     src/main/cpp/libktx-jni.cpp
     ${CMAKE_CURRENT_BINARY_DIR}/ktx-jni.manifest
 )

interface/java_binding/pom.xml

@@ -144,6 +144,19 @@
           </execution>
         </executions>
       </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <version>3.6.3</version>
+        <executions>
+          <execution>
+            <id>attach-javadocs</id>
+            <goals>
+              <goal>jar</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
       <!--
       <plugin>
         <groupId>org.codehaus.mojo</groupId>

interface/java_binding/src/main/cpp/KtxErrorCode.cpp

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2024, Khronos Group and Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "libktx-jni.h"
+#include <iostream>
+
+extern "C" JNIEXPORT jstring JNICALL Java_org_khronos_ktx_KtxErrorCode_createString(JNIEnv *env, jclass, jint error)
+{
+  KTX_error_code errorNative = KTX_error_code(error);
+  const char* errorStringNative = ktxErrorString(errorNative);
+
+  // If this causes an OutOfMemoryError, then it will return
+  // 'null', with the OutOfMemoryError pending
+  jstring errorString = env->NewStringUTF(errorStringNative);
+  return errorString;
+}
+