From 64230d5fc201bb31acafe7b4bdb938b9fd187b27 Mon Sep 17 00:00:00 2001 From: Luca Frosini Date: Tue, 22 Dec 2020 15:09:55 +0100 Subject: [PATCH] Added/fixed documentation --- .../relations/isrelatedto/Activates.java | 31 ++++++++++++++- .../relations/isrelatedto/CallsFor.java | 8 +++- .../relations/isrelatedto/Demands.java | 2 + .../relations/isrelatedto/DependsOn.java | 8 +++- .../relations/isrelatedto/Discovers.java | 8 ++-- .../relations/isrelatedto/Enables.java | 18 ++++++++- .../relations/isrelatedto/Hosts.java | 7 ++-- .../relations/isrelatedto/Involves.java | 6 ++- .../relations/isrelatedto/IsCustomizedBy.java | 6 ++- .../relations/isrelatedto/IsOwnedBy.java | 6 ++- .../relations/isrelatedto/IsPluginOf.java | 6 ++- .../relations/isrelatedto/Manages.java | 2 +- .../relations/isrelatedto/Requires.java | 39 ++++++++++++++++++- .../reference/relations/isrelatedto/Uses.java | 6 ++- 14 files changed, 128 insertions(+), 25 deletions(-) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Activates.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Activates.java index c2909f1..d420afd 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Activates.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Activates.java @@ -9,9 +9,27 @@ import org.gcube.informationsystem.types.reference.Change; import org.gcube.informationsystem.types.reference.TypeMetadata; import org.gcube.informationsystem.utils.TypeVersion; import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.ActivatesImpl; +import org.gcube.resourcemanagement.model.reference.entities.resources.EService; +import org.gcube.resourcemanagement.model.reference.entities.resources.HostingNode; +import org.gcube.resourcemanagement.model.reference.entities.resources.RunningPlugin; import org.gcube.resourcemanagement.model.reference.entities.resources.Service; +import org.gcube.resourcemanagement.model.reference.entities.resources.VirtualMachine; /** + * Activates has a {@link Service} instance both as source and target as well as + * {@link CallsFor} but with a complete different semantic. + * Activates is used to indicates that the source {@link Service} of the relation + * enable the operation of the target Service. + * Examples are between a {@link VirtualMachine} and an {@link HostingNode} to capture + * the {@link VirtualMachine} is operating the {@link HostingNode}. + * Another example is between a {@link VirtualMachine} and an {@link EService}, + * e.g., between a {@link VirtualMachine} and a database instance. + * This relation can be created also between an {@link HostingNode} and one + * {@link EService}, e.g., to represent a container e.g., Tomcat and the web-service(s) + * is operating. + * Activates is also used between an {@link EService} and a {@link RunningPlugin} + * which enrich the functionality offered by the source service. + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Activates * * @author Luca Frosini (ISTI - CNR) @@ -19,7 +37,18 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Service; @JsonDeserialize(as=ActivatesImpl.class) @TypeMetadata( name = Activates.NAME, - description = "", + description = "Activates has a {@link Service} instance both as source and target as " + + "well as {@link CallsFor} but with a complete different semantic.\n" + + "Activates is used to indicates that the source {@link Service} of the relation " + + "enable the operation of the target Service. \n" + + "Examples are between a {@link VirtualMachine} and an {@link HostingNode} to " + + "capture the {@link VirtualMachine} is operating the {@link HostingNode}. \n" + + "Another example is between a {@link VirtualMachine} and an {@link EService}, " + + "e.g., between a {@link VirtualMachine} and a database instance.\n" + + "This relation can be created also between an {@link HostingNode} and one {@link EService}, " + + "e.g., to represent a container e.g., Tomcat and the web-service(s) is operating. \n" + + "Activates is also used between an {@link EService} and a {@link RunningPlugin} which " + + "enrich the functionality offered by the source service.", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/CallsFor.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/CallsFor.java index 75b3070..f8fd5de 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/CallsFor.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/CallsFor.java @@ -12,6 +12,10 @@ import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.CallsForImp import org.gcube.resourcemanagement.model.reference.entities.resources.Service; /** + * A {@link Service} instance can require another {@link Service} instance to properly + * operate and this is indicated with CallsFor. + * Motivations similar to the ones for {@link Requires} relation conducted to the definition for this relation. + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#CallsFor * * @author Luca Frosini (ISTI - CNR) @@ -19,7 +23,9 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Service; @JsonDeserialize(as=CallsForImpl.class) @TypeMetadata( name = CallsFor.NAME, - description = "", + description = "A {@link Service} instance can require another {@link Service} instance to properly " + + "operate and this is indicated with CallsFor.\n" + + "Motivations similar to the ones for {@link Requires} relation conducted to the definition for this relation.", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Demands.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Demands.java index 0a5e456..c10f7aa 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Demands.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Demands.java @@ -13,6 +13,8 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Software; import org.gcube.resourcemanagement.model.reference.entities.resources.VirtualService; /** + * + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Demands * * @author Luca Frosini (ISTI - CNR) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/DependsOn.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/DependsOn.java index 7777f78..7e408fe 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/DependsOn.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/DependsOn.java @@ -12,14 +12,18 @@ import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.DependsOnIm import org.gcube.resourcemanagement.model.reference.entities.resources.Software; /** + * DependsOn indicates that a {@link Software} requires another one to work. + * This relation must not be confused with {@link Requires}. + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#DependsOn * * @author Luca Frosini (ISTI - CNR) */ @JsonDeserialize(as = DependsOnImpl.class) @TypeMetadata( - name = DependsOn.NAME, - description = "", + name = DependsOn.NAME, + description = "DependsOn indicates that a {@link Software} requires another one to work.\n" + + "This relation must not be confused with {@link Requires}.", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Discovers.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Discovers.java index c1ac6b2..1e2df0c 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Discovers.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Discovers.java @@ -11,14 +11,16 @@ import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.DiscoversIm import org.gcube.resourcemanagement.model.reference.entities.resources.EService; /** - * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Discovers + * + * + * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Discovers * * @author Luca Frosini (ISTI - CNR) */ @JsonDeserialize(as=DiscoversImpl.class) @TypeMetadata( - name = Discovers.NAME, - description = "", + name = Discovers.NAME, + description = "", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Enables.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Enables.java index b37cb37..51d29c5 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Enables.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Enables.java @@ -9,18 +9,32 @@ import org.gcube.informationsystem.types.reference.Change; import org.gcube.informationsystem.types.reference.TypeMetadata; import org.gcube.informationsystem.utils.TypeVersion; import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.EnablesImpl; +import org.gcube.resourcemanagement.model.reference.entities.resources.EService; +import org.gcube.resourcemanagement.model.reference.entities.resources.HostingNode; +import org.gcube.resourcemanagement.model.reference.entities.resources.Plugin; +import org.gcube.resourcemanagement.model.reference.entities.resources.RunningPlugin; import org.gcube.resourcemanagement.model.reference.entities.resources.Service; import org.gcube.resourcemanagement.model.reference.entities.resources.Software; /** + * Any {@link Service} representing running code of a specific software has the relation + * Enables targeted to the corresponding {@link Software}. + * Enables is used for example by {@link EService} to indicates the running software; + * from {@link HostingNode} to indicate the running software container; + * within {@link RunningPlugin} and the software represented as {@link Plugin}. + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Enables * * @author Luca Frosini (ISTI - CNR) */ @JsonDeserialize(as=EnablesImpl.class) @TypeMetadata( - name = Enables.NAME, - description = "", + name = Enables.NAME, + description = "Any {@link Service} representing running code of a specific software has the " + + "relation Enables targeted to the corresponding {@link Software}.\n" + + "Enables is used for example by {@link EService} to indicates the running software; " + + "from {@link HostingNode} to indicate the running software container; " + + "within {@link RunningPlugin} and the software represented as {@link Plugin}.", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Hosts.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Hosts.java index c5eb02f..920da83 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Hosts.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Hosts.java @@ -12,16 +12,17 @@ import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.HostsImpl; import org.gcube.resourcemanagement.model.reference.entities.resources.Service; import org.gcube.resourcemanagement.model.reference.entities.resources.Site; - /** + * + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Hosts * * @author Luca Frosini (ISTI - CNR) */ @JsonDeserialize(as=HostsImpl.class) @TypeMetadata( - name = Hosts.NAME, - description = "", + name = Hosts.NAME, + description = "", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Involves.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Involves.java index a1fff4e..afaa742 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Involves.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Involves.java @@ -13,14 +13,16 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Actor; import org.gcube.resourcemanagement.model.reference.entities.resources.Dataset; /** + * + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Involves * * @author Luca Frosini (ISTI - CNR) */ @JsonDeserialize(as=InvolvesImpl.class) @TypeMetadata( - name = Involves.NAME, - description = "", + name = Involves.NAME, + description = "", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsCustomizedBy.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsCustomizedBy.java index 7b3391b..2d3575e 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsCustomizedBy.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsCustomizedBy.java @@ -13,14 +13,16 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Configura import org.gcube.resourcemanagement.model.reference.entities.resources.Service; /** + * IsCustomizedBy evidences that any {@link Service} can be customised by a {@link ConfigurationTemplate}. + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#IsCustomizedBy * * @author Luca Frosini (ISTI - CNR) */ @JsonDeserialize(as=IsCustomizedByImpl.class) @TypeMetadata( - name = IsCustomizedBy.NAME, - description = "", + name = IsCustomizedBy.NAME, + description = "IsCustomizedBy evidences that any {@link Service} can be customised by a {@link ConfigurationTemplate}.", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsOwnedBy.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsOwnedBy.java index 364dda2..15441c2 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsOwnedBy.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsOwnedBy.java @@ -13,14 +13,16 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Actor; import org.gcube.resourcemanagement.model.reference.entities.resources.Site; /** + * + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#IsOwnedBy * * @author Luca Frosini (ISTI - CNR) */ @JsonDeserialize(as=IsOwnedByImpl.class) @TypeMetadata( - name = IsOwnedBy.NAME, - description = "", + name = IsOwnedBy.NAME, + description = "", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsPluginOf.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsPluginOf.java index 8b7da33..36b7f85 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsPluginOf.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/IsPluginOf.java @@ -12,14 +12,16 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Plugin; import org.gcube.resourcemanagement.model.reference.entities.resources.Software; /** + * + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#IsPluginOf * * @author Luca Frosini (ISTI - CNR) */ @JsonDeserialize(as = IsPluginOfImpl.class) @TypeMetadata( - name = IsPluginOf.NAME, - description = "", + name = IsPluginOf.NAME, + description = "", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Manages.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Manages.java index b234b7d..bba4520 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Manages.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Manages.java @@ -13,7 +13,7 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Dataset; import org.gcube.resourcemanagement.model.reference.entities.resources.Service; /** - * Manages indicates that of the source {@link Service} manages the target + * Manages indicates that the source {@link Service} manages the target * {@link Dataset}, e.g. read, manipulate, etc. * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Manages diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Requires.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Requires.java index ba36a46..035cdf9 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Requires.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Requires.java @@ -13,14 +13,49 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Service; import org.gcube.resourcemanagement.model.reference.entities.resources.Software; /** + * Requires is used to indicate that the source {@link Software} when activated requires + * to interact with a specific {@link Service} instance, i.e., the target of the relation. + * This relation usually reflects an administrative constraint than a technological limitation. + * When there are no constraint on the instance the relation is instead {@link DependsOn} + * which is between two {@link Software}. + * + * Not necessarily all the {@link Software} running in the infrastructure are represented as + * resources. Only the {@link Software} required for infrastructure administration or the + * ones to be managed with specific policies are represented. + * Indeed, Requires relation is normally used as policy constraint. + * + * Let imagine an open source software which uses a MySQL database as backend. + * In many cases, what characterises the software instance is the data present in the backend. + * The infrastructure manager could stipulate an agreement with a provider having a particular + * set of data which is not for public domain. + * The software once deployed, giving the business agreement, is entitled to use the instance + * of the provider and not a generic MySQL database instance. + * + * The infrastructure manager imposes the use of such a particular instance because of the data it contains. + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Requires * * @author Luca Frosini (ISTI - CNR) */ @JsonDeserialize(as=RequiresImpl.class) @TypeMetadata( - name = Requires.NAME, - description = "", + name = Requires.NAME, + description = "Requires is used to indicate that the source {@link Software} when activated requires " + + "to interact with a specific {@link Service} instance, i.e., the target of the relation.\n" + + "This relation usually reflects an administrative constraint than a technological limitation.\n" + + "When there are no constraint on the instance the relation is instead {@link DependsOn} " + + "which is between two {@link Software}." + + "Not necessarily all the {@link Software} running in the infrastructure are represented as resources. " + + "Only the {@link Software} required for infrastructure administration or the ones to be managed " + + "with specific policies are represented.\n" + + "Indeed, Requires relation is normally used as policy constraint.\n" + + "Let imagine an open source software which uses a MySQL database as backend.\n" + + "In many cases, what characterises the software instance is the data present in the backend.\n" + + "The infrastructure manager could stipulate an agreement with a provider having a particular " + + "set of data which is not for public domain.\n" + + "The software once deployed, giving the business agreement, is entitled to use the instance " + + "of the provider and not a generic MySQL database instance.\n" + + "The infrastructure manager imposes the use of such a particular instance because of the data it contains.", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) diff --git a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Uses.java b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Uses.java index 513d525..ef26c70 100644 --- a/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Uses.java +++ b/src/main/java/org/gcube/resourcemanagement/model/reference/relations/isrelatedto/Uses.java @@ -11,14 +11,16 @@ import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.UsesImpl; import org.gcube.resourcemanagement.model.reference.entities.resources.EService; /** + * + * * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Uses * * @author Luca Frosini (ISTI - CNR) */ @JsonDeserialize(as=UsesImpl.class) @TypeMetadata( - name = Uses.NAME, - description = "", + name = Uses.NAME, + description = "", version = TypeVersion.MINIMAL_VERSION_STRING ) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)