From 22e2a36a4c434ec112b5ebca460f601e28a042a6 Mon Sep 17 00:00:00 2001 From: Luca Frosini Date: Tue, 24 Jan 2023 16:54:00 +0100 Subject: [PATCH] Improved doc generation --- is-model.rst | 277 ++++++++++++++++++ .../generator/ClassesDiscoveryGenerator.java | 5 +- .../documentation/generator/Generator.java | 142 +++++++++ .../generator/TreeGenerator.java | 89 ++++-- .../generator/TypeListGenerator.java | 227 -------------- .../utils/documentation/knowledge/Node.java | 12 + .../knowledge/NodeElaborator.java | 10 + .../utils/documentation/knowledge/Tree.java | 7 + .../model/DocumentationGenerator.java | 58 ++-- .../entities/FacetDocumentationGenerator.java | 2 +- .../ResourceDocumentationGenerator.java | 13 +- .../ConsistsOfDocumentationGenerator.java | 2 +- .../IsRelatedToDocumentationGenerator.java | 2 +- .../utils/documentation/rst/Section.java | 20 +- .../utils/documentation/table/TableTest.java | 1 - 15 files changed, 584 insertions(+), 283 deletions(-) create mode 100644 is-model.rst create mode 100644 src/main/java/org/gcube/informationsystem/utils/documentation/generator/Generator.java delete mode 100644 src/main/java/org/gcube/informationsystem/utils/documentation/generator/TypeListGenerator.java create mode 100644 src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/NodeElaborator.java diff --git a/is-model.rst b/is-model.rst new file mode 100644 index 0000000..f148854 --- /dev/null +++ b/is-model.rst @@ -0,0 +1,277 @@ + +######## +Property +######## + +This is the base type for any Property + + +.. table:: **Property** + + +------------------------------------------------------+------+------------+-------------+ + | Name | Type | Attributes | Description | + +======================================================+======+============+=============+ + | This type does not define any additional attributes. | + +------------------------------------------------------+------+------------+-------------+ + + +The **Property** current version is 1.0.0. + +Changelog: + +* **1.0.0**: First Version. + + +###### +Entity +###### + +This is the base type for any Entity + + +.. table:: **Entity** + + +------------+----------+--------------------------------------------------------+--------------------------------------------------------------------------------------------+ + | Properties | + +============+==========+========================================================+============================================================================================+ + | **Name** | **Type** | **Attributes** | **Description** | + +------------+----------+--------------------------------------------------------+--------------------------------------------------------------------------------------------+ + | header | Header | ``Mandatory:true`` ``ReadOnly:false`` ``NotNull:true`` | Metadata associated with the instance that is automatically created/updated by the system. | + +------------+----------+--------------------------------------------------------+--------------------------------------------------------------------------------------------+ + + +The **Entity** current version is 1.0.0. + +Changelog: + +* **1.0.0**: First Version. + + +******** +Resource +******** + +This is the base type for any Resource + + +.. table:: **Resource** ``extends`` **Entity** + + +------------------------+-------------+--------------+----------+----------------------------------------------------------------------------------------------------+ + | Source | Relation | Multiplicity | Target | Description | + +========================+=============+==============+==========+====================================================================================================+ + | **Facets** | + +------------------------+-------------+--------------+----------+----------------------------------------------------------------------------------------------------+ + | Resource | ConsistsOf | 1..n | Facet | Any Resource consists of one or more Facets which describes the different aspects of the resource. | + +------------------------+-------------+--------------+----------+----------------------------------------------------------------------------------------------------+ + | **Resource Relations** | + +------------------------+-------------+--------------+----------+----------------------------------------------------------------------------------------------------+ + | Resource | IsRelatedTo | 0..n | Resource | Any Resource can be related to any other resource. | + +------------------------+-------------+--------------+----------+----------------------------------------------------------------------------------------------------+ + + +The **Resource** current version is 1.0.0. + +Changelog: + +* **1.0.0**: First Version. + + +***** +Facet +***** + +This is the base type for any Facet + + +.. table:: **Facet** ``extends`` **Entity** + + +------------------------------------------------------+----------------+------------------+-----------------+----------------------------------------------------------------------------------------------------+ + | Properties | + +======================================================+================+==================+=================+====================================================================================================+ + | **Name** | **Type** | **Attributes** | **Description** | + +------------------------------------------------------+----------------+------------------+-----------------+----------------------------------------------------------------------------------------------------+ + | This type does not define any additional attributes. | + +------------------------------------------------------+----------------+------------------+-----------------+----------------------------------------------------------------------------------------------------+ + | **Known Usage** | + +------------------------------------------------------+----------------+------------------+-----------------+----------------------------------------------------------------------------------------------------+ + | **Source** | **Relation** | **Multiplicity** | **Target** | **Description** | + +------------------------------------------------------+----------------+------------------+-----------------+----------------------------------------------------------------------------------------------------+ + | GCubeResource | IsIdentifiedBy | 1..1 | Facet | Any Resource has at least one Facet which in some way allow to identify the Resource per se. | + +------------------------------------------------------+----------------+------------------+-----------------+----------------------------------------------------------------------------------------------------+ + | Resource | ConsistsOf | 1..n | Facet | Any Resource consists of one or more Facets which describes the different aspects of the resource. | + +------------------------------------------------------+----------------+------------------+-----------------+----------------------------------------------------------------------------------------------------+ + + +The **Facet** current version is 1.0.0. + +Changelog: + +* **1.0.0**: First Version. + + +######## +Relation +######## + +This is the base type for any Relation + + +.. table:: **Relation** + + +-----------------------+-----------------------+----------------------------------------------------------+-----------------+----------------------------------------+ + | **Definition** | + +=======================+=======================+==========================================================+=================+========================================+ + | **Source** | **Relation** | **Multiplicity** | **Target** | **Description** | + +-----------------------+-----------------------+----------------------------------------------------------+-----------------+----------------------------------------+ + | Resource | Relation | 0..n | Entity | This is the base type for any Relation | + +-----------------------+-----------------------+----------------------------------------------------------+-----------------+----------------------------------------+ + | **Properties** | + +-----------------------+-----------------------+----------------------------------------------------------+-----------------+----------------------------------------+ + | **Name** | **Type** | **Attributes** | **Description** | + +-----------------------+-----------------------+----------------------------------------------------------+-----------------+----------------------------------------+ + | propagationConstraint | PropagationConstraint | ``Mandatory:false`` ``ReadOnly:false`` ``NotNull:false`` | | + +-----------------------+-----------------------+----------------------------------------------------------+-----------------+----------------------------------------+ + + +The **Relation** current version is 1.0.0. + +Changelog: + +* **1.0.0**: First Version. + + +********** +ConsistsOf +********** + +This is the base type for any ConsistsOf relation + + +.. table:: **ConsistsOf** ``extends`` **Relation** + + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Definition** | + +======================================================+==============+==================+==========================+=====================================================================================================================================================================================+ + | **Source** | **Relation** | **Multiplicity** | **Target** | **Description** | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Resource | ConsistsOf | 0..n | Facet | This is the base type for any ConsistsOf relation | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Properties** | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Name** | **Type** | **Attributes** | **Description** | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | This type does not define any additional attributes. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Known Usage** | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Source** | **Relation** | **Multiplicity** | **Target** | **Description** | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Actor | ConsistsOf | 0..n | ContactReferenceFacet | | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ConcreteDataset | ConsistsOf | 1..n | AccessPointFacet | The access point to use for having access to the concrete dataset. The embargoState can be modeled through the access policy defined in the consistsOf relation. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Dataset | ConsistsOf | 0..n | AccessPointFacet | The access point to use for having access to the dataset. The embargoState can be modeled through the access policy defined in the consistsOf relation. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Dataset | ConsistsOf | 0..n | DescriptiveMetadataFacet | Any descriptive information associated with the dataset, e.g. for discovery purposes. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Dataset | ConsistsOf | 0..n | EventFacet | Any 'event' characterising the lifecycle of the dataset, e.g. collection date, last collection date. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Dataset | ConsistsOf | 0..n | LicenseFacet | The licence governing dataset exploitation. The duration of license (if any) is captured by the expiry date defined in the consistsOf relation. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Dataset | ConsistsOf | 0..n | ProvenanceFacet | Any provenance record associated with the dataset. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Dataset | ConsistsOf | 0..n | SubjectFacet | Any subject/tag associated with the dataset for descriptive and discovery purposes. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | EService | ConsistsOf | 1..n | AccessPointFacet | Identify the endpoints of the EService. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | EService | ConsistsOf | 1..n | EventFacet | Events characterising the current status and lifecycle of the service, e.g. ActivationTime, DeploymentTime. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | EService | ConsistsOf | 0..n | LicenseFacet | The specific terms of use governing the exploitation of the EService. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | EService | ConsistsOf | 0..n | SoftwareFacet | Software available in the EService environment that characterizes the specific EService instance. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | EService | ConsistsOf | 1..1 | StateFacet | The current status of the EService, e.g. STARTED, ready, down, failed. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | HostingNode | ConsistsOf | 1..n | CPUFacet | The CPU equipping the Hosting Node. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | HostingNode | ConsistsOf | 1..n | EventFacet | Every event characterizing the life cycle of the Hosting Node, e.g. the activation time. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | HostingNode | ConsistsOf | 0..n | SimplePropertyFacet | Any pair property worth associating with the Hosting Node, e.g. Environment Variables | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | HostingNode | ConsistsOf | 0..n | SoftwareFacet | Any Software characterising the Hosting Node. Useful to report the hosted software that are not registered in the Resource Registry as Software Resource, e.g. Operating System | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | HostingNode | ConsistsOf | 1..1 | StateFacet | The current state of the Hosting Node, e.g. started, ready, certified, down, failed. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Resource | ConsistsOf | 1..n | Facet | Any Resource consists of one or more Facets which describes the different aspects of the resource. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Schema | ConsistsOf | 0..n | DescriptiveMetadataFacet | | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Schema | ConsistsOf | 0..n | SubjectFacet | | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Service | ConsistsOf | 0..n | CapabilityFacet | Any facility supported/offered by the Service. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Service | ConsistsOf | 0..n | DescriptiveMetadataFacet | Any descriptive information associated with the service, e.g. for discovery purposes. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Service | ConsistsOf | 0..n | SubjectFacet | Any subject/tag associated with the service for descriptive, cataloguing and discovery purposes. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Site | ConsistsOf | 1..n | LocationFacet | | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Site | ConsistsOf | 1..n | NetworkingFacet | | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Software | ConsistsOf | 0..n | CapabilityFacet | | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Software | ConsistsOf | 1..n | SoftwareFacet | Apart the one connected by the IsIdentifiedBy relation (gCube coordinates) the others identify the software in other way e.g. (Maven coordinates). | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | VirtualMachine | ConsistsOf | 1..n | CPUFacet | The CPU equipping the Virtual Machine. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | VirtualMachine | ConsistsOf | 1..n | EventFacet | Every event characterizing the life cycle of the Virtual Machine, e.g. the activation time. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | VirtualMachine | ConsistsOf | 0..n | SoftwareFacet | Any Software characterising the Virtual Machine. Useful to report the hosted software that are not registered in the Resource Registry as Software Resource, e.g. Operating System | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | VirtualMachine | ConsistsOf | 1..1 | StateFacet | The current state of the Virtual Machine, e.g. started, ready, down, unreachable. | + +------------------------------------------------------+--------------+------------------+--------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + + +The **ConsistsOf** current version is 1.0.0. + +Changelog: + +* **1.0.0**: First Version. + + +*********** +IsRelatedTo +*********** + +This is the base type for any IsRelatedTo relation + + +.. table:: **IsRelatedTo** ``extends`` **Relation** + + +------------------------------------------------------+--------------+------------------+-----------------+----------------------------------------------------+ + | **Definition** | + +======================================================+==============+==================+=================+====================================================+ + | **Source** | **Relation** | **Multiplicity** | **Target** | **Description** | + +------------------------------------------------------+--------------+------------------+-----------------+----------------------------------------------------+ + | Resource | IsRelatedTo | 0..n | Resource | This is the base type for any IsRelatedTo relation | + +------------------------------------------------------+--------------+------------------+-----------------+----------------------------------------------------+ + | **Properties** | + +------------------------------------------------------+--------------+------------------+-----------------+----------------------------------------------------+ + | **Name** | **Type** | **Attributes** | **Description** | + +------------------------------------------------------+--------------+------------------+-----------------+----------------------------------------------------+ + | This type does not define any additional attributes. | + +------------------------------------------------------+--------------+------------------+-----------------+----------------------------------------------------+ + | **Known Usage** | + +------------------------------------------------------+--------------+------------------+-----------------+----------------------------------------------------+ + | **Source** | **Relation** | **Multiplicity** | **Target** | **Description** | + +------------------------------------------------------+--------------+------------------+-----------------+----------------------------------------------------+ + | Resource | IsRelatedTo | 0..n | Resource | Any Resource can be related to any other resource. | + +------------------------------------------------------+--------------+------------------+-----------------+----------------------------------------------------+ + + +The **IsRelatedTo** current version is 1.0.0. + +Changelog: + +* **1.0.0**: First Version. + diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/generator/ClassesDiscoveryGenerator.java b/src/main/java/org/gcube/informationsystem/utils/documentation/generator/ClassesDiscoveryGenerator.java index 9a99451..c5c64d5 100644 --- a/src/main/java/org/gcube/informationsystem/utils/documentation/generator/ClassesDiscoveryGenerator.java +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/generator/ClassesDiscoveryGenerator.java @@ -16,10 +16,9 @@ import org.gcube.informationsystem.utils.discovery.RegistrationProvider; /** * @author Luca Frosini (ISTI - CNR) */ -public class ClassesDiscoveryGenerator { - +public class ClassesDiscoveryGenerator extends Generator { + protected TreeGenerator treeGenerator; - protected TypeListGenerator typeListGenerator; public ClassesDiscoveryGenerator() { diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/generator/Generator.java b/src/main/java/org/gcube/informationsystem/utils/documentation/generator/Generator.java new file mode 100644 index 0000000..f8f50e4 --- /dev/null +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/generator/Generator.java @@ -0,0 +1,142 @@ +package org.gcube.informationsystem.utils.documentation.generator; + +import java.io.File; +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.StandardOpenOption; + +import org.gcube.informationsystem.base.reference.AccessType; +import org.gcube.informationsystem.types.reference.Type; +import org.gcube.informationsystem.utils.documentation.model.DocumentationGenerator; +import org.gcube.informationsystem.utils.documentation.model.entities.EntityDocumentationGenerator; +import org.gcube.informationsystem.utils.documentation.model.entities.FacetDocumentationGenerator; +import org.gcube.informationsystem.utils.documentation.model.entities.ResourceDocumentationGenerator; +import org.gcube.informationsystem.utils.documentation.model.properties.PropertyDocumentationGenerator; +import org.gcube.informationsystem.utils.documentation.model.relations.ConsistsOfDocumentationGenerator; +import org.gcube.informationsystem.utils.documentation.model.relations.IsRelatedToDocumentationGenerator; +import org.gcube.informationsystem.utils.documentation.model.relations.RelationDocumentationGenerator; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +/** + * @author Luca Frosini (ISTI - CNR) + */ +public class Generator { + + private static final Logger logger = LoggerFactory.getLogger(Generator.class); + + protected AccessType[] accessTypes; + + public Generator() { + accessTypes = new AccessType[] { + AccessType.PROPERTY, + AccessType.ENTITY, AccessType.RESOURCE, AccessType.FACET, + AccessType.RELATION, AccessType.CONSISTS_OF, AccessType.IS_RELATED_TO + }; + } + + public Class getDocumentationGeneratorClass(AccessType accessType) + throws Exception { + Class clz; + switch (accessType) { + case PROPERTY: + clz = PropertyDocumentationGenerator.class; + break; + + case ENTITY: + clz = EntityDocumentationGenerator.class; + break; + + case RESOURCE: + clz = ResourceDocumentationGenerator.class; + break; + + case FACET: + clz = FacetDocumentationGenerator.class; + break; + + case RELATION: + clz = RelationDocumentationGenerator.class; + break; + + case IS_RELATED_TO: + clz = IsRelatedToDocumentationGenerator.class; + break; + + case CONSISTS_OF: + clz = ConsistsOfDocumentationGenerator.class; + break; + + default: + throw new Exception("List of types not recognized"); + } + return clz; + } + + protected DocumentationGenerator getDocumentationGenerator(Type type) throws Exception { + DocumentationGenerator dg = null; + switch (type.getAccessType()) { + case PROPERTY: + dg = new PropertyDocumentationGenerator(type); + break; + + case ENTITY: + dg = new EntityDocumentationGenerator(type); + break; + + case RESOURCE: + dg = new ResourceDocumentationGenerator(type); + break; + + case FACET: + dg = new FacetDocumentationGenerator(type); + break; + + case RELATION: + dg = new RelationDocumentationGenerator(type); + break; + + case IS_RELATED_TO: + dg = new IsRelatedToDocumentationGenerator(type); + break; + + case CONSISTS_OF: + dg = new ConsistsOfDocumentationGenerator(type); + break; + + default: + throw new Exception("I'm not developed to manage the " + AccessType.class.getSimpleName() + " " + type.getName()); + } + return dg; + } + + protected File getFile(String fileName, boolean newFile) throws IOException { + File file = new File(fileName); + + if(file.exists() && newFile) { + file.delete(); + } + + if(!file.exists()) { + logger.info("Going to create {}", file.getAbsolutePath()); + file.createNewFile(); + } + + return file; + } + + + protected void writeTypeToFile(Type type, File file, Integer level) throws Exception { + DocumentationGenerator dg = getDocumentationGenerator(type); + if(level!=null) { + dg.setLevel(level); + } + StringBuffer sb = dg.generate(); + Files.write(file.toPath(), sb.toString().getBytes(), StandardOpenOption.APPEND); + } + + protected void writeTypeToFile(Type type, File file) throws Exception { + writeTypeToFile(type, file, null); + } + +} diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/generator/TreeGenerator.java b/src/main/java/org/gcube/informationsystem/utils/documentation/generator/TreeGenerator.java index b193d9a..9ca4c52 100644 --- a/src/main/java/org/gcube/informationsystem/utils/documentation/generator/TreeGenerator.java +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/generator/TreeGenerator.java @@ -1,22 +1,33 @@ package org.gcube.informationsystem.utils.documentation.generator; +import java.io.File; +import java.nio.file.Files; +import java.nio.file.StandardOpenOption; import java.util.Map; import java.util.TreeMap; import org.gcube.informationsystem.base.reference.AccessType; import org.gcube.informationsystem.types.TypeMapper; import org.gcube.informationsystem.types.reference.Type; +import org.gcube.informationsystem.utils.documentation.knowledge.Node; +import org.gcube.informationsystem.utils.documentation.knowledge.NodeElaborator; import org.gcube.informationsystem.utils.documentation.knowledge.Tree; +import org.gcube.informationsystem.utils.documentation.model.DocumentationGenerator; import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** * @author Luca Frosini (ISTI - CNR) */ -public class TreeGenerator { +public class TreeGenerator extends Generator { private static final Logger logger = LoggerFactory.getLogger(TreeGenerator.class); + public static final String IS_MODEL_FILENAME = "is-model.rst"; + public static final String PROPERTIES_FILENAME = "properties.rst"; + public static final String ENTITIES_FILENAME = "entities.rst"; + public static final String RELATIONS_FILENAME = "relations.rst"; + protected Map types; public TreeGenerator() { @@ -31,6 +42,7 @@ public class TreeGenerator { types.put(accessType, tree); } if(type.getName().compareTo(accessType.getName())==0) { + // Head has been already added return; } Tree tree = types.get(accessType); @@ -38,39 +50,62 @@ public class TreeGenerator { } - public void elaborateTree(AccessType at, Tree tree) { - logger.info("\n{}", tree.toString()); + public void elaborateTree(final AccessType at, Tree tree, final File file) throws Exception { + logger.debug("Going to elaborate the following type tree\n{}", tree.toString()); -// elaborateList(propertyTypes); -// -// File f = getFile(ENTITIES_FILENAME, true); -// DocumentationGenerator edg = new EntityDocumentationGenerator(TypeMapper.createTypeDefinition(Entity.class)); -// edg.setOffsetLevel(offsetLevel); -// StringBuffer sb = edg.generateSection(); -// Files.write(f.toPath(), sb.toString().getBytes(), StandardOpenOption.APPEND); -// -// elaborateList(resourceTypes); -// elaborateList(facetTypes); -// -// f = getFile(RELATIONS_FILENAME, true); -// DocumentationGenerator rdg = new RelationDocumentationGenerator(TypeMapper.createTypeDefinition(Relation.class)); -// rdg.setOffsetLevel(offsetLevel); -// sb = rdg.generateSection(); -// Files.write(f.toPath(), sb.toString().getBytes(), StandardOpenOption.APPEND); -// -// elaborateList(isRelatedToTypes); -// elaborateList(consistsOfTypes); + NodeElaborator ne = new NodeElaborator() { + + @Override + public void elaborate(Node node, int level) throws Exception { + Type type = node.getType(); + if(level==0) { + /* + * Root node has been already documented in IS_MODEL_FILENAME + * Going to skip it + */ + DocumentationGenerator dg = getDocumentationGenerator(type); + dg.setLevel(level); + StringBuffer sb = dg.generateSection(); + Files.write(file.toPath(), sb.toString().getBytes(), StandardOpenOption.APPEND); + }else { + writeTypeToFile(type, file, level); + } + + } + }; + + tree.elaborate(ne); } + public void generate() throws Exception { - AccessType[] accessTypes = new AccessType[] { - AccessType.PROPERTY, - AccessType.RESOURCE, AccessType.FACET, - AccessType.CONSISTS_OF, AccessType.IS_RELATED_TO}; + File is = getFile(IS_MODEL_FILENAME, true); + File file = null; + for(AccessType at : accessTypes) { + Type type = TypeMapper.createTypeDefinition(at.getTypeClass()); + writeTypeToFile(type, is); + + switch (at) { + case PROPERTY: + file = getFile(PROPERTIES_FILENAME, true); + break; + + case ENTITY: + file = getFile(ENTITIES_FILENAME, true); + continue; + + case RELATION: + file = getFile(RELATIONS_FILENAME, true); + continue; + + default: + break; + } + Tree tree = types.get(at); - elaborateTree(at, tree); + elaborateTree(at, tree, file); } } diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/generator/TypeListGenerator.java b/src/main/java/org/gcube/informationsystem/utils/documentation/generator/TypeListGenerator.java deleted file mode 100644 index 5fc6c61..0000000 --- a/src/main/java/org/gcube/informationsystem/utils/documentation/generator/TypeListGenerator.java +++ /dev/null @@ -1,227 +0,0 @@ -package org.gcube.informationsystem.utils.documentation.generator; - -import java.io.File; -import java.io.IOException; -import java.lang.reflect.Constructor; -import java.nio.file.Files; -import java.nio.file.StandardOpenOption; -import java.util.ArrayList; -import java.util.List; -import java.util.Objects; - -import org.gcube.informationsystem.base.reference.AccessType; -import org.gcube.informationsystem.model.reference.entities.Entity; -import org.gcube.informationsystem.model.reference.properties.Property; -import org.gcube.informationsystem.model.reference.relations.Relation; -import org.gcube.informationsystem.types.TypeMapper; -import org.gcube.informationsystem.types.reference.Type; -import org.gcube.informationsystem.types.reference.entities.FacetType; -import org.gcube.informationsystem.types.reference.entities.ResourceType; -import org.gcube.informationsystem.types.reference.properties.PropertyType; -import org.gcube.informationsystem.types.reference.relations.ConsistsOfType; -import org.gcube.informationsystem.types.reference.relations.IsRelatedToType; -import org.gcube.informationsystem.utils.documentation.model.DocumentationGenerator; -import org.gcube.informationsystem.utils.documentation.model.entities.EntityDocumentationGenerator; -import org.gcube.informationsystem.utils.documentation.model.entities.FacetDocumentationGenerator; -import org.gcube.informationsystem.utils.documentation.model.entities.ResourceDocumentationGenerator; -import org.gcube.informationsystem.utils.documentation.model.properties.PropertyDocumentationGenerator; -import org.gcube.informationsystem.utils.documentation.model.relations.ConsistsOfDocumentationGenerator; -import org.gcube.informationsystem.utils.documentation.model.relations.IsRelatedToDocumentationGenerator; -import org.gcube.informationsystem.utils.documentation.model.relations.RelationDocumentationGenerator; -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; - -/** - * @author Luca Frosini (ISTI - CNR) - */ -public class TypeListGenerator { - - private static final Logger logger = LoggerFactory.getLogger(TypeListGenerator.class); - - public static final String PROPERTIES_FILENAME = "properties.rst"; - public static final String ENTITIES_FILENAME = "entities.rst"; - public static final String RELATIONS_FILENAME = "relations.rst"; - - protected List> propertyTypes; - protected List resourceTypes; - protected List facetTypes; - protected List isRelatedToTypes; - protected List consistsOfTypes; - - protected int offsetLevel; - - public TypeListGenerator() { - this.propertyTypes = new ArrayList<>(); - this.resourceTypes = new ArrayList<>(); - this.facetTypes = new ArrayList<>(); - this.isRelatedToTypes = new ArrayList<>(); - this.consistsOfTypes = new ArrayList<>(); - this.offsetLevel = 2; - } - - public List getResourceTypes() { - return resourceTypes; - } - - public void setResourceTypes(List resources) { - this.resourceTypes = resources; - } - - public List getFacetTypes() { - return facetTypes; - } - - public void setFacetTypes(List facets) { - this.facetTypes = facets; - } - - public List getIsRelatedToTypes() { - return isRelatedToTypes; - } - - public void setIsRelatedToTypes(List isRelatedToTypes) { - this.isRelatedToTypes = isRelatedToTypes; - } - - public List getConsistsOfTypes() { - return consistsOfTypes; - } - - public void setConsistsOfTypes(List consistsOfTypes) { - this.consistsOfTypes = consistsOfTypes; - } - - public void addType(Type type) { - switch (type.getAccessType()) { - case PROPERTY: - @SuppressWarnings("unchecked") - PropertyType p = (PropertyType) type; - propertyTypes.add(p); - break; - - case RESOURCE: - ResourceType r = (ResourceType) type; - resourceTypes.add(r); - break; - - case FACET: - FacetType f = (FacetType) type; - facetTypes.add(f); - break; - - case IS_RELATED_TO: - IsRelatedToType irt = (IsRelatedToType) type; - isRelatedToTypes.add(irt); - break; - - case CONSISTS_OF: - ConsistsOfType co = (ConsistsOfType) type; - consistsOfTypes.add(co); - break; - - default: - break; - } - } - - - protected File getFile(String fileName, boolean newFile) throws IOException { - File file = new File(fileName); - - if(file.exists() && newFile) { - file.delete(); - } - - if(!file.exists()) { - logger.info("Going to create {}", file.getAbsolutePath()); - file.createNewFile(); - } - - return file; - } - - public void checkList(List list) throws Exception { - Type first = list.get(0); - AccessType accessType = first.getAccessType(); - if(Objects.isNull(list) || list.size()==0) { - throw new Exception("Please add all " + accessType.getName() + " types before starting generation"); - } - } - - protected DocumentationGenerator getDocumentationGeneratorInstance(Class clz, Type type) throws Exception { - Constructor constructor = clz.getConstructor(Type.class); - return constructor.newInstance(type); - } - - public void elaborateList(List types) throws Exception { - Type first = types.get(0); - AccessType accessType = first.getAccessType(); - Class clz; - File f; - switch (accessType) { - case PROPERTY: - clz = PropertyDocumentationGenerator.class; - f = getFile(PROPERTIES_FILENAME, true); - break; - - case RESOURCE: - clz = ResourceDocumentationGenerator.class; - f = getFile(ENTITIES_FILENAME, false); - break; - - case FACET: - clz = FacetDocumentationGenerator.class; - f = getFile(ENTITIES_FILENAME, false); - break; - - case IS_RELATED_TO: - clz = IsRelatedToDocumentationGenerator.class; - f = getFile(RELATIONS_FILENAME, false); - break; - - case CONSISTS_OF: - clz = ConsistsOfDocumentationGenerator.class; - f = getFile(RELATIONS_FILENAME, false); - break; - - default: - throw new Exception("List of types not recognized"); - } - - for(Type type : types) { - DocumentationGenerator dg = getDocumentationGeneratorInstance(clz, type); - dg.setOffsetLevel(offsetLevel); - StringBuffer sb = dg.generateSection(); - Files.write(f.toPath(), sb.toString().getBytes(), StandardOpenOption.APPEND); - } - } - - public void generate() throws Exception { - checkList(propertyTypes); - checkList(resourceTypes); - checkList(facetTypes); - checkList(isRelatedToTypes); - checkList(consistsOfTypes); - - elaborateList(propertyTypes); - - File f = getFile(ENTITIES_FILENAME, true); - DocumentationGenerator edg = new EntityDocumentationGenerator(TypeMapper.createTypeDefinition(Entity.class)); - edg.setOffsetLevel(offsetLevel); - StringBuffer sb = edg.generateSection(); - Files.write(f.toPath(), sb.toString().getBytes(), StandardOpenOption.APPEND); - - elaborateList(resourceTypes); - elaborateList(facetTypes); - - f = getFile(RELATIONS_FILENAME, true); - DocumentationGenerator rdg = new RelationDocumentationGenerator(TypeMapper.createTypeDefinition(Relation.class)); - rdg.setOffsetLevel(offsetLevel); - sb = rdg.generateSection(); - Files.write(f.toPath(), sb.toString().getBytes(), StandardOpenOption.APPEND); - - elaborateList(isRelatedToTypes); - elaborateList(consistsOfTypes); - } - -} diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/Node.java b/src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/Node.java index b2830fb..d796538 100644 --- a/src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/Node.java +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/Node.java @@ -96,4 +96,16 @@ public class Node implements Comparable { return type.getName().compareTo(other.type.getName()); } + + + public void elaborate(NodeElaborator nodeElaborator) throws Exception { + elaborate(nodeElaborator, 0); + } + + protected void elaborate(NodeElaborator nodeElaborator, int level) throws Exception { + nodeElaborator.elaborate(this, level); + for (Node child : children) { + child.elaborate(nodeElaborator, level+1); + } + } } diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/NodeElaborator.java b/src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/NodeElaborator.java new file mode 100644 index 0000000..7e62057 --- /dev/null +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/NodeElaborator.java @@ -0,0 +1,10 @@ +package org.gcube.informationsystem.utils.documentation.knowledge; + +/** + * @author Luca Frosini (ISTI - CNR) + */ +public interface NodeElaborator { + + public void elaborate(Node node, int level) throws Exception; + +} diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/Tree.java b/src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/Tree.java index 246ff9f..77ac2a9 100644 --- a/src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/Tree.java +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/Tree.java @@ -27,6 +27,10 @@ public class Tree { } public void addNode(Type t) { + if(root.getType().getName().compareTo(t.getName())==0) { + // Root has been already added + return; + } Set superClasses = t.getSuperClasses(); for(String superClass : superClasses) { Node parent = locate.get(superClass); @@ -51,4 +55,7 @@ public class Tree { return root.toString(); } + public void elaborate(NodeElaborator nodeElaborator) throws Exception { + root.elaborate(nodeElaborator); + } } \ No newline at end of file diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/model/DocumentationGenerator.java b/src/main/java/org/gcube/informationsystem/utils/documentation/model/DocumentationGenerator.java index 1c2d415..4985c2d 100644 --- a/src/main/java/org/gcube/informationsystem/utils/documentation/model/DocumentationGenerator.java +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/model/DocumentationGenerator.java @@ -27,6 +27,9 @@ public abstract class DocumentationGenerator { private static final int DEFAULT_NUMBER_OF_COLUMNS = 5; + public static final String NO_ADDITIONAL_ATTRIBUTE = "This type does not define any additional attributes."; + public static final String NO_SPECIFIC_KNOWN_USAGE = "No specific known usage for this type."; + protected final Type type; protected final AccessType requiredType; protected String superClassToBeExcluded; @@ -187,12 +190,15 @@ public abstract class DocumentationGenerator { return row; } - protected Table addLinkedEntities(Table table, Collection entities) { - if(entities!=null) { + protected Table addLinkedEntities(Table table, Collection entities, String messageFroNullOrEmptyCollection) { + if(entities!=null && entities.size()>0) { for(LinkedEntity entity : entities) { Row row = getLinkedEntityrow(entity); table.appendRow(row); } + }else { + Row row = getRowCellSpan(messageFroNullOrEmptyCollection, requiredNumberOfColumns);; + table.appendRow(row); } return table; } @@ -254,7 +260,7 @@ public abstract class DocumentationGenerator { } protected Row getNoPropertyRow() { - return getRowCellSpan("This type does not define any additional attributes.", requiredNumberOfColumns); + return getRowCellSpan(NO_ADDITIONAL_ATTRIBUTE, requiredNumberOfColumns); } protected Row addCellSpanToRow(Row row, String content, int cellSpan) { @@ -328,7 +334,27 @@ public abstract class DocumentationGenerator { return stringBuffer; } - protected StringBuffer getChangelog() { + public Section getSection() { + Section section = new Section(); + int sectionLevel = level+offsetLevel; + SectionType[] sectionTypes = SectionType.values(); + int maxSectionLevel = sectionTypes.length; + sectionLevel = sectionLevel>=maxSectionLevel ? maxSectionLevel : sectionLevel; + SectionType sectionType = SectionType.values()[sectionLevel]; + section.setSectionType(sectionType); + return section; + } + + public StringBuffer generateSection() { + StringBuffer stringBuffer = new StringBuffer(); + stringBuffer.append("\n"); + Section section = getSection(); + String name = type.getName(); + stringBuffer.append(section.generate(name)); + return stringBuffer; + } + + protected StringBuffer generateChangelog() { StringBuffer stringBuffer = new StringBuffer(); stringBuffer.append("The **"); stringBuffer.append(type.getName()); @@ -356,23 +382,21 @@ public abstract class DocumentationGenerator { protected abstract Table getTable(); - public StringBuffer generateSection() { + protected StringBuffer generateTable() { StringBuffer stringBuffer = new StringBuffer(); - stringBuffer.append("\n"); - String name = type.getName(); - Section section = new Section(); - SectionType sectionType = SectionType.values()[level+offsetLevel]; - stringBuffer.append(section.generateSection(sectionType, name)); - stringBuffer.append(type.getDescription()); - stringBuffer.append("\n"); - String tableTitle = getTypeDeclaration().toString(); Table table = getTable(); stringBuffer.append(table.generateTable(tableTitle)); - - stringBuffer.append(getChangelog()); - - logger.info(stringBuffer.toString()); + return stringBuffer; + } + + public StringBuffer generate() { + StringBuffer stringBuffer = generateSection(); + stringBuffer.append(type.getDescription()); + stringBuffer.append("\n"); + stringBuffer.append(generateTable()); + stringBuffer.append(generateChangelog()); + logger.trace(stringBuffer.toString()); return stringBuffer; } } diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/model/entities/FacetDocumentationGenerator.java b/src/main/java/org/gcube/informationsystem/utils/documentation/model/entities/FacetDocumentationGenerator.java index d469340..2e4faca 100644 --- a/src/main/java/org/gcube/informationsystem/utils/documentation/model/entities/FacetDocumentationGenerator.java +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/model/entities/FacetDocumentationGenerator.java @@ -35,7 +35,7 @@ public class FacetDocumentationGenerator extends EntityDocumentationGenerator { UsageKnowledge fk = UsageKnowledge.getFacetKnowledge(); Set usage = fk.getUsage(type.getName()); - addLinkedEntities(table, usage); + addLinkedEntities(table, usage, NO_SPECIFIC_KNOWN_USAGE); return table; } diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/model/entities/ResourceDocumentationGenerator.java b/src/main/java/org/gcube/informationsystem/utils/documentation/model/entities/ResourceDocumentationGenerator.java index c53cfa8..11539c5 100644 --- a/src/main/java/org/gcube/informationsystem/utils/documentation/model/entities/ResourceDocumentationGenerator.java +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/model/entities/ResourceDocumentationGenerator.java @@ -14,6 +14,11 @@ import org.gcube.informationsystem.utils.documentation.rst.table.Table; */ public class ResourceDocumentationGenerator extends EntityDocumentationGenerator { + public static final String FACETS_TABLE_HEADING = "**Facets**"; + public static final String RESOURCE_RELATIONS_TABLE_HEADING = "**Resource Relations**"; + public static final String NO_SPECIFIC_FACETS = "No specific facets usage defined for this type."; + public static final String NO_SPECIFIC_RESOURCE_RELATIONS = "No specific Resource relations defined for this type."; + public ResourceDocumentationGenerator(Type type) { super(type,AccessType.RESOURCE); int level = 1; @@ -32,15 +37,15 @@ public class ResourceDocumentationGenerator extends EntityDocumentationGenerator protected Table getTable() { Table table = new Table(); table.appendRow(getSourceTargetHeadingRow()); - table.appendRow(getRowCellSpan("**Facets**", requiredNumberOfColumns)); + table.appendRow(getRowCellSpan(FACETS_TABLE_HEADING, requiredNumberOfColumns)); ResourceType resourceType = (ResourceType) type; UsageKnowledge fk = UsageKnowledge.getFacetKnowledge(); Set facets = fk.getUsage(resourceType.getName()); - addLinkedEntities(table, facets); - table.appendRow(getRowCellSpan("**Relations**", requiredNumberOfColumns)); + addLinkedEntities(table, facets, NO_SPECIFIC_FACETS); + table.appendRow(getRowCellSpan(RESOURCE_RELATIONS_TABLE_HEADING, requiredNumberOfColumns)); UsageKnowledge rk = UsageKnowledge.getResourceKnowledge(); Set resources = rk.getUsage(resourceType.getName()); - addLinkedEntities(table, resources); + addLinkedEntities(table, resources, NO_SPECIFIC_RESOURCE_RELATIONS); return table; } diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/model/relations/ConsistsOfDocumentationGenerator.java b/src/main/java/org/gcube/informationsystem/utils/documentation/model/relations/ConsistsOfDocumentationGenerator.java index 0bfd104..d8cd1dc 100644 --- a/src/main/java/org/gcube/informationsystem/utils/documentation/model/relations/ConsistsOfDocumentationGenerator.java +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/model/relations/ConsistsOfDocumentationGenerator.java @@ -30,7 +30,7 @@ public class ConsistsOfDocumentationGenerator extends RelationDocumentationGener table.appendRow(getSourceTargetBoldRow()); UsageKnowledge fk = UsageKnowledge.getFacetKnowledge(); Set facets = fk.getUsage(type.getName()); - addLinkedEntities(table, facets); + addLinkedEntities(table, facets, NO_SPECIFIC_KNOWN_USAGE); return table; } diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/model/relations/IsRelatedToDocumentationGenerator.java b/src/main/java/org/gcube/informationsystem/utils/documentation/model/relations/IsRelatedToDocumentationGenerator.java index acef10f..d9c6603 100644 --- a/src/main/java/org/gcube/informationsystem/utils/documentation/model/relations/IsRelatedToDocumentationGenerator.java +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/model/relations/IsRelatedToDocumentationGenerator.java @@ -30,7 +30,7 @@ public class IsRelatedToDocumentationGenerator extends RelationDocumentationGene table.appendRow(getSourceTargetBoldRow()); UsageKnowledge rk = UsageKnowledge.getResourceKnowledge(); Set resources = rk.getUsage(type.getName()); - addLinkedEntities(table, resources); + addLinkedEntities(table, resources, NO_SPECIFIC_KNOWN_USAGE); return table; } diff --git a/src/main/java/org/gcube/informationsystem/utils/documentation/rst/Section.java b/src/main/java/org/gcube/informationsystem/utils/documentation/rst/Section.java index af489a6..88740ae 100644 --- a/src/main/java/org/gcube/informationsystem/utils/documentation/rst/Section.java +++ b/src/main/java/org/gcube/informationsystem/utils/documentation/rst/Section.java @@ -22,6 +22,24 @@ public class Section { } } + protected SectionType sectionType; + + public Section() { + this.sectionType = SectionType.HEADING_1; + } + + public Section(SectionType sectionType) { + this.sectionType = sectionType; + } + + public SectionType getSectionType() { + return sectionType; + } + + public void setSectionType(SectionType sectionType) { + this.sectionType = sectionType; + } + protected StringBuffer getSectionSeparation(String separator, int lenght) { StringBuffer stringBuffer = new StringBuffer(); for(int i=0; i