Documenting the model

This commit is contained in:
Luca Frosini 2020-12-21 15:43:36 +01:00
parent 94c85b4a5f
commit aac52ec0e0
17 changed files with 197 additions and 26 deletions

View File

@ -28,7 +28,7 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.IsOwne
* {@link BelongsTo} relation
*
* Actor has similar meaning of E39_Actor defined in CDOC-CRM.
* Similarly LegalBody and Person have similar meaning of
* Similarly LegalBody and Person have similar meaning of
* E40_Legal_Body and E21_Person respectively.
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Actor

View File

@ -16,7 +16,6 @@ import org.gcube.resourcemanagement.model.reference.entities.facets.ContactFacet
import org.gcube.resourcemanagement.model.reference.relations.consistsof.HasMaintainer;
import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.IsPartOf;
/**
* ConcreteDataset is any incarnation/manifestation of a dataset or part of it.
* The relation {@link IsPartOf} is used when a ConcreteDataset is part of a {@link Dataset}.

View File

@ -14,8 +14,14 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.IsDeri
/**
* @author Luca Frosini (ISTI - CNR)
* Configuration is a specialisation of {@link ConfigurationTemplate}
* and is an instance of a configuration template characterising
* the behaviour and shape of the resource it is attached to.
* The Configuration can be related to the template it derives using {@link IsDerivationOf}.
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Configuration
*
* @author Luca Frosini (ISTI - CNR)
*/
@JsonDeserialize(as=ConfigurationImpl.class)
@ResourceSchema(
@ -25,7 +31,10 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.IsDeri
)
@TypeMetadata(
name = Configuration.NAME,
description = "An instance of a configuration template characterising the behaviour and shape of the resource it is attached to.",
description = "Configuration is a specialisation of {@link ConfigurationTemplate} "
+ "and is an instance of a configuration template characterising "
+ "the behaviour and shape of the resource it is attached to.\n"
+ "The Configuration can be related to the template it derives using {@link IsDerivationOf}.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -19,8 +19,13 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.IsCust
import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.IsDerivationOf;
/**
* @author Luca Frosini (ISTI - CNR)
* Configuration Template represents a template for a configuration.
* It describes how a configuration has to be realised,
* e.g. used to define the catalogue configuration parameters template.
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Configuration_Template
*
* @author Luca Frosini (ISTI - CNR)
*/
@JsonDeserialize(as=ConfigurationTemplateImpl.class)
@ResourceSchema(
@ -36,7 +41,7 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.IsDeri
)
@TypeMetadata(
name = ConfigurationTemplate.NAME,
description = "It represents a template for a configuration. It describe how a configuration has to be realized. E.g. Used to define the accounting configuration parameters template.",
description = "Configuration Template represents a template for a configuration. It describes how a configuration has to be realised, e.g. used to define the catalogue configuration parameters template.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -39,6 +39,7 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.Manage
/**
* A Dataset is a set of digital objects representing data and treated collectively as a unit.
* It is the key resource of a HDI, even more, it is the reason the HDI exists.
*
* A Dataset can be correlated to another Dataset by using {@link IsCorrelatedTo} relation.
*
* Dataset has similar meaning of PE18_Dataset defined in PARTHENOS Entities Model (PE Model).

View File

@ -21,8 +21,14 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.Discov
import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.Uses;
/**
* EService is any running service that is registered in the infrastructure and
* made available by an access point.
*
* EService has similar meaning of PE8_EService defined in PARTHENOS Entities Model (PE Model).
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#EService
*
* @author Luca Frosini (ISTI - CNR)
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#E-Service
*/
@JsonDeserialize(as = EServiceImpl.class)
@ResourceSchema(
@ -41,7 +47,7 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.Uses;
)
@TypeMetadata(
name = EService.NAME,
description = "Any Electronic Service (aka Running Service) that is registered in the infrastructure and made available by an Access Point.",
description = "EService is any running service that is registered in the infrastructure and made available by an access point.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -16,6 +16,8 @@ import org.gcube.resourcemanagement.model.impl.entities.resources.GCubeResourceI
import org.gcube.resourcemanagement.model.reference.relations.consistsof.IsIdentifiedBy;
/**
* Marker type for any gCube Resource extended in the gCube model
*
* @author Luca Frosini (ISTI - CNR)
*/
@Abstract
@ -27,7 +29,7 @@ import org.gcube.resourcemanagement.model.reference.relations.consistsof.IsIdent
)
@TypeMetadata(
name = GCubeResource.NAME,
description = "Base Class for any gCube Resource",
description = "Marker type for any gCube Resource extended in the gCube model.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -22,8 +22,30 @@ import org.gcube.resourcemanagement.model.reference.relations.consistsof.HasVola
import org.gcube.resourcemanagement.model.reference.relations.consistsof.IsIdentifiedBy;
/**
* @author Luca Frosini (ISTI - CNR)
* The HostingNode represent a container capable of managing the lifecycle of an
* electronic service, i.e., being capable to host and operate an {@link EService}.
* Examples are docker, tomcat.
*
* A container is a service which is conceived to enable any services respecting
* the container rules to be operative. The container does not typically provide any
* functionality rather than allowing the hosted service to operate.
*
* The HostingNode characterisation in terms of facets reflects the one presented for {@link VirtualMachine}.
*
* In particular, facets representing memory, CPU and networking interface are used to describe
* the HostingNode when the VirtualMachine enabling the HostingNode is not represented.
*
* Federated systems can provide virtual machines as resource or containers as resources.
* In some cases, the description of a container includes (virtual) hardware information.
*
* It is important to highlight that HostingNode is not a subclass of VirtualMachine.
*
* HostingNode could be though as a specialisation of the entity
* PE6_Software_Hosting_Service defined in PARTHENOS Entities Model (PE Model).
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Hosting_Node
*
* @author Luca Frosini (ISTI - CNR)
*/
@JsonDeserialize(as=HostingNodeImpl.class)
@ResourceSchema(
@ -40,7 +62,18 @@ import org.gcube.resourcemanagement.model.reference.relations.consistsof.IsIdent
)
@TypeMetadata(
name = HostingNode.NAME,
description = "The HostingNode represent a container capable of managing the lifecycle of an electronic service, i.e., being capable to host and operate an EService.",
description = "The HostingNode represent a container capable of managing the lifecycle of "
+ "an electronic service, i.e., being capable to host and operate an {@link EService}. "
+ "Examples are docker, tomcat.\n"
+ "A container is a service which is conceived to enable any services respecting "
+ "the container rules to be operative. The container does not typically provide any "
+ "functionality rather than allowing the hosted service to operate.\n"
+ "The HostingNode characterisation in terms of facets reflects the one presented for {@link VirtualMachine}.\n"
+ "In particular, facets representing memory, CPU and networking interface are used to describe "
+ "the HostingNode when the {@link VirtualMachine} enabling the HostingNode is not represented.\n"
+ "Federated systems can provide virtual machines as resource or containers as resources.\n"
+ "In some cases, the description of a container includes (virtual) hardware information.\n"
+ "It is important to highlight that HostingNode is not a subclass of {@link VirtualMachine}.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -14,8 +14,16 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.IsPlug
/**
* @author Luca Frosini (ISTI - CNR)
* Plugin is a piece of Software extending the capabilities of another
* {@link Software} (main) and requiring the main {@link Software} to be executed.
*
* The relation between the main {@link Software} and the Plugin
* is expressed by {@link IsPluginOf} relation.
* {@link IsPluginOf} is an extension of {@link DependsOn}.
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Plugin
*
* @author Luca Frosini (ISTI - CNR)
*/
@JsonDeserialize(as=PluginImpl.class)
@ResourceSchema(

View File

@ -10,13 +10,22 @@ import org.gcube.informationsystem.utils.TypeVersion;
import org.gcube.resourcemanagement.model.impl.entities.resources.RunningPluginImpl;
/**
* @author Luca Frosini (ISTI - CNR)
* RunningPlugin allows differentiating which is the primary service and which is
* an additional capability of a such a service.
* Keeping the two concepts separated enables to share a service across
* VREs with a subset of its capabilities.
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Running_Plugin
*
* @author Luca Frosini (ISTI - CNR)
*/
@JsonDeserialize(as=RunningPluginImpl.class)
@TypeMetadata(
name = RunningPlugin.NAME,
description = "Any instance of a Plugin deployed and running by an EService.",
description = "RunningPlugin allows differentiating which is the primary service and "
+ "which is an additional capability of a such a service.\n"
+ "Keeping the two concepts separated enables to share a service across "
+ "VREs with a subset of its capabilities.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -20,8 +20,14 @@ import org.gcube.resourcemanagement.model.reference.relations.consistsof.IsIdent
import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.IsCompliantWith;
/**
* @author Luca Frosini (ISTI - CNR)
* Schema is any reference schema used to specify compliant values.
* Examples include controlled vocabularies, ontologies, and others.
* This resource is mainly used by {@link Dataset} to evidence that
* is compliant with a Schema by using {@link IsCompliantWith} relation.
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Schema
*
* @author Luca Frosini (ISTI - CNR)
*/
@JsonDeserialize(as=SchemaImpl.class)
@ResourceSchema(
@ -37,7 +43,10 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.IsComp
)
@TypeMetadata(
name = Schema.NAME,
description = "Any reference schema to be used to specify values compliant with it. Examples include controlled vocabularies, ontologies, etc.",
description = "Schema is any reference schema used to specify compliant values.\n"
+ "Examples include controlled vocabularies, ontologies, and others.\n"
+ "This resource is mainly used by {@link Dataset} to evidence that "
+ "is compliant with a Schema by using {@link IsCompliantWith} relation.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -23,8 +23,27 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.Manage
import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.Requires;
/**
* @author Luca Frosini (ISTI - CNR)
* Service (Abstract) represents any typology of service worth registering in the infrastructure.
* Service has relations with quite all other resources.
* If on one side, an Hybrid Data Infrastructure (HDI) is created to manage datasets,
* on the other side the HDI born to manage such datasets digitally.
* We could affirm that datasets and services are the two pillar resources
* around which revolves the entire infrastructure.
* It is important to highlight that Service has a general meaning and must
* not be intended as a network-callable service which is represented instead
* by one of its specialisations called {@link EService}.
*
*
* Giving that Service is abstract no {@link IsIdentifiedBy} association with a facet is provided
* which in turns is responsibility of the specialisation.
*
* Service could be intended as a specialisation of
* the entity PE1_Service defined in PARTHENOS Entities Model (PE Model)
* and the entity D1_Digital_Object defined in CRMdig.
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Service
*
* @author Luca Frosini (ISTI - CNR)
*/
@Abstract
@JsonDeserialize(as=ServiceImpl.class)
@ -45,7 +64,17 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.Requir
)
@TypeMetadata(
name = Service.NAME,
description = "An abstract entity to represent any typology of Service worth registering in the infrastructure.",
description = "Service (Abstract) represents any typology of service worth registering in the infrastructure.\n"
+ "Service has relations with quite all other resources.\n"
+ "If on one side, an Hybrid Data Infrastructure (HDI) is created to manage datasets, "
+ "on the other side the HDI born to manage such datasets digitally.\n"
+ "We could affirm that datasets and services are the two pillar resources "
+ "around which revolves the entire infrastructure.\n"
+ "It is important to highlight that Service has a general meaning and must "
+ "not be intended as a network-callable service which is represented instead "
+ "by one of its specialisation called {@link EService}."
+ "Giving that Service is abstract no {@link IsIdentifiedBy} association with "
+ "a facet is provided which in turns is responsibility of the specialisation.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -21,8 +21,15 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.IsPlug
import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.Requires;
/**
* @author Luca Frosini (ISTI - CNR)
* Software is an entity worth being represented for management purposes.
* The relation {@link DependsOn} indicates dependencies between two Software
* captured for management purposes.
*
* Software has similar meaning of D14_Software defined in CRMdig.
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Software
*
* @author Luca Frosini (ISTI - CNR)
*/
@JsonDeserialize(as=SoftwareImpl.class)
@ResourceSchema(
@ -41,7 +48,8 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.Requir
)
@TypeMetadata(
name = Software.NAME,
description = "Any Software entity worth being represented for management purposes.",
description = "Software is an entity worth being represented for management purposes.\n"
+ "The relation {@link DependsOn} indicates dependencies between two Software captured for management purposes.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -21,8 +21,18 @@ import org.gcube.resourcemanagement.model.reference.relations.consistsof.HasVola
import org.gcube.resourcemanagement.model.reference.relations.consistsof.IsIdentifiedBy;
/**
* @author Luca Frosini (ISTI - CNR)
* VirtualMachine (VM) is the typical resource represented in a cloud infrastructure.
* It is an emulation of a physical computer which appears to the running
* operative system as real hardware.
* A VM provides operative system functionality and potentially allows
* to install any software designed for the running operative system.
*
* VirtualMachine could be though as a specialisation of the entity
* PE6_Software_Hosting_Service defined in PARTHENOS Entities Model (PE Model).
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Virtual_Machine
*
* @author Luca Frosini (ISTI - CNR)
*/
@JsonDeserialize(as=VirtualMachineImpl.class)
@ResourceSchema(
@ -38,7 +48,10 @@ import org.gcube.resourcemanagement.model.reference.relations.consistsof.IsIdent
)
@TypeMetadata(
name = VirtualMachine.NAME,
description = "A Virtual Machine is an emulation of a physical computer which appears to the running operative system as real hardware.",
description = "VirtualMachine (VM) is the typical resource represented in a cloud infrastructure.\n"
+ "It is an emulation of a physical computer which appears to the running operative system as real hardware.\n"
+ "A VM provides operative system functionality and potentially allows "
+ "to install any software designed for the running operative system.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -4,6 +4,7 @@
package org.gcube.resourcemanagement.model.reference.entities.resources;
import org.gcube.com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import org.gcube.informationsystem.model.reference.properties.PropagationConstraint;
import org.gcube.informationsystem.types.annotations.ResourceSchema;
import org.gcube.informationsystem.types.annotations.ResourceSchemaEntry;
import org.gcube.informationsystem.types.annotations.ResourceSchemaRelatedEntry;
@ -16,8 +17,30 @@ import org.gcube.resourcemanagement.model.reference.relations.consistsof.IsIdent
import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.Demands;
/**
* @author Luca Frosini (ISTI - CNR)
* VirtualService is an abstract service (non-physically existing service) worth being
* represented as an existing Service for management purposes.
* Examples of usage include cases where classes or set of services have to
* be managed like an existing unit.
* This resource is essential from infrastructure management point of view because
* it allows easily share a pool of services across VREs as a single unit.
*
* VirtualService mainly consist of a service definition which uses relations to
* {@link ConfigurationTemplate}, {@link EService},
* {@link Software} (using {@link Demands} relation) to properly support the sharing across VREs.
*
* The correct sharing is feasible thanks to the {@link PropagationConstraint} of the model.
*
* The IS provides only the support for resource sharing as a bundle.
* Instead, the actions required to deploy a {@link Software} are a responsibility of the service
* invoking the sharing operation.
*
* This resource emerged thank to the experience maturated with
* gCube IS V.1 (gCore Based IS) where this resource was represented as a Generic Resource
* containing the list of the resources id forming the bundle which often lead to inconsistency.
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#Virtual_Service
*
* @author Luca Frosini (ISTI - CNR)
*/
@JsonDeserialize(as=VirtualServiceImpl.class)
@ResourceSchema(
@ -30,7 +53,20 @@ import org.gcube.resourcemanagement.model.reference.relations.isrelatedto.Demand
)
@TypeMetadata(
name = VirtualService.NAME,
description = "An abstract service (non physically existing service) worth being represented as an existing Service for management purposes. Examples of usage include cases where classes or set of services are to be managed like an existing unit.",
description = "VirtualService is an abstract service (non-physically existing service) worth being "
+ "represented as an existing Service for management purposes.\n"
+ "Examples of usage include cases where classes or set of services have to be managed like an existing unit.\n"
+ "This resource is essential from infrastructure management point of view because "
+ "it allows easily share a pool of services across VREs as a single unit.\n"
+ "VirtualService mainly consist of a service definition which uses relations to {@link ConfigurationTemplate}, "
+ "{@link EService}, {@link Software} (using {@link Demands} relation) to properly support the sharing across VREs.\n"
+ "The correct sharing is feasible thanks to the {@link PropagationConstraint} of the model.\n"
+ "The IS provides only the support for resource sharing as a bundle.\n"
+ "Instead, the actions required to deploy a {@link Software} are a responsibility "
+ "of the service invoking the sharing operation.\n"
+ "This resource emerged thank to the experience maturated with gCube IS V.1 (gCore Based IS) "
+ "where this resource was represented as a Generic Resource containing "
+ "the list of the resources id forming the bundle which often lead to inconsistency.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)

View File

@ -8,7 +8,7 @@ import org.gcube.informationsystem.utils.TypeVersion;
import org.gcube.resourcemanagement.model.impl.properties.GCubePropertyImpl;
/**
* Marker type for {@link Property} properties extended in the gCube model.
* Marker type for {@link Property} properties extended in the gCube Model.
*
* @author Manuele Simi (ISTI - CNR)
* @author Luca Frosini (ISTI - CNR)

View File

@ -13,6 +13,9 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Configura
import org.gcube.resourcemanagement.model.reference.entities.resources.Software;
/**
* The relation IsConfiguredBy indicates that the source {@link Software}
* requires a configuration when it is instantiated.
*
* https://wiki.gcube-system.org/gcube/Facet_Based_Resource_Model#IsConfiguredBy
*
* @author Luca Frosini (ISTI - CNR)
@ -20,7 +23,8 @@ import org.gcube.resourcemanagement.model.reference.entities.resources.Software;
@JsonDeserialize(as=IsConfiguredByImpl.class)
@TypeMetadata(
name = IsConfiguredBy.NAME,
description = "",
description = "The relation IsConfiguredBy indicates that the source "
+ "{@link Software} requires a configuration when it is instantiated.",
version = TypeVersion.MINIMAL_VERSION_STRING
)
@Change(version = TypeVersion.MINIMAL_VERSION_STRING, description = TypeVersion.MINIMAL_VERSION_DESCRIPTION)