BinarySerialiser: add quantity metadata field

wirew0rm · wirew0rm · commit 8f28a9db2e90 · 2025-12-19T19:41:17.000+01:00
Signed-off-by: Alexander Krimm &lt;A.Krimm@gsi.de&gt;
diff --git a/serialiser/src/main/java/io/opencmw/serialiser/FieldDescription.java b/serialiser/src/main/java/io/opencmw/serialiser/FieldDescription.java
@@ -56,6 +56,11 @@ public interface FieldDescription {
      */
     String getFieldUnit();
 
+    /**
+     * @return optional meta data tag describing the field's quantity or similar (N.B. can be empty String)
+     */
+    String getFieldQuantity();
+
     /**
      * @return for a hierarchical/nested data structure refers to the parent this field belongs to (N.B. can be null if there isn't a parent, e.g. for a root element)
      */
diff --git a/serialiser/src/main/java/io/opencmw/serialiser/annotations/MetaInfo.java b/serialiser/src/main/java/io/opencmw/serialiser/annotations/MetaInfo.java
@@ -9,6 +9,7 @@
 @Target({ ElementType.FIELD, ElementType.TYPE })
 public @interface MetaInfo {
     String unit() default "";
+    String quantity() default "";
     String description() default "";
     byte modifier() default 0;
 }
diff --git a/serialiser/src/main/java/io/opencmw/serialiser/annotations/Quantity.java b/serialiser/src/main/java/io/opencmw/serialiser/annotations/Quantity.java
@@ -0,0 +1,12 @@
+package io.opencmw.serialiser.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.FIELD, ElementType.TYPE })
+public @interface Quantity {
+    String value() default "";
+}
diff --git a/serialiser/src/main/java/io/opencmw/serialiser/spi/BinarySerialiser.java b/serialiser/src/main/java/io/opencmw/serialiser/spi/BinarySerialiser.java
@@ -422,6 +422,9 @@ public WireDataFieldDescription getFieldHeader() {
                 if (buffer.position() < dataStartPosition) {
                     lastFieldHeader.setFieldUnit(buffer.getString());
                 }
+                if (buffer.position() < dataStartPosition) {
+                    lastFieldHeader.setFieldQuantity(buffer.getString());
+                }
                 if (buffer.position() < dataStartPosition) {
                     lastFieldHeader.setFieldDescription(buffer.getString());
                 }
@@ -1456,6 +1459,7 @@ public WireDataFieldDescription putFieldHeader(final FieldDescription fieldDescr
 
             if (isPutFieldMetaData() && fieldDescription.isAnnotationPresent() && dataType != DataType.END_MARKER) {
                 buffer.putString(fieldDescription.getFieldUnit());
+                buffer.putString(fieldDescription.getFieldQuantity());
                 buffer.putString(fieldDescription.getFieldDescription());
                 buffer.putByte(fieldDescription.getFieldModifier());
             }
@@ -1470,6 +1474,7 @@ public WireDataFieldDescription putFieldHeader(final FieldDescription fieldDescr
             lastFieldHeader = new WireDataFieldDescription(this, parent, fieldDescription.getFieldName(), dataType, headerStart, dataStartOffset, dataSize);
             if (isPutFieldMetaData() && fieldDescription.isAnnotationPresent()) {
                 lastFieldHeader.setFieldUnit(fieldDescription.getFieldUnit());
+                lastFieldHeader.setFieldQuantity(fieldDescription.getFieldQuantity());
                 lastFieldHeader.setFieldDescription(fieldDescription.getFieldDescription());
                 lastFieldHeader.setFieldModifier(fieldDescription.getFieldModifier());
             }
diff --git a/serialiser/src/main/java/io/opencmw/serialiser/spi/ClassFieldDescription.java b/serialiser/src/main/java/io/opencmw/serialiser/spi/ClassFieldDescription.java
@@ -31,6 +31,7 @@ public class ClassFieldDescription implements FieldDescription {
     private final String fieldName;
     private final String fieldNameRelative;
     private final String fieldUnit;
+    private final String fieldQuantity;
     private final String fieldDescription;
     private final byte fieldModifier;
     private final boolean annotationPresent;
@@ -115,10 +116,11 @@ protected ClassFieldDescription(final Class<?> referenceClass, final Field field
         // read annotation values
         AnnotatedElement annotatedElement = field == null ? referenceClass : field;
         fieldUnit = getFieldUnit(annotatedElement);
+        fieldQuantity = getFieldQuantity(annotatedElement);
         fieldDescription = getFieldDescription(annotatedElement);
         fieldModifier = getFieldModifier(annotatedElement);
 
-        annotationPresent = fieldUnit != null || fieldDescription != null;
+        annotationPresent = fieldUnit != null || fieldQuantity != null || fieldDescription != null;
 
         typeName = ClassUtils.translateClassName(classType.getTypeName()).intern();
         final int lastDot = typeName.lastIndexOf('.');
@@ -325,6 +327,11 @@ public String getFieldUnit() {
         return fieldUnit;
     }
 
+    @Override
+    public String getFieldQuantity() {
+        return fieldQuantity;
+    }
+
     /**
      * @return field type strings (e.g. for the class Map&lt;Integer,String&gt; this returns
      *         '&lt;java.lang.Integer,java.lang.String&gt;'
@@ -640,9 +647,10 @@ protected static void printClassStructure(final ClassFieldDescription field, fin
             if (field.isAnnotationPresent()) {
                 LOGGER.atInfo().addArgument(mspace).addArgument(isSerialisable ? "  " : "//") //
                         .addArgument(field.getFieldUnit())
+                        .addArgument(field.getFieldQuantity())
                         .addArgument(field.getFieldDescription())
                         .addArgument(field.getFieldModifier())
-                        .log("{} {}         <meta-info: unit:'{}' description:'{}' modifier:'{}'>");
+                        .log("{} {}         <meta-info: unit:'{}' quantity:'{}' description:'{}' modifier:'{}'>");
             }
 
             field.getChildren().forEach(f -> printClassStructure((ClassFieldDescription) f, fullView, recursionLevel + 1));
@@ -685,6 +693,18 @@ private static String getFieldUnit(final AnnotatedElement annotatedElement) {
         return null;
     }
 
+    private static String getFieldQuantity(final AnnotatedElement annotatedElement) {
+        final MetaInfo[] annotationMeta = annotatedElement.getAnnotationsByType(MetaInfo.class);
+        if (annotationMeta.length > 0) {
+            return annotationMeta[0].quantity().intern();
+        }
+        final Quantity[] annotationQuantity = annotatedElement.getAnnotationsByType(Quantity.class);
+        if (annotationQuantity.length > 0) {
+            return annotationQuantity[0].value().intern();
+        }
+        return null;
+    }
+
     private static String spaces(final int spaces) {
         return CharBuffer.allocate(spaces).toString().replace('\0', ' ');
     }
diff --git a/serialiser/src/main/java/io/opencmw/serialiser/spi/WireDataFieldDescription.java b/serialiser/src/main/java/io/opencmw/serialiser/spi/WireDataFieldDescription.java
@@ -29,6 +29,7 @@ public class WireDataFieldDescription implements FieldDescription {
     // local references to source buffer needed for parsing
     private final IoSerialiser ioSerialiser;
     private String fieldUnit;
+    private String fieldQuantity;
     private String fieldDescription;
     private byte fieldModifier;
     private int dataSize;
@@ -151,6 +152,15 @@ public void setFieldUnit(final String fieldUnit) {
         this.fieldUnit = fieldUnit;
     }
 
+    @Override
+    public String getFieldQuantity() {
+        return fieldQuantity;
+    }
+
+    public void setFieldQuantity(final String fieldQuantity) {
+        this.fieldQuantity = fieldQuantity;
+    }
+
     /**
      * @return raw ioSerialiser reference this field was retrieved with the position in the underlying IoBuffer at the to be read field
      * N.B. this is a safe convenience method and not performance optimised
@@ -208,7 +218,7 @@ public Class<?> getType() {
 
     @Override
     public boolean isAnnotationPresent() {
-        return fieldUnit != null || fieldDescription != null;
+        return fieldUnit != null || fieldQuantity != null || fieldDescription != null;
     }
 
     @Override
@@ -233,9 +243,10 @@ protected static void printFieldStructure(final FieldDescription field, final in
         if (field.isAnnotationPresent()) {
             LOGGER.atInfo().addArgument(mspace) //
                     .addArgument(field.getFieldUnit())
+                    .addArgument(field.getFieldQuantity())
                     .addArgument(field.getFieldDescription())
                     .addArgument(field.getFieldModifier())
-                    .log("{}     <meta-info: unit:'{}' description:'{}' modifier:'{}'>");
+                    .log("{}     <meta-info: unit:'{}' quantity='{}' description:'{}' modifier:'{}'>");
         }
         field.getChildren().forEach(f -> printFieldStructure(f, recursionLevel + 1));
     }
diff --git a/serialiser/src/test/java/io/opencmw/serialiser/annotations/SerialiserAnnotationTests.java b/serialiser/src/test/java/io/opencmw/serialiser/annotations/SerialiserAnnotationTests.java
@@ -32,12 +32,14 @@ void testAnnotationGeneration() {
         final FieldDescription energyField = classFieldDescription.findChildField("energy");
         assertNotNull(energyField);
         assertEquals("GeV/u", energyField.getFieldUnit());
+        assertEquals("energy", energyField.getFieldQuantity());
         assertEquals("energy description", energyField.getFieldDescription());
         assertEquals(0, energyField.getFieldModifier());
 
         final FieldDescription temperatureField = classFieldDescription.findChildField("temperature");
         assertNotNull(temperatureField);
         assertEquals("°C", temperatureField.getFieldUnit());
+        assertEquals("temperature", temperatureField.getFieldQuantity());
         assertEquals("important temperature reading", temperatureField.getFieldDescription());
         assertEquals(0, temperatureField.getFieldModifier());
     }
@@ -64,27 +66,31 @@ void testCustomSerialiserIdentity(final Class<? extends IoBuffer> bufferClass) t
         final FieldDescription energyField = serialiserFieldDescriptions.findChildField("energy");
         assertNotNull(energyField);
         assertEquals("GeV/u", energyField.getFieldUnit());
+        assertEquals("energy", energyField.getFieldQuantity());
         assertEquals("energy description", energyField.getFieldDescription());
         assertEquals(0, energyField.getFieldModifier());
 
         final FieldDescription temperatureField = serialiserFieldDescriptions.findChildField("temperature");
         assertNotNull(temperatureField);
         assertEquals("°C", temperatureField.getFieldUnit());
+        assertEquals("temperature", temperatureField.getFieldQuantity());
         assertEquals("important temperature reading", temperatureField.getFieldDescription());
         assertEquals(0, temperatureField.getFieldModifier());
     }
 
     @Description("this class is used to test field annotation")
     public static class AnnotatedDataClass {
-        @MetaInfo(unit = "GeV/u", description = "energy description", modifier = 0)
+        @MetaInfo(unit = "GeV/u", quantity = "energy", description = "energy description", modifier = 0)
         public double energy;
 
         @Unit("°C")
+        @Quantity("temperature")
         @Description("important temperature reading")
         @Modifier(0)
         public double temperature;
 
         @Unit("V")
+        @Quantity("voltage")
         @Description("control variable")
         @Modifier(1)
         public double controlVariable;

Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,7 @@`
`9`	`9`	`@Target({ ElementType.FIELD, ElementType.TYPE })`
`10`	`10`	`public @interface MetaInfo {`
`11`	`11`	`String unit() default "";`
	`12`	`+ String quantity() default "";`
`12`	`13`	`String description() default "";`
`13`	`14`	`byte modifier() default 0;`
`14`	`15`	`}`
Original file line number	Diff line number	Diff line change
`@@ -422,6 +422,9 @@ public WireDataFieldDescription getFieldHeader() {`
`422`	`422`	`if (buffer.position() < dataStartPosition) {`
`423`	`423`	`lastFieldHeader.setFieldUnit(buffer.getString());`
`424`	`424`	`}`
	`425`	`+ if (buffer.position() < dataStartPosition) {`
	`426`	`+ lastFieldHeader.setFieldQuantity(buffer.getString());`
	`427`	`+ }`
`425`	`428`	`if (buffer.position() < dataStartPosition) {`
`426`	`429`	`lastFieldHeader.setFieldDescription(buffer.getString());`
`427`	`430`	`}`
`@@ -1456,6 +1459,7 @@ public WireDataFieldDescription putFieldHeader(final FieldDescription fieldDescr`
`1456`	`1459`
`1457`	`1460`	`if (isPutFieldMetaData() && fieldDescription.isAnnotationPresent() && dataType != DataType.END_MARKER) {`
`1458`	`1461`	`buffer.putString(fieldDescription.getFieldUnit());`
	`1462`	`+ buffer.putString(fieldDescription.getFieldQuantity());`
`1459`	`1463`	`buffer.putString(fieldDescription.getFieldDescription());`
`1460`	`1464`	`buffer.putByte(fieldDescription.getFieldModifier());`
`1461`	`1465`	`}`
`@@ -1470,6 +1474,7 @@ public WireDataFieldDescription putFieldHeader(final FieldDescription fieldDescr`
`1470`	`1474`	`lastFieldHeader = new WireDataFieldDescription(this, parent, fieldDescription.getFieldName(), dataType, headerStart, dataStartOffset, dataSize);`
`1471`	`1475`	`if (isPutFieldMetaData() && fieldDescription.isAnnotationPresent()) {`
`1472`	`1476`	`lastFieldHeader.setFieldUnit(fieldDescription.getFieldUnit());`
	`1477`	`+ lastFieldHeader.setFieldQuantity(fieldDescription.getFieldQuantity());`
`1473`	`1478`	`lastFieldHeader.setFieldDescription(fieldDescription.getFieldDescription());`
`1474`	`1479`	`lastFieldHeader.setFieldModifier(fieldDescription.getFieldModifier());`
`1475`	`1480`	`}`