[serde-*, read-write-*] Support for visiting arbitrary decorations and values

tweed5-serde-api/src/main/java/de/siphalor/tweed5/dataapi/api/DelegatingTweedDataVisitor.java

@@ -0,0 +1,118 @@
+package de.siphalor.tweed5.dataapi.api;
+
+import de.siphalor.tweed5.dataapi.api.decoration.TweedDataDecoration;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import org.jspecify.annotations.Nullable;
+
+@Getter
+@RequiredArgsConstructor(access = AccessLevel.PROTECTED)
+public class DelegatingTweedDataVisitor implements TweedDataVisitor {
+	protected final TweedDataVisitor delegate;
+
+	@Override
+	public void visitNull() {
+		beforeValueWrite();
+		delegate.visitNull();
+	}
+
+	@Override
+	public void visitBoolean(boolean value) {
+		beforeValueWrite();
+		delegate.visitBoolean(value);
+	}
+
+	@Override
+	public void visitByte(byte value) {
+		beforeValueWrite();
+		delegate.visitByte(value);
+	}
+
+	@Override
+	public void visitShort(short value) {
+		beforeValueWrite();
+		delegate.visitShort(value);
+	}
+
+	@Override
+	public void visitInt(int value) {
+		beforeValueWrite();
+		delegate.visitInt(value);
+	}
+
+	@Override
+	public void visitLong(long value) {
+		beforeValueWrite();
+		delegate.visitLong(value);
+	}
+
+	@Override
+	public void visitFloat(float value) {
+		beforeValueWrite();
+		delegate.visitFloat(value);
+	}
+
+	@Override
+	public void visitDouble(double value) {
+		beforeValueWrite();
+		delegate.visitDouble(value);
+	}
+
+	@Override
+	public void visitString(String value) {
+		beforeValueWrite();
+		delegate.visitString(value);
+	}
+
+	@Override
+	public void visitEmptyList() {
+		beforeValueWrite();
+		delegate.visitEmptyList();
+	}
+
+	@Override
+	public void visitListStart() {
+		beforeValueWrite();
+		delegate.visitListStart();
+	}
+
+	@Override
+	public void visitListEnd() {
+		delegate.visitListEnd();
+	}
+
+	@Override
+	public void visitEmptyMap() {
+		beforeValueWrite();
+		delegate.visitEmptyMap();
+	}
+
+	@Override
+	public void visitMapStart() {
+		beforeValueWrite();
+		delegate.visitMapStart();
+	}
+
+	@Override
+	public void visitMapEntryKey(String key) {
+		delegate.visitMapEntryKey(key);
+	}
+
+	@Override
+	public void visitMapEnd() {
+		delegate.visitMapEnd();
+	}
+
+	@Override
+	public void visitValue(@Nullable Object value) throws TweedDataUnsupportedValueException {
+		delegate.visitValue(value);
+	}
+
+	protected void beforeValueWrite() {}
+
+	@Override
+	public void visitDecoration(TweedDataDecoration decoration) {
+		delegate.visitDecoration(decoration);
+	}
+}

tweed5-serde-api/src/main/java/de/siphalor/tweed5/dataapi/api/TweedDataUnsupportedValueException.java

@@ -0,0 +1,13 @@
+package de.siphalor.tweed5.dataapi.api;
+
+import lombok.Getter;
+
+@Getter
+public class TweedDataUnsupportedValueException extends Exception {
+	private final Object value;
+
+	public TweedDataUnsupportedValueException(Object value) {
+		super("Unsupported value " + value + " of type " + value.getClass().getName());
+		this.value = value;
+	}
+}

tweed5-serde-api/src/main/java/de/siphalor/tweed5/dataapi/api/TweedDataVisitor.java

@@ -1,5 +1,8 @@
 package de.siphalor.tweed5.dataapi.api;
 
+import de.siphalor.tweed5.dataapi.api.decoration.TweedDataDecoration;
+import org.jspecify.annotations.Nullable;
+
 public interface TweedDataVisitor {
 	void visitNull();
 	void visitBoolean(boolean value);
@@ -11,6 +14,43 @@ public interface TweedDataVisitor {
 	void visitDouble(double value);
 	void visitString(String value);
 
+	/**
+	 * Visits an arbitrary value.
+	 * <br />
+	 * This method is allowed to throw a {@link TweedDataUnsupportedValueException} for any value,
+	 * so call sites should <b>always</b> provide a fallback based on the primitive visitor methods.
+	 * @param value the value to visit. May be {@code null}.
+	 * @throws TweedDataUnsupportedValueException if the value is not supported by this visitor.
+	 * The visitor should then proceed to write the value with the primitive visitor methods.
+	 * @apiNote Please use the specific visitor methods if possible.
+	 * This method is mainly provided for extensibility beyond the standard data types.
+	 * This could, for example, be used to allow native support for {@link java.math.BigDecimal}
+	 * or {@link java.util.UUID} values.
+	 */
+	default void visitValue(@Nullable Object value) throws TweedDataUnsupportedValueException {
+		if (value == null) {
+			visitNull();
+		} else if (value instanceof Boolean) {
+			visitBoolean((Boolean) value);
+		} else if (value instanceof Byte) {
+			visitByte((Byte) value);
+		} else if (value instanceof Short) {
+			visitShort((Short) value);
+		} else if (value instanceof Integer) {
+			visitInt((Integer) value);
+		} else if (value instanceof Long) {
+			visitLong((Long) value);
+		} else if (value instanceof Float) {
+			visitFloat((Float) value);
+		} else if (value instanceof Double) {
+			visitDouble((Double) value);
+		} else if (value instanceof String) {
+			visitString((String) value);
+		} else {
+			throw new TweedDataUnsupportedValueException(value);
+		}
+	}
+
 	default void visitEmptyList() {
 		visitListStart();
 		visitListEnd();
@@ -26,5 +66,8 @@ public interface TweedDataVisitor {
 	void visitMapEntryKey(String key);
 	void visitMapEnd();
 
-	void visitComment(String comment);
+	/**
+	 * Visits a decoration. The implementation <b>may</b> choose to ignore the decoration.
+	 */
+	void visitDecoration(TweedDataDecoration decoration);
 }

tweed5-serde-api/src/main/java/de/siphalor/tweed5/dataapi/api/decoration/TweedDataCommentDecoration.java

@@ -0,0 +1,5 @@
+package de.siphalor.tweed5.dataapi.api.decoration;
+
+public interface TweedDataCommentDecoration extends TweedDataDecoration {
+	String comment();
+}

tweed5-serde-api/src/main/java/de/siphalor/tweed5/dataapi/api/decoration/TweedDataDecoration.java

@@ -0,0 +1,7 @@
+package de.siphalor.tweed5.dataapi.api.decoration;
+
+/**
+ * Marker interface for "decorative" information during (de)serialization.
+ */
+public interface TweedDataDecoration {
+}

tweed5-serde-api/src/main/java/de/siphalor/tweed5/dataapi/api/decoration/package-info.java

@@ -0,0 +1,4 @@
+@NullMarked
+package de.siphalor.tweed5.dataapi.api.decoration;
+
+import org.jspecify.annotations.NullMarked;