CM H3 Java JNI whitelist plugin

doc/news/_preparation_next_release.md

@@ -118,6 +118,16 @@ you up to date with the multi-language support provided by Elektra.
 - Introduced `KeySet::remove(Key)` and `KeySet::remove(String)`
 - Removed `KeySet::lookup(Key, int)` and `KeySet::lookup(String, int)` as well as accompanying flag definitions `KeySet::KDB_O_NONE`, `KeySet::KDB_O_DEL` and `KeySet::KDB_O_POP`. Please use `KeySet::lookup(Key)` and `KeySet::lookup(String)` instead. Instead of `KeySet::KDB_O_DEL`, please consider using `Key::release`. The proper replacement for `KeySet::KDB_O_POP` is `KeySet::remove(Key)` or `KeySet::remove(String)`.
 - Native library proxy interface `Elektra` is now package private (previously was public).
+- Added example Java plugin `whitelist` (see [here](../../src/bindings/jna/plugins/whitelist/README.md))
+- Changed `Key nextMeta()` to `Optional<Key> nextMeta ()` no longer throwing NoSuchElementException for non-exceptional behavior
+- Added support of binary valued keys:
+  - Renamed `KeyBinaryTypeNotSupportedException` to `KeyStringValueException`
+  - Introduced `KeyBinaryValueException`
+  - Improved `Key` test coverage
+  - Introduced `Key::getBinary()` and `Key::setBinary(byte[])`
+- Fixed example project in `examples/external/java/read-keys-example`
+  - now works with a standard installation of Elektra
+  - updated code to work with current Java binding
 
 _(Michael Tucek)_
 

doc/tutorials/java-kdb.md

@@ -85,34 +85,51 @@ The _user_ namespace is accessible without special rights, but if you try to wri
 
 ### Traversing Keys in a `KeySet`
 
+First we create a new `KDB` handle and fetch all keys for the desired namespace, in this example the whole `user` namespace. Since all all keys are put in the passed `keySet` variable we can then iterate through it.
+The `at(int)` method returns a new `Key` object for the native key with the corresponding position within the `keySet`.
+
 ```java
-var keyNamespace = Key.create("user:/");            // select a namespace from which all keys should be fetched
+var keyNamespace = Key.create("user:/");           // select a namespace from which all keys should be fetched
 try (KDB kdb = KDB.open()) {
-    var keySet = kdb.get(keyNamespace);             // fetch all keys int new key set
-    for (int i = 0; i < keySet.length(); i++) {     // traverse the set
+    var keySet = kdb.get(keyNamespace);            // fetch all keys into a new key set
+    for (int i = 0; i < keySet.length(); i++) {    // traverse the set
         var currentKey = keySet.at(i);
         System.out.println(String.format("%s: %s",
-                currentKey.getName(),               // fetch the key's name
-                currentKey.getString()));           // fetch the key's value
+                currentKey.getName(),              // fetch the key's name
+                currentKey.getString()));          // fetch the key's value
     }
 } catch (KDB.KDBException e) {
     e.printStackTrace();
 }
 ```
 
