#2349 Introduce AbstractAuditModProp to represent properties modified…

… in an audit event

platform-pojo-bl/src/main/java/ua/com/fielden/platform/audit/AbstractAuditEntity.java

@@ -7,12 +7,19 @@
 import ua.com.fielden.platform.security.user.User;
 
 import java.util.Date;
+import java.util.Set;
 
 /**
  * Base type for all audit-entity types.
  * <p>
  * It is expected that in a typical scenario an audit-entity type has a key-member property representing a reference to the audited entity.
  * However, to provide more control in atypical scenarios, this base type leaves it up to specific audit-entity types to declare such a property.
+ * <p>
+ * It is also expected that each audit-entity type will participate in a one-to-many association with an entity type derived
+ * from {@link AbstractAuditModProp}, to represent properties, values of which changed during an audit event.
+ * Thus, all audit-types are expected to declare a corresponding collectional property and implement its accessor - {@link #getChangedProps()};
+ * an abstract setter is not declared in this base type because there is no suitable type for the setter's parameter
+ * (method types are contravariant in the parameter type).
  *
  * @param <E>  type of the audited entity
  */
@@ -25,6 +32,8 @@ public abstract class AbstractAuditEntity<E extends AbstractEntity<?>> extends A
 
     public abstract AbstractAuditEntity<E> setAuditedEntity(E auditedEntity);
 
+    public abstract Set<? extends AbstractAuditModProp<? extends AbstractAuditEntity<E>>> getChangedProps();
+
     @IsProperty
     @MapTo
     @Title(value = "Audited entity version", desc = "Version of the entity for which this audit record was created.")

platform-pojo-bl/src/main/java/ua/com/fielden/platform/audit/AbstractAuditModProp.java

@@ -0,0 +1,34 @@
+package ua.com.fielden.platform.audit;
+
+import ua.com.fielden.platform.entity.AbstractEntity;
+import ua.com.fielden.platform.entity.DynamicEntityKey;
+import ua.com.fielden.platform.entity.annotation.KeyType;
+import ua.com.fielden.platform.entity.meta.PropertyDescriptor;
+
+/**
+ * Base type for entity types that model a one-2-many association with an audit-entity to represent properties of the audited entity that were modified as part of an audit event.
+ * <p>
+ * This type does not declare any properties due to limited support for generically-typed properties.
+ * Therefore, it is up to specific entity types to declare the required properties, which are:
+ * <ol>
+ *   <li> {@code auditEntity: AE}; composite key-member.
+ *   <li> {@code property: PropertyDescriptor<AE>}; composite key-member.
+ *        <p>
+ *        Audit-entity type is used to parameterise the property descriptor because of the evolutionary model of audit-entity types.
+ *        The audited type cannot be used as it could result in a persisted property descriptor becoming invalid due to structural changes to the audited type.
+ * </ol>
+ *
+ * @param <AE>  type of the audit-entity
+ */
+@KeyType(DynamicEntityKey.class)
+public abstract class AbstractAuditModProp<AE extends AbstractAuditEntity<?>> extends AbstractEntity<DynamicEntityKey> {
+
+    public abstract AE getAuditedEntity();
+
+    public abstract AbstractAuditModProp<AE> setAuditedEntity(AE entity);
+
+    public abstract PropertyDescriptor<AE> getProperty();
+
+    public abstract AbstractAuditModProp<AE> setProperty(PropertyDescriptor<AE> propertyDescriptor);
+
+}