Moved some interfaces and enhanced docs

common/README.md

@@ -0,0 +1,113 @@
+# objects4j-common
+Some interfaces, annotations and validators.
+
+## Bean validation (JSR 303)
+Constraint annotations and the corresponding validators.
+
+### [@IsFile](src/main/java/org/fuin/objects4j/common/IsFile.java)
+Verifies that the annotated java File is a file and not a directory
+```Java
+@IsFile
+private File myDir;
+```
+
+### [@FileExists](src/main/java/org/fuin/objects4j/common/FileExists.java)
+Verifies that the file exists
+```Java
+@FileExists
+private File myFile;
+```
+
+### [@IsDirectory](src/main/java/org/fuin/objects4j/common/IsDirectory.java)
+Verifies that it's a directory and not a file
+```Java
+@IsDirectory
+private File myDir;
+```
+
+### [@HasPublicStaticIsValidMethod](src/main/java/org/fuin/objects4j/common/HasPublicStaticIsValidMethod.java) / [@HasPublicStaticIsValidMethods](src/main/java/org/fuin/objects4j/common/HasPublicStaticIsValidMethods.java)
+Tags a class that has a public static method that verifies if a given value can be converted into an instance of the class.
+The default is a method named "isValid" with a String parameter. You can change this using the annotation arguments.
+```Java
+@HasPublicStaticIsValidMethod
+public class IBAN {
+    public static boolean isValid(String ibanStr) {
+        ...
+    }
+}
+```
+
+### [@HasPublicStaticValueOfMethod](src/main/java/org/fuin/objects4j/common/HasPublicStaticValueOfMethod.java) / [@HasPublicStaticValueOfMethods](src/main/java/org/fuin/objects4j/common/HasPublicStaticValueOfMethods.java)
+Tags a class that has a public static method that converts if a given value into an instance of the class.
+The default is a method named "valueOf" with a String parameter. You can change this using the annotation arguments.
+```Java
+@HasPublicStaticValueOfMethod
+public class IBAN {
+    public static IBAN valueOf(String ibanStr) {
+        return new IBAN(ibanStr);
+    }
+}
+```
+
+## Interfaces
+Annotated classes provide some special functionality.
+
+### String methods
+
+#### [TraceStringCapable](src/main/java/org/fuin/objects4j/common/TraceStringCapable.java)
+Marker interface for classes that provide a special representation for trace output.
+
+#### [AsStringCapable](src/main/java/org/fuin/objects4j/common/AsStringCapable.java)
+Objects that provides a string representation of itself that is used for displaying business values.
+In contrast to that is the standard "toString()" method often used for technical information.
+
+```Java
+public class CompanyName implements TraceStringCapable, AsStringCapable {
+
+    private String str;
+
+    @Override
+    public String asString() {
+        return str; 
+    }
+
+    @Override
+    public String toTraceString() {
+        return str + "[" + this.hashCode() + "]";
+    }
+
+    @Override
+    public String toString() {
+        return "CompanyName{str=" + str + '}';
+    }
+
+}
+```
+
+### [MarshalInformation](src/main/java/org/fuin/objects4j/common/MarshalInformation.java)
+Tags any instance that is capable of delivering additional information for serialization/deserialization. 
+In contrast to XML where the element name can be used to determine the type of the object, as with JSON 
+there is often just an unknown type of object. This interface helps to determine the full qualified name 
+of the class and the tag name to use.
+
+### [ExceptionShortIdentifable](src/main/java/org/fuin/objects4j/common/ExceptionShortIdentifable.java)
+Marks an exception that provides a unique short identifier. This identifier should be human-readable and 
+is meant to be displayed to an end user. A service desk can use it to identify the type of error quickly 
+and for example attach a guideline to it that explains how to solve the problem.
+
+### [ToExceptionCapable](src/main/java/org/fuin/objects4j/common/ToExceptionCapable.java)
+Tags objects that can create an exception based on their data.
+
+### [UniquelyNumbered](src/main/java/org/fuin/objects4j/common/UniquelyNumbered.java)
+Tags objects that provide a unique (long) number in their context.
+This is used along with [UniquelyNumberedException](src/main/java/org/fuin/objects4j/common/UniquelyNumberedException.java) 
+which is a base class for exceptions that have such a unique ID.
+
+### [ValueObject](src/main/java/org/fuin/objects4j/common/ValueObject.java)
+Immutable object that represents an object whose equality isn't based on identity.
+That means instances of this type are equal when they have the same value, not necessarily being the same object.
+A Java record is a perfect match for this kind of object. 
+
+### [ValueObjectWithBaseType](src/main/java/org/fuin/objects4j/common/ValueObjectWithBaseType.java)
+Value object that may be expressed in a more general type with relaxed restrictions.
+Often basic Java types like String or numeric values (Long, Integer, ...) are used for this.

