From 23bef3281e9be176fdc5bc340051f4c3cb58c141 Mon Sep 17 00:00:00 2001
From: JonasG <jonas.grgt@gmail.com>
Date: Sun, 11 Feb 2024 22:09:31 +0100
Subject: [PATCH] doc: improve root-mapping documentation

Added test to verify both type and field can be mapped absolutely
---
 README.md                                     | 16 +++++++++++++
 .../GeneralDeserializationTest.java           | 23 +++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/README.md b/README.md
index 1c02b44..cbcd9a3 100644
--- a/README.md
+++ b/README.md
@@ -94,10 +94,12 @@ Each `@Tag` annotation must include a `path` property, using an XPath-like expre
 
 Path expressions can be **absolute**, starting with a slash, representing a path from the root tag to the mapped tag.
 **Relative** paths, without a starting slash, require a parent to be mapped absolutely.
+Root mappings can be placed top-level on the class, all subsequent relative mappings are relative to the root mapping. 
 
 ```java
 import java.math.BigDecimal;
 
+@Tag(path = "/WeatherData")
 class Weather {
     // not annotated with @Tag hence is ignored
     String id;
@@ -105,6 +107,10 @@ class Weather {
     // example for an absolute mapped tag
     @Tag(path = "/WeatherData/Location") 
     Location location;
+	
+	// example for a relative-mapped tag based upon the top-level mapping
+	@Tag(path = "CurrentConditions")
+	Conditions conditions;
 
     // normally all fields without @Tag are ignored, yet this field is 
     // taken into account because at least one of its child fields is
@@ -130,6 +136,16 @@ class Temperature {
 }
 ```
 
+Absolute mapping a field of top-level class containing a top-level root mapping is supported.
+```java
+@Tag(path = "/WeatherData")
+class Weather {
+    @Tag(path = "/WeatherData/Location")
+    Location location;
+}
+
+```
+
 ### Attributes
 
 
diff --git a/xjx-serdes/src/test/java/io/jonasg/xjx/serdes/deserialize/GeneralDeserializationTest.java b/xjx-serdes/src/test/java/io/jonasg/xjx/serdes/deserialize/GeneralDeserializationTest.java
index 38f0750..955e607 100644
--- a/xjx-serdes/src/test/java/io/jonasg/xjx/serdes/deserialize/GeneralDeserializationTest.java
+++ b/xjx-serdes/src/test/java/io/jonasg/xjx/serdes/deserialize/GeneralDeserializationTest.java
@@ -216,4 +216,27 @@ static class WhiteSpacePathMappingHolder {
         @Tag(path = "   /DataTypes/Double   ")
         Double Double;
     }
+
+	@Test
+	void absoluteRootMappingWithTopLevelMappedRootType() {
+		// given
+		String data = """
+				<?xml version="1.0" encoding="UTF-8"?>
+				<DataTypes>
+					<Double>5.7</Double>
+				</DataTypes>
+				""";
+
+		// when
+		var holder = new XjxSerdes().read(data, AbsoluteRootMappingHolder.class);
+
+		// then
+		assertThat(holder.Double).isEqualTo(5.7D);
+	}
+
+	@Tag(path = "/DataTypes")
+	static class AbsoluteRootMappingHolder {
+		@Tag(path = "/DataTypes/Double")
+		Double Double;
+	}
 }