prepare for release

README.md

@@ -15,7 +15,7 @@
 
 ## Forewords
 
-This is a declarative, bit-level, message parser. All you have to do is write a [POJO](https://en.wikipedia.org/wiki/Plain_old_Java_object) that represents your message and annotate it. That's all. [Boxon](https://en.wikipedia.org/wiki/Boson) will take care of the rest for you.
+This is a declarative, bit-level, message parser. All you have to do is write a [DTO](https://en.wikipedia.org/wiki/Data_transfer_object) that represents your message and annotate it. That's all. [Boxon](https://en.wikipedia.org/wiki/Boson) will take care of the rest for you.
 
 If you want to use the parser straight away, just go [here](#examples).
 
@@ -46,7 +46,7 @@ Boxon...
    - Bit fields: bit fields with length from 1 to 2,147,483,647 bits.
    - Strings: fixed-length, variable-length and zero terminated strings with various encodings.
    - Arrays: fixed-length and variable-length arrays of built-in or user-defined element types.
-   - Objects: custom-type POJOs.
+   - Objects: custom-type DTOs.
    - Choices: supports integer keys.
  - User defined types (arbitrary combination of built-in types)
  - Has templates (annotated classes) that are not complex: they do not call each other uselessly complicating the structure (apart, necessarily, for `@BindArray`), no complicated chains of factories: it's just a parser that works.
@@ -142,27 +142,28 @@ You can get pre-built JARs (usable on JRE 11 or newer) from [Sonatype](https://o
     1. [Converters](#how-to-converters)
     2. [Custom annotations](#how-to-annotations)
 10. [Examples](#examples)
-     1. [Multi-message parser](#example-multi)
-     2. [Message composer](#example-composer)
+    1. [Multi-message parser](#example-multi)
+    2. [Message composer](#example-composer)
 11. [Contributing](#contributing)
 12. [Changelog](#changelog)
-     1. [version 3.2.0](#changelog-3.2.0)
-     2. [version 3.1.3](#changelog-3.1.3)
-     3. [version 3.1.2](#changelog-3.1.2)
-     4. [version 3.1.1](#changelog-3.1.1)
-     5. [version 3.1.0](#changelog-3.1.0)
-     6. [version 3.0.2](#changelog-3.0.2)
-     7. [version 3.0.1](#changelog-3.0.1)
-     8. [version 3.0.0](#changelog-3.0.0)
-     9. [version 2.1.2](#changelog-2.1.2)
-     10. [version 2.1.1](#changelog-2.1.1)
-     11. [version 2.1.0](#changelog-2.1.0)
-     12. [version 2.0.0](#changelog-2.0.0)
-     13. [version 1.1.0](#changelog-1.1.0)
-     14. [version 1.0.0](#changelog-1.0.0)
-     15. [version 0.0.2](#changelog-0.0.2)
-     16. [version 0.0.1](#changelog-0.0.1)
-     17. [version 0.0.0](#changelog-0.0.0)
+    1. [version 3.3.0](#changelog-3.3.0)
+    2. [version 3.2.0](#changelog-3.2.0)
+    3. [version 3.1.3](#changelog-3.1.3)
+    4. [version 3.1.2](#changelog-3.1.2)
+    5. [version 3.1.1](#changelog-3.1.1)
+    6. [version 3.1.0](#changelog-3.1.0)
+    7. [version 3.0.2](#changelog-3.0.2)
+    8. [version 3.0.1](#changelog-3.0.1)
+    9. [version 3.0.0](#changelog-3.0.0)
+    10. [version 2.1.2](#changelog-2.1.2)
+    11. [version 2.1.1](#changelog-2.1.1)
+    12. [version 2.1.0](#changelog-2.1.0)
+    13. [version 2.0.0](#changelog-2.0.0)
+    14. [version 1.1.0](#changelog-1.1.0)
+    15. [version 1.0.0](#changelog-1.0.0)
+    16. [version 0.0.2](#changelog-0.0.2)
+    17. [version 0.0.1](#changelog-0.0.1)
+    18. [version 0.0.0](#changelog-0.0.0)
 13. [License](#license)
 
 <br/>
@@ -677,7 +678,7 @@ Here are described the build-in special annotations.
 
 #### description
 
-Marks a POJO as an annotated message.
+Marks a DTO as an annotated message.
 
 #### annotation type
 
@@ -776,6 +777,9 @@ Assign a constant, calculated value to a field.
 
 Note that the evaluations are done AFTER parsing the entire message.
 
+This annotation with `runLast` to `true` can be used to force a parameter to have a certain value, after perhaps using it to calculate other parameters.
+Its effect cannot be undone.
+
 #### annotation type
 
 This annotation is bounded to a variable.
@@ -926,7 +930,7 @@ Response<String, byte[]> composedMessage = configurator.composeConfiguration("1.
 
 #### description
 
-Marks a POJO as an annotated configuration message.
+Marks a DTO as an annotated configuration message.
 
 #### annotation type
 
@@ -1174,12 +1178,14 @@ private int downloadTimeout;
 <a name="descriptor"></a>
 ## Descriptor
 
-Return a description of the loaded templates.
+Return a description of the loaded templates and configuration.
+It basically provides a description of the annotations in JSON format.
 
 ```java
 Descriptor descriptor = Descriptor.create(core);
 
-List<Map<String, Object>> descriptions = descriptor.describeTemplates();
+List<Map<String, Object>> templateDescriptions = descriptor.describeTemplates();
+List<Map<String, Object>> configurationDescriptions = descriptor.describeConfiguration();
 ```
 
 
@@ -1188,7 +1194,7 @@ List<Map<String, Object>> descriptions = descriptor.describeTemplates();
 <a name="extractor"></a>
 ## Extractor
 
-Extract values from a POJO using <a href="https://tools.ietf.org/html/rfc6901">RFC6901</a> syntax.
+Extract values from a DTO using <a href="https://tools.ietf.org/html/rfc6901">RFC6901</a> syntax.
 
 ```java
 Parser parser = Parser.create(core);
@@ -1540,6 +1546,15 @@ Pull requests are welcomed.
 <a name="changelog"></a>
 ## Changelog
 
+<a name="changelog-3.3.0"></a>
+### version 3.3.0 - 20240317
+
+- Added description of configuration.
+- Changed the key to reference a configuration (from `start` to `shortDescription`).
+- Corrected generation of parameter `MutuallyExclusive` on configuration description.
+- Corrected log text on enumeration error.
+- Fixed a test that occasionally fails.
+
 <a name="changelog-3.2.0"></a>
 ### version 3.2.0 - 20240312
 
@@ -1552,8 +1567,8 @@ Pull requests are welcomed.
 - Fixed validation on max value while composing a message.
 - Fixed number not written with the correct radix.
 - Made `shortDescription` mandatory in the annotation, as it should have been.
-- Added method to map a POJO into a `Map<String, Object>` in `ReflectionHelper`.
-- Added method `Configurator.composeConfiguration` accepting a POJO.
+- Added method to map a DTO into a `Map<String, Object>` in `ReflectionHelper`.
+- Added method `Configurator.composeConfiguration` accepting a DTO.
 - Corrected errors in the documentation.
 - Migrated from java 11 to java 21 for performance.
 
@@ -1569,7 +1584,7 @@ Pull requests are welcomed.
 <a name="changelog-3.1.1"></a>
 ### version 3.1.1 - 20240229
 
-- Fixed an error if annotating with `@Skip` as the last annotation of the POJO.
+- Fixed an error if annotating with `@Skip` as the last annotation of the DTO.
 
 <a name="changelog-3.1.0"></a>
 ### version 3.1.0 - 20240228
@@ -1592,7 +1607,7 @@ Pull requests are welcomed.
 - Added `CoreBuilder` to facilitate the creation of a `Core`: now it is no longer necessary to remember the order in which the methods should be called.
 - Added missing javadoc. Enhanced existing javadoc.
 - Added `@BindBitSet` binding for java `@BitSet`.
-- Added `Extractor`, used to programmatically extract values from a POJO.
+- Added `Extractor`, used to programmatically extract values from a DTO.
 - Removed `Bits`.
 - Enhanced binding validation.
 - Fixed a concurrency bug on the validation of alternatives.

pom.xml

@@ -5,7 +5,7 @@
 
 	<groupId>io.github.mtrevisan</groupId>
 	<artifactId>boxon</artifactId>
-	<version>3.2.0</version>
+	<version>3.3.0</version>
 
 	<packaging>jar</packaging>
 
@@ -80,7 +80,7 @@
 
 		<!-- Spring Expression -->
 		<!-- https://mvnrepository.com/artifact/org.springframework/spring-expression -->
-		<springframework.spring-expression.version>6.1.4</springframework.spring-expression.version>
+		<springframework.spring-expression.version>6.1.5</springframework.spring-expression.version>
 
 		<!-- FreeMarker -->
 		<!-- https://mvnrepository.com/artifact/org.freemarker/freemarker -->

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindArray.java

@@ -81,7 +81,7 @@
 	/**
 	 * The choices to select from, based on a prefix of a certain size, if any.
 	 *
-	 * @return The choices to select from, based on a prefix of a certain size (defaults to empty {@link ObjectChoices}).
+	 * @return	The choices to select from, based on a prefix of a certain size (defaults to empty {@link ObjectChoices}).
 	 */
 	ObjectChoices selectFrom() default @ObjectChoices;
 
@@ -110,7 +110,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindArrayPrimitive.java

@@ -98,7 +98,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindBitSet.java

@@ -85,7 +85,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindByte.java

@@ -69,7 +69,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindDouble.java

@@ -77,7 +77,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindFloat.java

@@ -77,7 +77,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindInt.java

@@ -77,7 +77,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindInteger.java

@@ -86,7 +86,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindList.java

@@ -74,7 +74,7 @@
 	/**
 	 * The choices to select from, based on a prefix of a certain size, if any.
 	 *
-	 * @return The choices to select from, based on a prefix of a certain size (defaults to empty {@link ObjectChoicesList}).
+	 * @return	The choices to select from, based on a prefix of a certain size (defaults to empty {@link ObjectChoicesList}).
 	 */
 	ObjectChoicesList selectFrom() default @ObjectChoicesList;
 
@@ -96,7 +96,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindLong.java

@@ -77,7 +77,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindObject.java

@@ -74,7 +74,7 @@
 	/**
 	 * The choices to select from, based on a prefix of a certain size.
 	 *
-	 * @return The choices to select from, based on a prefix of a certain size (defaults to empty {@link ObjectChoices}).
+	 * @return	The choices to select from, based on a prefix of a certain size (defaults to empty {@link ObjectChoices}).
 	 */
 	ObjectChoices selectFrom() default @ObjectChoices;
 
@@ -103,7 +103,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindShort.java

@@ -77,7 +77,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindString.java

@@ -83,7 +83,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/BindStringTerminated.java

@@ -90,7 +90,7 @@
 	/**
 	 * The choices to select from to apply a given converter.
 	 *
-	 * @return The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
+	 * @return	The choices to select from to apply a given converter (defaults to empty {@link ConverterChoices}).
 	 */
 	ConverterChoices selectConverterFrom() default @ConverterChoices;
 

src/main/java/io/github/mtrevisan/boxon/annotations/bindings/ObjectChoices.java

@@ -52,8 +52,8 @@
 	/**
 	 * The bit order to be considered when returning a representation of the first {@link #prefixLength() length} bits read as a header.
 	 *
-	 * @return	The byte order to be considered when returning a representation of the first {@link #prefixLength() length} bits read as a header
-	 * 	(defaults to {@link ByteOrder#BIG_ENDIAN}).
+	 * @return	The byte order to be considered when returning a representation of the first {@link #prefixLength() length} bits read as a
+	 * 	header (defaults to {@link ByteOrder#BIG_ENDIAN}).
 	 */
 	ByteOrder bitOrder() default ByteOrder.BIG_ENDIAN;
 

src/main/java/io/github/mtrevisan/boxon/annotations/configurations/AlternativeConfigurationField.java

@@ -62,12 +62,15 @@
 	String longDescription() default "";
 
 	/**
-	 * The unit of measure of the value (the format should follow <a href="https://ucum.org/ucum.html">UCUM</a>/<a href="https://en.wikipedia.org/wiki/Unified_Code_for_Units_of_Measure">ISO 80000</a> standard).
+	 * The unit of measure of the value (the format should follow
+	 * <a href="https://ucum.org/ucum.html">UCUM</a>/<a href="https://en.wikipedia.org/wiki/Unified_Code_for_Units_of_Measure">ISO 80000</a>
+	 * standard).
 	 *
 	 * @return	The unit of measure of the value.
 	 */
 	String unitOfMeasure() default "";
 
+
 	/**
 	 * The lowest protocol the field is in.
 	 *

src/main/java/io/github/mtrevisan/boxon/annotations/configurations/AlternativeSubField.java

@@ -47,12 +47,15 @@
 	String longDescription() default "";
 
 	/**
-	 * The unit of measure of the value (the format should follow <a href="https://ucum.org/ucum.html">UCUM</a>/<a href="https://en.wikipedia.org/wiki/Unified_Code_for_Units_of_Measure">ISO 80000</a> standard).
+	 * The unit of measure of the value (the format should follow
+	 * <a href="https://ucum.org/ucum.html">UCUM</a>/<a href="https://en.wikipedia.org/wiki/Unified_Code_for_Units_of_Measure">ISO 80000</a>
+	 * standard).
 	 *
 	 * @return	The unit of measure of the value.
 	 */
 	String unitOfMeasure() default "";
 
+
 	/**
 	 * The lowest protocol the field is in.
 	 *
@@ -98,7 +101,7 @@
 
 	/**
 	 * The default value of the field.
-	 * <p>For non-mutually exclusive enumeration fields this is an array.</p>
+	 * <p>For non-mutually exclusive enumeration fields this is an array (e.g. 'ONE|TWO|THREE').</p>
 	 * <p>If not present, the field is mandatory.</p>
 	 *
 	 * @return	The default value of the field.

src/main/java/io/github/mtrevisan/boxon/annotations/configurations/CompositeConfigurationField.java

@@ -63,6 +63,7 @@
 	 */
 	String longDescription() default "";
 
+
 	/**
 	 * The lowest protocol the field is in.
 	 *