-First we create a new `KDB` session and fetch all keys for the desired namespace, in this example the whole `user` namespace. Since all all keys are put in the passed `keySet` variable we can then iterate through it.
-The `at(int)` method return a new `Key` object for the native key with the corresponding position within the `keySet`.
+`KeySet` also provides an iterator implementation:
+
+```java
+var keyNamespace = Key.create("user:/");           // select a namespace from which all keys should be fetched
+try (KDB kdb = KDB.open()) {
+    var iter = kdb.get(keyNamespace).iterator();   // fetch all keys into a new key set
+    while(iter.hasNext()) {                        // traverse the set
+        var currentKey = iter.next();
+        System.out.println(String.format("%s: %s",
+                currentKey.getName(),              // fetch the key's name
+                currentKey.getString()));          // fetch the key's value
+    }
+} catch (KDB.KDBException e) {
+    e.printStackTrace();
+}
+```
 
 Of course, alternatively a for each loop can be used:
 
 ```java
-var keyNamespace = Key.create("user:/");            // select a namespace from which all keys should be fetched
+var keyNamespace = Key.create("user:/");           // select a namespace from which all keys should be fetched
 try (KDB kdb = KDB.open()) {
-    var keySet = kdb.get(keyNamespace);             // fetch all keys int new key set
-    for (var currentKey : keySet) {                 // traverse the set
+    var keySet = kdb.get(keyNamespace);            // fetch all keys into a new key set
+    for (var currentKey : keySet) {                // traverse the set
         System.out.println(String.format("%s: %s",
-                currentKey.getName(),               // fetch the key's name
-                currentKey.getString()));           // fetch the key's value
+                currentKey.getName(),              // fetch the key's name
+                currentKey.getString()));          // fetch the key's value
     }
 } catch (KDB.KDBException e) {
     e.printStackTrace();

examples/external/java/read-keys-example/.gitignore

@@ -0,0 +1,15 @@
+# ignore java class files
+*.class
+
+# ignore secret settings
+secret-settings.gradle
+
+# ignore gradle cache
+/.gradle
+
+# ignore eclipse project files
+.project
+.classpath
+bin
+target
+.settings

examples/external/java/read-keys-example/README.md

@@ -1,7 +1,29 @@
-This is a fully working example for how to use Elektra with Maven or Gradle.
+This is a fully working example for how to use Elektra with Maven or Gradle for reading keys.
 
-Make sure Elektra and the JNA binding are installed correctly.
+First Make sure to install the Elektra Java binding to your local maven repository:
 
-See [JNA binding](../../../../src/bindings/jna/README.md) for more information.
+```sh
+cd ./src/bindings/jna
+./gradlew publishLibelektraPublicationToMavenLocal
+```
 
-TODO add short intro how to build suing gradle or maven
+Alternatively change the `libelektra` dependency in `build.gradle` to a published version, fitting your Elektra installation.
+(See [JNA binding](../../../../src/bindings/jna/README.md) for more information.)
+
+Then change to the example app folder:
+
+```sh
+cd ../../../examples/external/java/read-keys-example
+```
+
+Use a local Gradle installation to run the example app:
+
+```sh
+gradle run
+```
+
+Alternatively use a local Maven installation to run the example app:
+
+```sh
+mvn compile exec:java
+```

examples/external/java/read-keys-example/pom.xml

@@ -12,8 +12,8 @@
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <maven.compiler.source>1.8</maven.compiler.source>
-    <maven.compiler.target>1.8</maven.compiler.target>
+    <maven.compiler.source>11</maven.compiler.source>
+    <maven.compiler.target>11</maven.compiler.target>
   </properties>
 
   <dependencies>

examples/external/java/read-keys-example/src/main/java/org/libelektra/app/App.java

@@ -1,23 +1,24 @@
 package org.libelektra.app;
 
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.Map;
 import java.util.stream.Collectors;
 import org.libelektra.KDB;
+import org.libelektra.KDBException;
 import org.libelektra.Key;
 import org.libelektra.KeySet;
-import org.libelektra.exception.KDBException;
 
 public class App
 {
 
-	private final static String MOUNT_SPACE = "user:/";
-	private final static String KEY_PREFIX = MOUNT_SPACE + "/sw/clock/central/";
+	private static final String MOUNT_SPACE = "system:/";
+	private static final String KEY_PREFIX = MOUNT_SPACE + "elektra/version/infos/";
 
 	public static void main (String[] args)
 	{
 		System.out.println ("Example started");
-		Map<String, String> stringStringMap = loadConfigurationSettings ();
+		var stringStringMap = loadConfigurationSettings ();
 		System.out.println ("Result:");
 		System.out.println (stringStringMap);
 		System.out.println ("Example terminated");
@@ -27,57 +28,38 @@ public static void main (String[] args)
 	private static Map<String, String> loadConfigurationSettings ()
 	{
 		// all keys we want to retrieve
-		String[] keys = new String[] {
-			"server/port",
-			"spring/profiles/active",
-			"spring/datasource/type",
-			"spring/datasource/url",
-			"spring/datasource/username",
-			"spring/datasource/password",
-			"spring/jpa/database-platform",
-			"spring/jpa/database",
-			"spring/mail/host",
-			"spring/mail/port",
-			"jhipster/mail/from",
-			"jhipster/mail/base-url",
-		};
+		String[] keys = new String[] { "author", "description", "licence", "versions" };
+
 		// read the keys
 		return readKeys (keys);
 	}
 
 	private static Map<String, String> readKeys (String[] keys)
 	{
 		System.out.println ("Reading following keys:");
-		for (String key : keys)
-		{
-			System.out.println (key);
-		}
-		// create a key without specifying a name, which is allowed
-		Key key = Key.create ("");
+		Arrays.stream (keys).map (k -> KEY_PREFIX + k).forEach (System.out::println);
+
 		// open KDB with autoclose functionality
 		// keep in mind this is an expensive operation, avoid calling it too frequently
-		try (KDB kdb = KDB.open (key))
+		try (KDB kdb = KDB.open ())
 		{
-			// create keyset
-			KeySet keySet = KeySet.create ();
-			// set mount space
-			kdb.get (keySet, Key.create (MOUNT_SPACE));
+			// fetch key set
+			KeySet keySet = kdb.get (Key.create (MOUNT_SPACE));
+
 			// fetch values
 			return Arrays.stream (keys)
-				.map (k -> {
-					Key lookedUpValue = keySet.lookup (KEY_PREFIX + k);
-					// if null (not found), set it to null value
-					// if specification with default value is applied, this actually should never happen
-					return new String[] { k, (lookedUpValue != null) ? lookedUpValue.getString () : null };
-				})
-				// collect to map
-				.collect (Collectors.toMap (keyValue -> keyValue[0], keyValue -> keyValue[1]));
+				.map (k -> KEY_PREFIX + k)
+				.collect (Collectors.toMap (k
+							    -> k,
+							    // if not found, set it to "(no-spec-default)"
+							    // if specification with default value is applied, this actually should never
+							    // happen
+							    k -> keySet.lookup (k).map (Key::getString).orElse ("(no-spec-default)")));
 		}
 		catch (KDBException e)
 		{
-			// a problem occured with kdb.get(keySet, Key.create(MOUNT_SPACE));
 			e.printStackTrace ();
 		}
-		return null;
+		return Collections.emptyMap ();
 	}
 }

src/bindings/jna/CMakeLists.txt

@@ -57,24 +57,6 @@ if (Java_JAVAC_EXECUTABLE)
 				set (GRADLE_TEST_EXCLUDES "")
 				java_test_needs_plugin (GOptsTest gopts)
 
-				if ((CMAKE_SYSTEM_NAME STREQUAL "Darwin")
-				    AND NOT (CMAKE_SYSTEM_VERSION VERSION_LESS 15)
-				    OR (NOT BUILD_TESTING))
-					# we cannot set DYLD_LIBRARY_PATH on new macOS versions, making the kdb tests fail if its not
-					# installed in the system
-					java_exclude_test (ExceptionMapperIT)
-					java_exclude_test (ExceptionMapperTest)
-					java_exclude_test (GOptsTest)
-					java_exclude_test (KDBExceptionTest)
-					java_exclude_test (KDBTest)
-					java_exclude_test (KeyNameIteratorTest)
-					java_exclude_test (KeySetTest)
-					java_exclude_test (KeyTest)
-					java_exclude_test (PluginLoaderIT)
-					java_exclude_test (ReturnTest)
-					java_exclude_test (WarningEntryTest)
-				endif ()
-
 				# first fill the elektra version in the pom file @ONLY to avoid replacing pom.xml placeholders which also
 				# use the format ${}
 				configure_file ("${CMAKE_CURRENT_SOURCE_DIR}/version-settings.gradle.in"
@@ -114,13 +96,14 @@ if (Java_JAVAC_EXECUTABLE)
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/InterfaceException.java
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/InternalException.java
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/KDBClosedException.java
-					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/KeyBinaryTypeNotSupportedException.java
+					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/KeyBinaryValueException.java
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/KeyException.java
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/KeyMetaException.java
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/KeyNameException.java
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/KeyReleasedException.java
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/KeySetAppendException.java
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/KeySetReleasedException.java
+					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/KeyStringValueException.java
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/LogicalException.java
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/OutOfMemoryException.java
 					${JNA_BINDING_SOURCE_DIRECTORY_EXCEPTION}/package-info.java
@@ -141,6 +124,10 @@ if (Java_JAVAC_EXECUTABLE)
 					${JNA_BINDING_SOURCE_DIRECTORY_TEST_PLUGIN}/ReturnTest.java
 					${JNA_BINDING_PREFIX}/build.gradle
 					${JNA_BINDING_PREFIX}/dependencies.gradle
+					plugins/build.gradle
+					plugins/dependencies.gradle
+					plugins/whitelist/src/main/java/org/libelektra/plugin/WhitelistPlugin.java
+					plugins/whitelist/src/test/java/org/libelektra/plugin/WhitelistPluginTests.java
 					build.gradle
 					gradle.properties
 					java-library.gradle
@@ -180,8 +167,14 @@ if (Java_JAVAC_EXECUTABLE)
 					DESTINATION "share/java"
 					COMPONENT java-elektra)
 
-				# add gradle test to execute with ctest in the testing phase
-				if (BUILD_TESTING AND NOT ENABLE_ASAN)
+				# we cannot set DYLD_LIBRARY_PATH on new macOS versions, making the kdb tests fail if its not installed in
+				# the system
+				if (BUILD_TESTING
+				    AND NOT ENABLE_ASAN
+				    AND NOT
+					((CMAKE_SYSTEM_NAME STREQUAL "Darwin")
+					 AND NOT (CMAKE_SYSTEM_VERSION VERSION_LESS 15)
+					 OR (NOT BUILD_TESTING)))
 					add_test (
 						NAME testjna_gradle
 						COMMAND ${GRADLE_EXECUTABLE} -q --console=plain test

src/bindings/jna/README.md

@@ -176,7 +176,6 @@ You can run unit tests by invoking:
 
 ## Limitations
 
-- no binary keys
 - no Java iterator for metadata
 
 ## Release publishing to Maven Central

src/bindings/jna/java-shared.gradle

@@ -98,15 +98,6 @@ tasks.named('test').configure {
 	}
 }
 
-// apply optional test override
-File testExclusions = new File('test-exclusion.gradle')
-if (testExclusions.exists()) {
-	apply from: testExclusions
-	logger.lifecycle("Test exclusions have been applied.")
-} else {
-	logger.lifecycle("Test exclusions file not found.")
-}
-
 // eclipse IDE integration
 eclipse {
 	classpath {

src/bindings/jna/libelektra/build.gradle

@@ -1,6 +1,15 @@
 // apply project configuration for java libraries
 apply from: "$rootProject.projectDir/java-library.gradle"
 
+// apply optional test override
+File testExclusions = new File('test-exclusion.gradle')
+if (testExclusions.exists()) {
+	apply from: testExclusions
+	logger.lifecycle("Test exclusions have been applied.")
+} else {
+	logger.lifecycle("Test exclusions file not found.")
+}
+
 // apply project dependencies
 apply from: 'dependencies.gradle'
 

src/bindings/jna/libelektra/src/main/java/org/libelektra/Elektra.java

@@ -321,8 +321,9 @@ int elektraGOptsContractFromStrings (Pointer contractKeySet, long argsSize, Stri
 
 	int keySetString (Pointer key, String newString);
 
-	// int keyGetBinary(Pointer key, byte[] returnedBinary, int maxSize);
-	// int keySetBinary(Pointer key, byte[] newBinary, int dataSize);
+	int keyGetBinary (Pointer key, byte[] returnedBinary, int maxSize);
+
+	int keySetBinary (Pointer key, @Nullable byte[] newBinary, int dataSize);
 
 	// KeySet methods -----------------------------------------------------------