core/src/main/java/org/fuin/objects4j/core/AsStringCapable.java → common/src/main/java/org/fuin/objects4j/common/AsStringCapable.java

@@ -15,7 +15,7 @@
  * You should have received a copy of the GNU Lesser General Public License
  * along with this library. If not, see http://www.gnu.org/licenses/.
  */
-package org.fuin.objects4j.core;
+package org.fuin.objects4j.common;
 
 /**
  * Provides a string representation of itself.

common/src/main/java/org/fuin/objects4j/common/ExceptionShortIdentifable.java

@@ -18,7 +18,7 @@
 package org.fuin.objects4j.common;
 
 /**
- * Marks an exception that provides a unique short identifier. This identifier should be human readable and is meant to be displayed to an
+ * Marks an exception that provides a unique short identifier. This identifier should be human-readable and is meant to be displayed to an
  * end user. A service desk can use it to identify the type of error quickly and for example attach a guideline to it that explains how to
  * solve the problem.
  */

common/src/main/java/org/fuin/objects4j/common/MarshalInformation.java

@@ -18,9 +18,9 @@
 package org.fuin.objects4j.common;
 
 /**
- * Tags any instance that is capable of delivering additional informations for serialization/deserialization. In contrast to XML where the
+ * Tags any instance that is capable of delivering additional information for serialization/deserialization. In contrast to XML where the
  * element name can be used to determine the type of the object, as with JSON there is often just an unknown type of object. This class
- * helps determining the full qualified name of the class and the tag name to use.
+ * helps to determine the full qualified name of the class and the tag name to use.
  * 
  * @param <DATA>
  *            Type of data returned.

core/src/main/java/org/fuin/objects4j/core/ValueObject.java → common/src/main/java/org/fuin/objects4j/common/ValueObject.java

@@ -15,11 +15,11 @@
  * You should have received a copy of the GNU Lesser General Public License
  * along with this library. If not, see http://www.gnu.org/licenses/.
  */
