feat(util): add getJsonValue method for robust JSON parsing #11654

Introduced `getJsonValue` to parse serialized JSON strings into `JsonValue`, supporting `JsonObject`, `JsonArray`, and primitives. Includes comprehensive unit tests for valid and invalid JSON scenarios.

Note: a primitive (number, string, ...) is not a valid JSON document on its own. The exception thrown is intended to be used to handle this situation.

As this is related to the Settings Service, this may be used to return the raw value instead of some JSON object/array.

Author: poikilotherm

src/main/java/edu/harvard/iq/dataverse/util/json/JsonUtil.java

@@ -8,12 +8,14 @@
 import java.io.StringWriter;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Objects;
 import java.util.logging.Logger;
 import jakarta.json.Json;
 import jakarta.json.JsonArray;
 import jakarta.json.JsonException;
 import jakarta.json.JsonObject;
 import jakarta.json.JsonReader;
+import jakarta.json.JsonValue;
 import jakarta.json.JsonWriter;
 import jakarta.json.JsonWriterFactory;
 import jakarta.json.stream.JsonGenerator;
@@ -131,4 +133,34 @@ public static JsonArray getJsonArray(String serializedJson) {
             }
         }
     }
+    
+    
+    /**
+     * Parses a serialized JSON string and returns it as a JsonValue.
+     * The returned JsonValue can be a JsonObject, JsonArray, or another type
+     * based on the structure of the provided serialized JSON string.
+     * This method closes its resources but does not catch any exceptions.
+     *
+     * @param serializedJson The JSON content serialized as a String
+     * @return The parsed content as a JsonValue which could be a JsonObject, JsonArray, or another JsonValue type
+     * @throws JsonException If an error occurs during parsing (null, invalid JSON, not trimmed, etc.)
+     */
+    public static JsonValue getJsonValue(String serializedJson) {
+        if (serializedJson == null) {
+            throw new JsonException("The serialized JSON string cannot be null.");
+        }
+        
+        try (StringReader rdr = new StringReader(serializedJson)) {
+            try (JsonReader jsonReader = Json.createReader(rdr)) {
+                JsonValue jsonValue = jsonReader.read();
+                if (jsonValue.getValueType() == JsonValue.ValueType.OBJECT) {
+                    return jsonValue.asJsonObject();
+                } else if (jsonValue.getValueType() == JsonValue.ValueType.ARRAY) {
+                    return jsonValue.asJsonArray();
+                } else {
+                    return jsonValue;
+                }
+            }
+        }
+    }
 }

src/test/java/edu/harvard/iq/dataverse/util/json/JsonUtilTest.java

@@ -1,7 +1,15 @@
 package edu.harvard.iq.dataverse.util.json;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import jakarta.json.JsonException;
+import jakarta.json.JsonValue;
+import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.NullAndEmptySource;
+import org.junit.jupiter.params.provider.ValueSource;
 
 class JsonUtilTest {
 
@@ -15,5 +23,32 @@ void testPrettyPrint() {
         assertEquals("[\n    \"junk\"\n]", JsonUtil.prettyPrint("[\"junk\"]"));
         assertEquals("{\n" + "    \"foo\": \"bar\"\n" + "}", JsonUtil.prettyPrint("{\"foo\": \"bar\"}"));
     }
-
+    
+    @Nested
+    class JsonValues {
+        @Test
+        void testGetJsonValueWithJsonObject() {
+            String jsonObject = "{\"key\": \"value\"}";
+            JsonValue result = JsonUtil.getJsonValue(jsonObject);
+            assertEquals(JsonValue.ValueType.OBJECT, result.getValueType());
+            assertEquals("value", result.asJsonObject().getString("key"));
+        }
+        
+        @Test
+        void testGetJsonValueWithJsonArray() {
+            String jsonArray = "[\"element1\", \"element2\"]";
+            JsonValue result = JsonUtil.getJsonValue(jsonArray);
+            assertEquals(JsonValue.ValueType.ARRAY, result.getValueType());
+            assertEquals("element1", result.asJsonArray().getString(0));
+            assertEquals("element2", result.asJsonArray().getString(1));
+        }
+        
+        @ParameterizedTest
+        @NullAndEmptySource
+        @ValueSource(strings = {"   ", "  \"\"", "\"primitive\"", "{invalid}", "[invalid]", "[1234, invalid]"})
+        void testGetJsonValueWithInvalidJson(String sut) {
+            assertThrows(JsonException.class, () -> JsonUtil.getJsonValue(sut));
+        }
+    }
+    
 }