From 82e7a03b3c330ce85bf2c8990ce70027a3916d37 Mon Sep 17 00:00:00 2001 From: Luca Frosini Date: Fri, 18 Dec 2020 12:06:31 +0100 Subject: [PATCH] Improved javadoc and types and properties description. --- .../model/reference/properties/Header.java | 10 ++--- .../properties/PropagationConstraint.java | 39 ++++++++++++++----- .../model/reference/properties/Property.java | 2 +- .../properties/PropertyDefinitionImpl.java | 3 +- .../informationsystem/utils/TypeVersion.java | 38 ++++++++++++++---- 5 files changed, 67 insertions(+), 25 deletions(-) diff --git a/src/main/java/org/gcube/informationsystem/model/reference/properties/Header.java b/src/main/java/org/gcube/informationsystem/model/reference/properties/Header.java index 9478cb2..5cee515 100644 --- a/src/main/java/org/gcube/informationsystem/model/reference/properties/Header.java +++ b/src/main/java/org/gcube/informationsystem/model/reference/properties/Header.java @@ -44,23 +44,23 @@ public interface Header extends Property { public static final String __CONTEXTS = "contexts"; - @ISProperty(name = UUID_PROPERTY, readonly = true, mandatory = true, nullable = false) + @ISProperty(name = UUID_PROPERTY, description = "This UUID is be used to identify the Entity or the Relation univocally.", readonly = true, mandatory = true, nullable = false) public UUID getUUID(); public void setUUID(UUID uuid); - @ISProperty(name = CREATOR_PROPERTY, readonly = true, mandatory = true, nullable = false) + @ISProperty(name = CREATOR_PROPERTY, description = "The user that created the Entity or the Relation. It is initialized at creation time. ", readonly = true, mandatory = true, nullable = false) public String getCreator(); @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = Element.DATETIME_PATTERN) - @ISProperty(name = CREATION_TIME_PROPERTY, readonly = true, mandatory = true, nullable = false) + @ISProperty(name = CREATION_TIME_PROPERTY, description = "Creation time. It represents the difference, measured in milliseconds, between the creation time and midnight, January 1, 1970, UTC.", readonly = true, mandatory = true, nullable = false) public Date getCreationTime(); - @ISProperty(name = MODIFIED_BY_PROPERTY, mandatory = true, nullable = false) + @ISProperty(name = MODIFIED_BY_PROPERTY, description = "The user that made the last update to the Entity or the Relation. At creation time, it assumes the same value of creator.", mandatory = true, nullable = false) public String getModifiedBy(); @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = Element.DATETIME_PATTERN) - @ISProperty(name = LAST_UPDATE_TIME_PROPERTY, mandatory = true, nullable = false) + @ISProperty(name = LAST_UPDATE_TIME_PROPERTY, description = "Last Update time. At creation time it assumes the same value of creationTime. It represents the difference, measured in milliseconds, between the creation time and midnight, January 1, 1970, UTC.", mandatory = true, nullable = false) public Date getLastUpdateTime(); } \ No newline at end of file diff --git a/src/main/java/org/gcube/informationsystem/model/reference/properties/PropagationConstraint.java b/src/main/java/org/gcube/informationsystem/model/reference/properties/PropagationConstraint.java index b110c38..fa26b01 100644 --- a/src/main/java/org/gcube/informationsystem/model/reference/properties/PropagationConstraint.java +++ b/src/main/java/org/gcube/informationsystem/model/reference/properties/PropagationConstraint.java @@ -12,6 +12,15 @@ import org.gcube.informationsystem.utils.TypeVersion; /** * @author Luca Frosini (ISTI - CNR) + * At any time entities and relations can be added or removed to/from a context or deleted. + * The PropagationConstraint property contained in each relation is a predefined Property type + * which indicates the behaviour to be held on a target entity when an event related to a context occurs + * in the source resource or directly to the relation. + * + * The default values of propagation constraints are: + * - IsRelatedTo: remove=keep, add=unpropagate; + * - ConsistsOf : remove=cascadeWhenOrphan, add=propagate. + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Propagation_Constraint */ @JsonDeserialize(as=PropagationConstraintImpl.class) @@ -27,21 +36,23 @@ public interface PropagationConstraint extends Property { public enum RemoveConstraint { /** - * When the source Entity is removed also the target - * Entity is removed but if and only if the latter has no other - * incoming Relation. + * When a remove action is performed on the source Entity of the relation, + * or directly on the relation, then the same remove action apart on + * the relation is performed to the target entity if it has no other incoming relations */ cascadeWhenOrphan, /** - * When the source Entity is removed also the target - * Entity is removed. + * When a remove action is performed on the source Entity of the relation, + * or directly on the relation, then the same remove action is performed on + * the relation and its target entity; */ cascade, /** - * When the source Entity is removed the target Entity - * is keep. + * When a remove action is performed on the source Entity of the relation, + * or directly on the relation, then the same remove action is performed on + * relation but never to the target entity. */ keep @@ -49,19 +60,29 @@ public interface PropagationConstraint extends Property { public enum AddConstraint { + /** + * When an 'add' action is performed on the source Entity of the relation, + * or directly on the relation, then the same add action is performed on + * the relation and its target Entity. + */ propagate, + /** + * When an 'add' action is performed on the source Entity of the relation, + * is performed on source relation only. Trying to perform an 'add' action on + * the relation has no effects. + */ unpropagate } - @ISProperty(name=REMOVE_PROPERTY) + @ISProperty(name=REMOVE_PROPERTY, description = "It indicates the behaviour to implement for the target Entity when a 'remove' action is performed on the source Resource. Remove actions are: (i) the operation of removing an instance from a context; (ii) the operation of deleting an instance (it has an impact on all contexts).", mandatory = true, nullable = false) public RemoveConstraint getRemoveConstraint(); public void setRemoveConstraint(RemoveConstraint removeConstraint); - @ISProperty(name=ADD_PROPERTY) + @ISProperty(name=ADD_PROPERTY, description = "It indicates the behaviour to implement for the target Entity when an 'add' action is performed on the source Resource. Add action is the operation of adding an instance to a context.", mandatory = true, nullable = false) public AddConstraint getAddConstraint(); public void setAddConstraint(AddConstraint addConstraint); diff --git a/src/main/java/org/gcube/informationsystem/model/reference/properties/Property.java b/src/main/java/org/gcube/informationsystem/model/reference/properties/Property.java index 8e0be1b..584ca2b 100644 --- a/src/main/java/org/gcube/informationsystem/model/reference/properties/Property.java +++ b/src/main/java/org/gcube/informationsystem/model/reference/properties/Property.java @@ -18,9 +18,9 @@ import org.gcube.informationsystem.utils.AdditionalPropertiesSerializer; import org.gcube.informationsystem.utils.TypeVersion; /** - * @author Luca Frosini (ISTI - CNR) * Root Class for Property types. It creates a base common type, which is useful * for management purpose. + * @author Luca Frosini (ISTI - CNR) */ // @JsonIgnoreProperties(ignoreUnknown=true) @JsonDeserialize(as=PropertyImpl.class) diff --git a/src/main/java/org/gcube/informationsystem/types/impl/properties/PropertyDefinitionImpl.java b/src/main/java/org/gcube/informationsystem/types/impl/properties/PropertyDefinitionImpl.java index 1035592..a21c08f 100644 --- a/src/main/java/org/gcube/informationsystem/types/impl/properties/PropertyDefinitionImpl.java +++ b/src/main/java/org/gcube/informationsystem/types/impl/properties/PropertyDefinitionImpl.java @@ -34,7 +34,6 @@ public final class PropertyDefinitionImpl implements PropertyDefinition { public final static String UUID_REGEX = "^([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}){1}$"; public final static String URI_REGEX = null; public final static String URL_REGEX = null; - public final static String TYPE_VERSION_REGEX = "^[1-9][0-9]{0,}\\.(0|([1-9][0-9]{0,}))\\.(0|([1-9][0-9]{0,}))$"; private String name= ""; private String description= ""; @@ -137,7 +136,7 @@ public final class PropertyDefinitionImpl implements PropertyDefinition { this.regexp = URL_REGEX; } if(TypeVersion.class.isAssignableFrom(type)){ - this.regexp = TYPE_VERSION_REGEX; + this.regexp = TypeVersion.TYPE_VERSION_REGEX; } } diff --git a/src/main/java/org/gcube/informationsystem/utils/TypeVersion.java b/src/main/java/org/gcube/informationsystem/utils/TypeVersion.java index 3d9d900..7595c09 100644 --- a/src/main/java/org/gcube/informationsystem/utils/TypeVersion.java +++ b/src/main/java/org/gcube/informationsystem/utils/TypeVersion.java @@ -3,17 +3,38 @@ package org.gcube.informationsystem.utils; import java.util.regex.Pattern; import org.gcube.com.fasterxml.jackson.annotation.JsonIgnore; -import org.gcube.informationsystem.types.impl.properties.PropertyDefinitionImpl; +/** + * A class representing and validating a version in the following format X.X.X (Major.Minor.Revision) + * Each part is an integer with no trailing zeros (e.g 1 and not 01). + * The version is validated by the regex defined in the static field {@link TypeVersion#TYPE_VERSION_REGEX} + * + * Accepted initial version is {@link TypeVersion#MINIMAL_VERSION_STRING} + * + * @author Luca Frosini (ISTI - CNR) + */ public class TypeVersion implements Comparable { - public final static String TYPE_VERSION_REGEX = PropertyDefinitionImpl.TYPE_VERSION_REGEX; + /** + * Regex validating the version + */ + public final static String TYPE_VERSION_REGEX = "^[1-9][0-9]{0,}\\.(0|([1-9][0-9]{0,}))\\.(0|([1-9][0-9]{0,}))$"; - public final static Pattern TYPE_VERSION_PATTERN; + private final static Pattern TYPE_VERSION_PATTERN; + /** + * Accepted initial version + */ public static final String MINIMAL_VERSION_STRING = "1.0.0"; + + /** + * Accepted initial version as TypeVersion instance + */ public static final TypeVersion MINIMAL_VERSION; + /** + * Default changelog description for the initial version + */ public static final String MINIMAL_VERSION_DESCRIPTION = "First Version"; static { @@ -52,12 +73,13 @@ public class TypeVersion implements Comparable { check(); } - /* - * The REGEX does not allow a 0.X.X Version. - * Anyway I added this check in case we decide to change the minimal version and the - * regex. - */ + protected void check() { + /* + * The REGEX does not allow a 0.X.X Version. + * Anyway I added this check in case we decide to change the minimal version and the + * regex. + */ if(this.compareTo(MINIMAL_VERSION)<0) { throw new RuntimeException("Minimal Allowed version is " + MINIMAL_VERSION_STRING); }