Added/fixed documentation

This commit is contained in:
Luca Frosini 2020-12-22 15:09:55 +01:00
parent 5ac9feb9e2
commit 64230d5fc2
14 changed files with 128 additions and 25 deletions

View File

@ -9,9 +9,27 @@ import org.gcube.informationsystem.types.reference.Change;
import org.gcube.informationsystem.types.reference.TypeMetadata; import org.gcube.informationsystem.types.reference.TypeMetadata;
import org.gcube.informationsystem.utils.TypeVersion; import org.gcube.informationsystem.utils.TypeVersion;
import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.ActivatesImpl; 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.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 * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Activates
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
@ -19,7 +37,18 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Service;
@JsonDeserialize(as=ActivatesImpl.class) @JsonDeserialize(as=ActivatesImpl.class)
@TypeMetadata( @TypeMetadata(
name = Activates.NAME, 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 version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -12,6 +12,10 @@ import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.CallsForImp
import org.gcube.resourcemanagement.model.reference.entities.resources.Service; 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 * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#CallsFor
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
@ -19,7 +23,9 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Service;
@JsonDeserialize(as=CallsForImpl.class) @JsonDeserialize(as=CallsForImpl.class)
@TypeMetadata( @TypeMetadata(
name = CallsFor.NAME, 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 version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -13,6 +13,8 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Software;
import org.gcube.resourcemanagement.model.reference.entities.resources.VirtualService; import org.gcube.resourcemanagement.model.reference.entities.resources.VirtualService;
/** /**
*
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Demands * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Demands
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)

View File

@ -12,14 +12,18 @@ import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.DependsOnIm
import org.gcube.resourcemanagement.model.reference.entities.resources.Software; 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 * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#DependsOn
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@JsonDeserialize(as = DependsOnImpl.class) @JsonDeserialize(as = DependsOnImpl.class)
@TypeMetadata( @TypeMetadata(
name = DependsOn.NAME, name = DependsOn.NAME,
description = "", 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 version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -11,14 +11,16 @@ import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.DiscoversIm
import org.gcube.resourcemanagement.model.reference.entities.resources.EService; 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) * @author Luca Frosini (ISTI - CNR)
*/ */
@JsonDeserialize(as=DiscoversImpl.class) @JsonDeserialize(as=DiscoversImpl.class)
@TypeMetadata( @TypeMetadata(
name = Discovers.NAME, name = Discovers.NAME,
description = "", description = "",
version = TypeVersion.MINIMAL_VERSION_STRING version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -9,18 +9,32 @@ import org.gcube.informationsystem.types.reference.Change;
import org.gcube.informationsystem.types.reference.TypeMetadata; import org.gcube.informationsystem.types.reference.TypeMetadata;
import org.gcube.informationsystem.utils.TypeVersion; import org.gcube.informationsystem.utils.TypeVersion;
import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.EnablesImpl; 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.Service;
import org.gcube.resourcemanagement.model.reference.entities.resources.Software; 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 * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Enables
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@JsonDeserialize(as=EnablesImpl.class) @JsonDeserialize(as=EnablesImpl.class)
@TypeMetadata( @TypeMetadata(
name = Enables.NAME, name = Enables.NAME,
description = "", 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 version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -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.Service;
import org.gcube.resourcemanagement.model.reference.entities.resources.Site; import org.gcube.resourcemanagement.model.reference.entities.resources.Site;
/** /**
*
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Hosts * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Hosts
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@JsonDeserialize(as=HostsImpl.class) @JsonDeserialize(as=HostsImpl.class)
@TypeMetadata( @TypeMetadata(
name = Hosts.NAME, name = Hosts.NAME,
description = "", description = "",
version = TypeVersion.MINIMAL_VERSION_STRING version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -13,14 +13,16 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Actor;
import org.gcube.resourcemanagement.model.reference.entities.resources.Dataset; import org.gcube.resourcemanagement.model.reference.entities.resources.Dataset;
/** /**
*
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Involves * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Involves
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@JsonDeserialize(as=InvolvesImpl.class) @JsonDeserialize(as=InvolvesImpl.class)
@TypeMetadata( @TypeMetadata(
name = Involves.NAME, name = Involves.NAME,
description = "", description = "",
version = TypeVersion.MINIMAL_VERSION_STRING version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -13,14 +13,16 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Configura
import org.gcube.resourcemanagement.model.reference.entities.resources.Service; 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 * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#IsCustomizedBy
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@JsonDeserialize(as=IsCustomizedByImpl.class) @JsonDeserialize(as=IsCustomizedByImpl.class)
@TypeMetadata( @TypeMetadata(
name = IsCustomizedBy.NAME, name = IsCustomizedBy.NAME,
description = "", description = "IsCustomizedBy evidences that any {@link Service} can be customised by a {@link ConfigurationTemplate}.",
version = TypeVersion.MINIMAL_VERSION_STRING version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -13,14 +13,16 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Actor;
import org.gcube.resourcemanagement.model.reference.entities.resources.Site; import org.gcube.resourcemanagement.model.reference.entities.resources.Site;
/** /**
*
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#IsOwnedBy * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#IsOwnedBy
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@JsonDeserialize(as=IsOwnedByImpl.class) @JsonDeserialize(as=IsOwnedByImpl.class)
@TypeMetadata( @TypeMetadata(
name = IsOwnedBy.NAME, name = IsOwnedBy.NAME,
description = "", description = "",
version = TypeVersion.MINIMAL_VERSION_STRING version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -12,14 +12,16 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Plugin;
import org.gcube.resourcemanagement.model.reference.entities.resources.Software; import org.gcube.resourcemanagement.model.reference.entities.resources.Software;
/** /**
*
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#IsPluginOf * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#IsPluginOf
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@JsonDeserialize(as = IsPluginOfImpl.class) @JsonDeserialize(as = IsPluginOfImpl.class)
@TypeMetadata( @TypeMetadata(
name = IsPluginOf.NAME, name = IsPluginOf.NAME,
description = "", description = "",
version = TypeVersion.MINIMAL_VERSION_STRING version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -13,7 +13,7 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Dataset;
import org.gcube.resourcemanagement.model.reference.entities.resources.Service; 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. * {@link Dataset}, e.g. read, manipulate, etc.
* *
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Manages * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Manages

View File

@ -13,14 +13,49 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Service;
import org.gcube.resourcemanagement.model.reference.entities.resources.Software; 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 * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Requires
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@JsonDeserialize(as=RequiresImpl.class) @JsonDeserialize(as=RequiresImpl.class)
@TypeMetadata( @TypeMetadata(
name = Requires.NAME, name = Requires.NAME,
description = "", 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 version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -11,14 +11,16 @@ import org.gcube.resourcemanagement.model.impl.relations.isrelatedto.UsesImpl;
import org.gcube.resourcemanagement.model.reference.entities.resources.EService; import org.gcube.resourcemanagement.model.reference.entities.resources.EService;
/** /**
*
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Uses * https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Uses
* *
* @author Luca Frosini (ISTI - CNR) * @author Luca Frosini (ISTI - CNR)
*/ */
@JsonDeserialize(as=UsesImpl.class) @JsonDeserialize(as=UsesImpl.class)
@TypeMetadata( @TypeMetadata(
name = Uses.NAME, name = Uses.NAME,
description = "", description = "",
version = TypeVersion.MINIMAL_VERSION_STRING version = TypeVersion.MINIMAL_VERSION_STRING
) )
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION) @Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)