From d6d9082e500620cf129ebaa0484364e410bb6133 Mon Sep 17 00:00:00 2001
From: Michael Hoennig <michael@hoennig.de>
Date: Mon, 24 Jun 2024 11:33:26 +0200
Subject: [PATCH] add some documentation

---
 ...HsHostingAssetEntityValidatorRegistry.java |  1 +
 .../hs/hosting/asset/validators/README.md     | 40 +++++++++++++++++++
 2 files changed, 41 insertions(+)
 create mode 100644 src/main/java/net/hostsharing/hsadminng/hs/hosting/asset/validators/README.md

diff --git a/src/main/java/net/hostsharing/hsadminng/hs/hosting/asset/validators/HsHostingAssetEntityValidatorRegistry.java b/src/main/java/net/hostsharing/hsadminng/hs/hosting/asset/validators/HsHostingAssetEntityValidatorRegistry.java
index 39b765f9..1b9a5241 100644
--- a/src/main/java/net/hostsharing/hsadminng/hs/hosting/asset/validators/HsHostingAssetEntityValidatorRegistry.java
+++ b/src/main/java/net/hostsharing/hsadminng/hs/hosting/asset/validators/HsHostingAssetEntityValidatorRegistry.java
@@ -14,6 +14,7 @@ public class HsHostingAssetEntityValidatorRegistry {
 
     private static final Map<Enum<HsHostingAssetType>, HsEntityValidator<HsHostingAssetEntity>> validators = new HashMap<>();
     static {
+        // HOWTO: add (register) new HsHostingAssetType-specific validators
         register(CLOUD_SERVER, new HsCloudServerHostingAssetValidator());
         register(MANAGED_SERVER, new HsManagedServerHostingAssetValidator());
         register(MANAGED_WEBSPACE, new HsManagedWebspaceHostingAssetValidator());
diff --git a/src/main/java/net/hostsharing/hsadminng/hs/hosting/asset/validators/README.md b/src/main/java/net/hostsharing/hsadminng/hs/hosting/asset/validators/README.md
new file mode 100644
index 00000000..52e03058
--- /dev/null
+++ b/src/main/java/net/hostsharing/hsadminng/hs/hosting/asset/validators/README.md
@@ -0,0 +1,40 @@
+### HsHostingAssetEntity-Validation
+
+There is just a single `HsHostingAssetEntity` class for all types of hosting assets like Managed-Server, Managed-Webspace, Unix-Users, Databases etc. These are distinguished by  `HsHostingAssetType HsHostingAssetEntity.type`.
+
+For each of these types, a distinct validator has to be 
+implemented as a subclass of `HsHostingAssetEntityValidator` which needs to be registered (see `HsHostingAssetEntityValidatorRegistry`) for the relevant type(s).
+
+### Kinds of Validations
+
+#### Identifier validation
+
+The identifier of a Hosting-Asset is for example the Webspace-Name like "xyz00" or a Unix-User-Name like "xyz00-test".
+
+To validate the identifier, vverride the method `identifierPattern(...)` and return a regular expression to validate the identifier against. The regular expression can depend on the actual entity instance.
+
+#### Reference validation
+
+References in this context are:
+- the related Booking-Item,
+- the parent-Hosting-Asset,
+- the Assigned-To-Hosting-Asset and
+- the Contact.
+
+The first parameters of the `HsHostingAssetEntityValidator` superclass take rule descriptors for these references. These are all Subclasses fo   
+
+### Validation Order
+
+The validations are called in a sensible order. E.g. if a property value is not numeric, it makes no sense to check the total sum of such values to be within certain numeric values. And if the related booking item is of wrong type, it makes no sense to validate limits against sub-entities.
+
+Properties are validated all at once, though. Thus, if multiple properties fail validation, all error messages are returned at once.
+
+In general, the validation es executed in this order:
+
+1. the entity itself
+   1. its references
+   2. its properties
+2. the limits of the parent entity (parent asset + booking item)
+3. limits against the own own-sub-entities
+
+This implementation can be found in `HsHostingAssetEntityValidator.validate`.