feat(xjx-serdes): add better map support

README.md

@@ -130,7 +130,7 @@ class Temperature {
 ### Attributes
 
 
-### Collections
+### Collection types
 When deserializing XML data containing a collection type, the following conventions apply:
 
 - Only `List` and `Set` types are supported
@@ -179,3 +179,59 @@ public class Forecast {
     String minTemperature;
 }
 ```
+
+### Map types
+
+Maps can be deserialized either as a field or a top-level type. Consider the following XML document:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<WeatherData>
+    <CurrentConditions>
+        <Temperature>
+            <Value>75</Value>
+            <Unit>°F</Unit>
+        </Temperature>
+    </CurrentConditions>
+</WeatherData>
+```
+
+#### Option 1: Map a Specific Section
+
+You can map a specific section from the XML onto a custom field:
+
+```java
+class WeatherData {
+    @Tag(path = "/WeatherData/CurrentConditions")
+    Map<String, Object> map;
+}
+```
+In this case, the map field will contain:
+```java
+Map.of("Temperature", Map.of("Value", "75", "Unit", "°F"));
+```
+
+#### Option 2: Map the Whole Document
+
+Alternatively, you can map the entire document onto a Map of String Object
+```java
+class WeatherData {
+    @Tag(path = "/WeatherData")
+    Map<String, Object> map;
+}
+```
+In this case, the map field will contain:
+```java
+Map.of("CurrentConditions", 
+    Map.of("Temperature", Map.of("Value", "75", "Unit", "°F"))));
+```
+
+#### Option 3: Map to a Map
+```java
+Map<String, Object> map = new XjxSerdes().read(document, new MapOf<>() {});
+```
+In this case, the result of `read` will contain a Map of String Object
+```java
+Map.of("CurrentConditions", 
+    Map.of("Temperature", Map.of("Value", "75", "Unit", "°F"))));
+```
+

pom.xml

@@ -11,6 +11,10 @@
         <module>xjx-serdes</module>
     </modules>
 
+    <name>xjx</name>
+    <description>Lightweight XML library for Java</description>
+    <url>https://github.com/jonasgeiregat/xjx</url>
+
     <licenses>
         <license>
             <name>GPL-v3.0</name>
@@ -127,6 +131,16 @@
                         </goals>
                     </execution>
                 </executions>
+                <configuration>
+                    <pomElements>
+                        <url/>
+                        <name/>
+                        <description/>
+                        <scm/>
+                        <developers/>
+                        <inceptionYear/>
+                    </pomElements>
+                </configuration>
             </plugin>
             <plugin>
                 <groupId>org.jreleaser</groupId>

xjx-sax/pom.xml

@@ -8,6 +8,9 @@
     </parent>
 
     <artifactId>xjx-sax</artifactId>
+    <name>xjx-sax</name>
+    <description>SAX based XML parser</description>
+    <url>https://github.com/jonasgeiregat/xjx</url>
 
     <properties>
         <maven.compiler.source>17</maven.compiler.source>

xjx-sax/src/main/java/io/jonasg/xjx/EndTag.java

@@ -2,7 +2,4 @@
 
 public record EndTag(String namespace, String name) {
 
-    public EndTag(String name) {
-        this(null, name);
-    }
 }

xjx-sax/src/test/java/io/jonasg/xjx/scanners/EndTagScannerTest.java

@@ -10,6 +10,8 @@
 import java.io.StringReader;
 import java.util.ArrayList;
 
+import static org.assertj.core.api.Assertions.*;
+
 class EndTagScannerTest {
 
 
@@ -22,7 +24,7 @@ void shouldFail_whenInputDoesNotStartWithALessThenSignFollowedByASlash() {
         ThrowableAssert.ThrowingCallable act = () -> endTagAction.scan(new BufferedPositionedReader(new StringReader("home</a>")), t -> {});
 
         // then
-        Assertions.assertThatThrownBy(act)
+        assertThatThrownBy(act)
                 .isInstanceOf(XmlParsingException.class)
                 .hasMessage("End tag does not start with </ in: 'home</a>'");
     }
@@ -37,7 +39,7 @@ void shouldEmit_endTag() {
         endTagAction.scan(new BufferedPositionedReader(new StringReader("</a>")), tokens::add);
 
         // then
-        Assertions.assertThat(tokens).containsExactly(new Token<>(Token.Type.END_TAG, new EndTag("a")));
+        assertThat(tokens).containsExactly(new Token<>(Token.Type.END_TAG, new EndTag(null, "a")));
     }
 
 
@@ -51,7 +53,7 @@ void shouldEmit_endTagWithNamespace() {
         endTagAction.scan(new BufferedPositionedReader(new StringReader("</a:b>")), tokens::add);
 
         // then
-        Assertions.assertThat(tokens).containsExactly(new Token<>(Token.Type.END_TAG, new EndTag("a", "b")));
+        assertThat(tokens).containsExactly(new Token<>(Token.Type.END_TAG, new EndTag("a", "b")));
     }
 
 }

xjx-serdes/pom.xml

@@ -8,6 +8,9 @@
     </parent>
 
     <artifactId>xjx-serdes</artifactId>
+    <name>xjx-serdes</name>
+    <description>XML Serializer and Deserializer library for Java</description>
+    <url>https://github.com/jonasgeiregat/xjx</url>
 
     <properties>
         <maven.compiler.source>17</maven.compiler.source>

xjx-serdes/src/main/java/io/jonasg/xjx/serdes/XjxSerdes.java

@@ -1,11 +1,16 @@
 package io.jonasg.xjx.serdes;
 
 import io.jonasg.xjx.sax.SaxParser;
+import io.jonasg.xjx.serdes.deserialize.MapOf;
+import io.jonasg.xjx.serdes.deserialize.MapRootSaxHandler;
 import io.jonasg.xjx.serdes.deserialize.PathBasedSaxHandler;
 import io.jonasg.xjx.serdes.deserialize.PathWriterIndexFactory;
+import io.jonasg.xjx.serdes.deserialize.XjxDeserializationException;
 
 import java.io.Reader;
 import java.io.StringReader;
+import java.util.HashMap;
+import java.util.Map;
 
 public class XjxSerdes {
 
@@ -31,4 +36,21 @@ public <T> T read(Reader data, Class<T> clazz) {
         saxParser.parse(data, saxHandler);
         return saxHandler.instance();
     }
+
+    public <K, V> Map<K, V> read(String data, MapOf<K, V> mapOf) {
+        return read(new StringReader(data), mapOf);
+    }
+
+    @SuppressWarnings("unchecked")
+    public <K, V> Map<K, V> read(Reader data, MapOf<K, V> mapOf) {
+        Class<?> keyType = mapOf.keyType();
+        Class<?> valueType = mapOf.valueType();
+        if (keyType == String.class && valueType == Object.class) {
+            HashMap<String, Object> map = new HashMap<>();
+            MapRootSaxHandler mapRootSaxHandler = new MapRootSaxHandler(map, true);
+            saxParser.parse(data, mapRootSaxHandler);
+            return (Map<K, V>) map;
+        }
+        throw new XjxDeserializationException("Maps only support String as key");
+    }
 }

xjx-serdes/src/main/java/io/jonasg/xjx/serdes/deserialize/MapAsRoot.java

@@ -0,0 +1,6 @@
+package io.jonasg.xjx.serdes.deserialize;
+
+import java.util.Map;
+
+public record MapAsRoot(Object root, Map<String, Object> map) {
+}

xjx-serdes/src/main/java/io/jonasg/xjx/serdes/deserialize/MapOf.java

@@ -0,0 +1,27 @@
+package io.jonasg.xjx.serdes.deserialize;
+
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+
+public abstract class MapOf<K, V> {
+
+    protected final Type keyType;
+
+    protected final Type valueType;
+
+    protected MapOf() {
+        Type superClass = this.getClass().getGenericSuperclass();
+        this.keyType = ((ParameterizedType) superClass).getActualTypeArguments()[0];
+        this.valueType = ((ParameterizedType) superClass).getActualTypeArguments()[1];
+    }
+
+    @SuppressWarnings("unchecked")
+    public Class<K> keyType() {
+        return (Class<K>) keyType;
+    }
+
+    @SuppressWarnings("unchecked")
+    public Class<V> valueType() {
+        return (Class<V>) valueType;
+    }
+}

xjx-serdes/src/main/java/io/jonasg/xjx/serdes/deserialize/MapSaxHandler.java → xjx-serdes/src/main/java/io/jonasg/xjx/serdes/deserialize/MapRootSaxHandler.java

@@ -9,17 +9,31 @@
 import java.util.List;
 import java.util.Map;
 
-public class MapSaxHandler implements SaxHandler {
+public class MapRootSaxHandler implements SaxHandler {
 
     private final LinkedList<Map<String, Object>> mapsStack;
 
+    private final boolean skipRootTag;
+
+    private Map<String, Object> instance;
+
     private String characterData;
 
     private String prevStartTag;
 
-    public MapSaxHandler(HashMap<String, Object> instance) {
+    private String rootTag;
+
+    public MapRootSaxHandler(Map<String, Object> instance) {
         this.mapsStack = new LinkedList<>();
         this.mapsStack.add(instance);
+        this.skipRootTag = false;
+        this.instance = instance;
+    }
+
+    public MapRootSaxHandler(HashMap<String, Object> instance, boolean skipRootTag) {
+        this.mapsStack = new LinkedList<>();
+        this.mapsStack.add(instance);
+        this.skipRootTag = skipRootTag;
     }
 
     @Override
@@ -28,11 +42,16 @@ public void startDocument() {
 
     @Override
     public void startTag(String namespace, String name, List<Attribute> attributes) {
-        Map<String, Object> activeMap = this.mapsStack.getLast();
-        Map<String, Object> newMap = new LinkedHashMap<>();
-        activeMap.put(name, newMap);
-        this.mapsStack.add(newMap);
-        this.prevStartTag = name;
+        if (this.rootTag != null || !skipRootTag) {
+            Map<String, Object> activeMap = this.mapsStack.getLast();
+            Map<String, Object> newMap = new LinkedHashMap<>();
+            activeMap.put(name, newMap);
+            this.mapsStack.add(newMap);
+            this.prevStartTag = name;
+        }
+        if (this.rootTag == null) {
+            this.rootTag = name;
+        }
     }
 
     @Override
@@ -53,4 +72,8 @@ public void endTag(String namespace, String name) {
     public void characters(String data) {
         this.characterData = data;
     }
+
+    public Map<String, Object> instance() {
+        return instance;
+    }
 }

xjx-serdes/src/main/java/io/jonasg/xjx/serdes/deserialize/MapWithTypeInfo.java

@@ -0,0 +1,7 @@
+package io.jonasg.xjx.serdes.deserialize;
+
+import java.util.HashMap;
+import java.util.Map;
+
+public record MapWithTypeInfo(Map<String, Object> map, Class<?> valueType) {
+}

xjx-serdes/src/main/java/io/jonasg/xjx/serdes/deserialize/Path.java

@@ -80,4 +80,8 @@ public int hashCode() {
     public String toString() {
         return "/" + String.join("/", sections) + (attribute == null ? "" : "[" + attribute + "]");
     }
+
+    public boolean isRoot() {
+        return sections.size() == 1;
+    }
 }