-package org.fuin.objects4j.core;
+package org.fuin.objects4j.common;
 
 /**
- * Immutable object that represents an object whose equality isn't based on identity. That means instances of this type are equal when they
- * have the same value, not necessarily being the same object.
+ * Immutable object that represents an object whose equality isn't based on identity.
+ * That means instances of this type are equal when they have the same value, not necessarily being the same object.
  */
 public interface ValueObject {
 

core/src/main/java/org/fuin/objects4j/core/ValueObjectConverter.java → common/src/main/java/org/fuin/objects4j/common/ValueObjectConverter.java

@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU Lesser General Public License
  * along with this library. If not, see http://www.gnu.org/licenses/.
  */
-package org.fuin.objects4j.core;
+package org.fuin.objects4j.common;
+
+import org.fuin.objects4j.common.ValueObjectWithBaseType;
 
 /**
  * Converts a value object into it's base type and back.

core/src/main/java/org/fuin/objects4j/core/ValueObjectWithBaseType.java → common/src/main/java/org/fuin/objects4j/common/ValueObjectWithBaseType.java

@@ -15,13 +15,13 @@
  * You should have received a copy of the GNU Lesser General Public License
  * along with this library. If not, see http://www.gnu.org/licenses/.
  */
-package org.fuin.objects4j.core;
+package org.fuin.objects4j.common;
 
 import jakarta.validation.constraints.NotNull;
 
 /**
- * Value object that may be expressed in a more general type with relaxed restrictions. Often basic Java types like String or numeric values
- * (Long, Integer, ...) are used for this.
+ * Value object that may be expressed in a more general type with relaxed restrictions.
+ * Often basic Java types like String or numeric values (Long, Integer, ...) are used for this.
  * 
  * @param <BASE_TYPE>
  *            Base type that may represent this type of value object.

core/src/main/java/org/fuin/objects4j/core/ValueOfCapable.java → common/src/main/java/org/fuin/objects4j/common/ValueOfCapable.java

@@ -15,12 +15,12 @@
  * You should have received a copy of the GNU Lesser General Public License
  * along with this library. If not, see http://www.gnu.org/licenses/.
  */
-package org.fuin.objects4j.core;
+package org.fuin.objects4j.common;
 
 import jakarta.annotation.Nullable;
 
 /**
- * Can convert a string into a type.
+ * Functional interface used ton convert a string into a type.
  *
  * @param <T>
  *            Target type.

common/src/main/java/org/fuin/objects4j/common/package-info.java

@@ -19,6 +19,6 @@
  */
 
 /**
- * Contains base classes like utilities and general annotation.
+ * Some interfaces, annotations and validators.
  */
 package org.fuin.objects4j.common;

common/src/test/java/org/fuin/objects4j/common/HasPublicStaticIsValidMethodValidatorTest.java

@@ -137,7 +137,7 @@ private static String first(Set<?> violations) {
         return violations.stream().map(v -> ((ConstraintViolation<?>) v).getMessage()).findFirst().orElse(null);
     }
 
-    @HasPublicStaticIsValidMethod
+    @HasPublicStaticIsValidMethod(method = "isValid", param = String.class)
     public static final class MyClassValid {
         public static boolean isValid(String str) {
             if (str == null) {

core/README.md

@@ -0,0 +1,37 @@
+# objects4j-core
+A library with common Java types that are mostly immutable value objects.
+
+## Description
+Provides Value Objects (immutable objects) that represents an object whose equality isn't based on identity. 
+That means instances of this type are equal when they have the same value, not necessarily being the same object. 
+Additionally, some helper classes (like validators) are placed in this package.
+
+**Base classes** that allow an easy implementation of concrete classes. 
+* [AbstractIntegerValueObject](src/main/java/org/fuin/objects4j/core/AbstractIntegerValueObject.java) - A value object that is based on an integer.
+* [AbstractLongValueObject](src/main/java/org/fuin/objects4j/core/AbstractLongValueObject.java) - A value object that is based on a long.
+* [AbstractStringValueObject](src/main/java/org/fuin/objects4j/core/AbstractStringValueObject.java) - A value object that is based on a string.
+* [AbstractUuidValueObject](src/main/java/org/fuin/objects4j/core/AbstractUuidValueObject.java) - A value object that is based on a UUID.
+
+**Predefined Value Objects**
+* [CurrencyAmount](src/main/java/org/fuin/objects4j/core/CurrencyAmount.java) - Combines a currency (like "USD" or "EUR") with a big decimal value (like "**512 EUR**"). There is also a [CurrencyAmountConverter](src/main/java/org/fuin/objects4j/core/CurrencyAmountConverter.java) (JAX-B, JSON-B and JPA) and a [CurrencyAmountValidator](src/main/java/org/fuin/objects4j/core/CurrencyAmountValidator.java) (```@CurrencyAmountStr```) available.
+* [EmailAddress](src/main/java/org/fuin/objects4j/core/EmailAddress.java) - Email address. There is also a [EmailAddressConverter](src/main/java/org/fuin/objects4j/core/EmailAddressConverter.java) (JAX-B, JSON-B and JPA) and a [EmailAddressValidator](src/main/java/org/fuin/objects4j/core/EmailAddressValidator.java) (```@EmailAddressStr```) available.
+* [Password](src/main/java/org/fuin/objects4j/core/Password.java) - A password with a length between 8 and 20 characters. There is also a [PasswordConverter](src/main/java/org/fuin/objects4j/core/PasswordConverter.java) (JAX-B, JSON-B and JPA) and a [PasswordValidator](src/main/java/org/fuin/objects4j/core/PasswordValidator.java) (```@PasswordStr```) available.
+* [PasswordSha512](src/main/java/org/fuin/objects4j/core/PasswordSha512.java) - A SHA-512 hashed password that is HEX encoded. There is also a [PasswordSha512Converter](src/main/java/org/fuin/objects4j/core/PasswordSha512Converter.java) (JAX-B, JSON-B and JPA) and a [PasswordSha512Validator](src/main/java/org/fuin/objects4j/core/PasswordSha512Validator.java) (```@PasswordSha512Str```) available.
+* [UserName](src/main/java/org/fuin/objects4j/core/UserName.java) - User name with restricted character set and length. There is also a [UserNameConverter](src/main/java/org/fuin/objects4j/core/UserNameConverter.java) (JAX-B, JSON-B and JPA) and a [UserNameValidator](src/main/java/org/fuin/objects4j/core/UserNameValidator.java) (```@UserNameStr```) available.
+* [Hour](src/main/java/org/fuin/objects4j/core/Hour.java) - Hour of a day like '**23:59**' (24 hours, sometimes called Military Time). There is also an [HourConverter](src/main/java/org/fuin/objects4j/core/HourConverter.java) (JAX-B, JSON-B and JPA) and an [HourStrValidator](src/main/java/org/fuin/objects4j/core/HourStrValidator.java) (```@HourStr```) available.
+* [HourRange](src/main/java/org/fuin/objects4j/core/HourRange.java) - Range of hours of a day like '**00:00-24:00**' (24 hours, sometimes called Military Time). There is also an [HourRangeConverter](src/main/java/org/fuin/objects4j/core/HourRangeConverter.java) (JAX-B, JSON-B and JPA) and an [HourRangeStrValidator](src/main/java/org/fuin/objects4j/core/HourRangeStrValidator.java) (```@HourRangeStr```) available.
+* [HourRanges](src/main/java/org/fuin/objects4j/core/HourRanges.java) - Multiple range of hours of a day like '**09:00-12:00+13:00-17:00**'. There is also an [HourRangesConverter](src/main/java/org/fuin/objects4j/core/HourRangesConverter.java) (JAX-B, JSON-B and JPA) and an [HourRangesStrValidator](src/main/java/org/fuin/objects4j/core/HourRangesStrValidator.java) (```@HourRangesStr```) available.
+* [DayOfTheWeek](src/main/java/org/fuin/objects4j/core/DayOfTheWeek.java) - The days of the week '**Mon**'-'**Sun**'(from Monday to Sunday) plus '**PH**' (Public Holiday). There is also an [DayOfTheWeekConverter](src/main/java/org/fuin/objects4j/core/DayOfTheWeekConverter.java) (JAX-B, JSON-B and JPA) and an [DayOfTheWeekStrValidator](src/main/java/org/fuin/objects4j/core/DayOfTheWeekStrValidator.java) (```@DayOfTheWeekStr```) available.
+* [MultiDayOfTheWeek](src/main/java/org/fuin/objects4j/core/MultiDayOfTheWeek.java) - Multiple days of the week like '**Mon/Tue/Wed-Fri/PH**' (Monday AND Tuesday AND Wednesday TO Friday AND Public Holidays). There is also an [MultiDayOfTheWeekConverter](src/main/java/org/fuin/objects4j/core/MultiDayOfTheWeekConverter.java) (JAX-B, JSON-B and JPA) and an [MultiDayOfTheWeekStrValidator](src/main/java/org/fuin/objects4j/core/MultiDayOfTheWeekStrValidator.java) (```@MultiDayOfTheWeekStr```) available.
+* [DayOpeningHours](src/main/java/org/fuin/objects4j/core/DayOpeningHours.java) - Multiple range of hours of single a day like '**Mon 09:00-12:00+13:00-17:00**'. There is also an [DayOpeningHoursConverter](src/main/java/org/fuin/objects4j/core/DayOpeningHoursConverter.java) (JAX-B, JSON-B and JPA) and an [DayOpeningHoursStrValidator](src/main/java/org/fuin/objects4j/core/DayOpeningHoursStrValidator.java) (```@DayOpeningHoursStr```) available.
+* [WeeklyOpeningHours](src/main/java/org/fuin/objects4j/core/WeeklyOpeningHours.java) - weekly opening hours separated by a comma like '**Mon-Fri 09:00-12:00+13:00-17:00,Sat/Sun 09:-12:00**'. There is also an [WeeklyOpeningHoursConverter](src/main/java/org/fuin/objects4j/core/WeeklyOpeningHoursConverter.java) (JAX-B, JSON-B and JPA) and an [WeeklyOpeningHoursStrValidator](src/main/java/org/fuin/objects4j/core/WeeklyOpeningHoursStrValidator.java) (```@WeeklyOpeningHoursStr```) available.
+
+**Validators**
+* [DateStrValidator](src/main/java/org/fuin/objects4j/core/DateStrValidator.java) - Validates that a string is a date using the current locale ([@DateStr](src/main/java/org/fuin/objects4j/core/DateStr.java)).
+* [LocaleStrValidator](src/main/java/org/fuin/objects4j/core/LocaleStrValidator.java) - Validates that a string is a valid locale ([@LocaleStr](src/main/java/org/fuin/objects4j/core/LocaleStr.java)). 
+* [PropertiesContainValidator](src/main/java/org/fuin/objects4j/core/PropertiesContainValidator.java) - Validates that a string is one out of a list of constants ([@PropertiesContain("one", "two", "three")](src/main/java/org/fuin/objects4j/core/PropertiesContain.java)).
+* [TrimmedNotEmptyValidator](src/main/java/org/fuin/objects4j/core/TrimmedNotEmptyValidator.java) - Validates that a string is not empty after it was trimmed [@TrimmedNotEmpty](src/main/java/org/fuin/objects4j/core/TrimmedNotEmpty.java)
+* [UUIDStrValidator](src/main/java/org/fuin/objects4j/core/UUIDStrValidator.java) - Validates that a string is a valid UUID ([@UUIDStr](src/main/java/org/fuin/objects4j/core/UUIDStr.java)). 
+
+**Other**
+* [KeyValue](src/main/java/org/fuin/objects4j/core/KeyValue.java) - Container for a key (String) and a value (Object).

core/src/main/java/org/fuin/objects4j/core/AbstractIntegerValueObject.java

@@ -17,6 +17,8 @@
  */
 package org.fuin.objects4j.core;
 
+import org.fuin.objects4j.common.ValueObjectWithBaseType;
+
 import java.io.Serial;
 import java.io.Serializable;
 

core/src/main/java/org/fuin/objects4j/core/AbstractLongValueObject.java

@@ -17,6 +17,8 @@
  */
 package org.fuin.objects4j.core;
 
+import org.fuin.objects4j.common.ValueObjectWithBaseType;
+
 import java.io.Serial;
 import java.io.Serializable;
 

core/src/main/java/org/fuin/objects4j/core/AbstractStringValueObject.java

@@ -17,6 +17,9 @@
  */
 package org.fuin.objects4j.core;
 
+import org.fuin.objects4j.common.AsStringCapable;
+import org.fuin.objects4j.common.ValueObjectWithBaseType;
+
 import java.io.Serial;
 import java.io.Serializable;
 

core/src/main/java/org/fuin/objects4j/core/AbstractUuidValueObject.java

@@ -18,6 +18,7 @@
 package org.fuin.objects4j.core;
 
 import org.fuin.objects4j.common.HasPublicStaticIsValidMethod;
+import org.fuin.objects4j.common.ValueObjectWithBaseType;
 
 import java.io.Serial;
 import java.io.Serializable;

core/src/main/java/org/fuin/objects4j/core/CurrencyAmount.java

@@ -19,10 +19,12 @@
 
 import jakarta.annotation.Nullable;
 import jakarta.validation.constraints.NotNull;
+import org.fuin.objects4j.common.AsStringCapable;
 import org.fuin.objects4j.common.ConstraintViolationException;
 import org.fuin.objects4j.common.Contract;
 import org.fuin.objects4j.common.HasPublicStaticIsValidMethod;
 import org.fuin.objects4j.common.HasPublicStaticValueOfMethod;
+import org.fuin.objects4j.common.ValueObjectWithBaseType;
 import org.fuin.objects4j.ui.Label;
 import org.fuin.objects4j.ui.ShortLabel;
 

core/src/main/java/org/fuin/objects4j/core/DayOfTheWeek.java

@@ -20,10 +20,12 @@
 import jakarta.annotation.Nullable;
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.NotNull;
+import org.fuin.objects4j.common.AsStringCapable;
 import org.fuin.objects4j.common.ConstraintViolationException;
 import org.fuin.objects4j.common.Contract;
 import org.fuin.objects4j.common.HasPublicStaticIsValidMethod;
 import org.fuin.objects4j.common.HasPublicStaticValueOfMethod;
+import org.fuin.objects4j.common.ValueObjectWithBaseType;
 import org.fuin.objects4j.ui.Label;
 import org.fuin.objects4j.ui.Prompt;
 import org.fuin.objects4j.ui.ShortLabel;

core/src/main/java/org/fuin/objects4j/core/DayOpeningHours.java

@@ -20,10 +20,12 @@
 import jakarta.annotation.Nullable;
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.NotNull;
+import org.fuin.objects4j.common.AsStringCapable;
 import org.fuin.objects4j.common.ConstraintViolationException;
 import org.fuin.objects4j.common.Contract;
 import org.fuin.objects4j.common.HasPublicStaticIsValidMethod;
 import org.fuin.objects4j.common.HasPublicStaticValueOfMethod;
+import org.fuin.objects4j.common.ValueObjectWithBaseType;
 import org.fuin.objects4j.core.HourRanges.ChangeType;
 import org.fuin.objects4j.ui.Prompt;
 

core/src/main/java/org/fuin/objects4j/core/KeyValue.java

@@ -19,6 +19,7 @@
 
 import jakarta.validation.constraints.NotNull;
 import org.fuin.objects4j.common.Contract;
+import org.fuin.objects4j.common.ValueObject;
 
 import javax.annotation.concurrent.Immutable;
 import java.util.Collection;

jackson/README.md

@@ -0,0 +1,21 @@
+# objects4j-jackson
+FasterXML [Jackson](https://github.com/FasterXML/jackson) JSON serializer/deserializer for the types defined in [Core](../core).
+
+## Getting started
+Simply add the [Objects4JJacksonAdapterModule](src/main/java/org/fuin/objects4j/jackson/Objects4JJacksonAdapterModule.java) 
+to your object mapper to activate the serializers and deserializer.
+
+```java
+@Configuration
+public class SpringBootConfig {
+
+    @Bean
+    @Primary
+    public ObjectMapper jsonMapper() {
+        return new ObjectMapper()
+                .setSerializationInclusion(JsonInclude.Include.NON_NULL)
+                .registerModule(new Objects4JJacksonAdapterModule());
+    }
+
+}
+```