gCubeSystem
/
information-system-model-documentation-generator
15
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improved doc generation

This commit is contained in:
Luca Frosini 2023-01-24 16:54:00 +01:00
parent a7e597fbd4
commit 22e2a36a4c
15 changed files with 584 additions and 283 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

277
is-model.rst Normal file
View File

@ -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 <key,value> 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.

5
src/main/java/org/gcube/informationsystem/utils/documentation/generator/ClassesDiscoveryGenerator.java
View File

@ -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() {

142
src/main/java/org/gcube/informationsystem/utils/documentation/generator/Generator.java Normal file
View File

@ -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<? extends DocumentationGenerator> getDocumentationGeneratorClass(AccessType accessType)
throws Exception {
Class<? extends DocumentationGenerator> 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);
}
}

89
src/main/java/org/gcube/informationsystem/utils/documentation/generator/TreeGenerator.java
View File

@ -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<AccessType, Tree> 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);
}
}

227
src/main/java/org/gcube/informationsystem/utils/documentation/generator/TypeListGenerator.java
View File

@ -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<PropertyType<Property>> propertyTypes;
protected List<ResourceType> resourceTypes;
protected List<FacetType> facetTypes;
protected List<IsRelatedToType> isRelatedToTypes;
protected List<ConsistsOfType> 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<ResourceType> getResourceTypes() {
return resourceTypes;
}
public void setResourceTypes(List<ResourceType> resources) {
this.resourceTypes = resources;
}
public List<FacetType> getFacetTypes() {
return facetTypes;
}
public void setFacetTypes(List<FacetType> facets) {
this.facetTypes = facets;
}
public List<IsRelatedToType> getIsRelatedToTypes() {
return isRelatedToTypes;
}
public void setIsRelatedToTypes(List<IsRelatedToType> isRelatedToTypes) {
this.isRelatedToTypes = isRelatedToTypes;
}
public List<ConsistsOfType> getConsistsOfTypes() {
return consistsOfTypes;
}
public void setConsistsOfTypes(List<ConsistsOfType> consistsOfTypes) {
this.consistsOfTypes = consistsOfTypes;
}
public void addType(Type type) {
switch (type.getAccessType()) {
case PROPERTY:
@SuppressWarnings("unchecked")
PropertyType<Property> p = (PropertyType<Property>) 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<? extends Type> 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<? extends DocumentationGenerator> clz, Type type) throws Exception {
Constructor<? extends DocumentationGenerator> constructor = clz.getConstructor(Type.class);
return constructor.newInstance(type);
}
public void elaborateList(List<? extends Type> types) throws Exception {
Type first = types.get(0);
AccessType accessType = first.getAccessType();
Class<? extends DocumentationGenerator> 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);
}
}

12
src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/Node.java
View File

@ -96,4 +96,16 @@ public class Node implements Comparable<Node> {
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);
}
}
}

10
src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/NodeElaborator.java Normal file
View File

@ -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;
}

7
src/main/java/org/gcube/informationsystem/utils/documentation/knowledge/Tree.java
View File

@ -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<String> 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);
}
}

58
src/main/java/org/gcube/informationsystem/utils/documentation/model/DocumentationGenerator.java
View File

@ -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<LinkedEntity> entities) {
if(entities!=null) {
protected Table addLinkedEntities(Table table, Collection<LinkedEntity> 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;
}
}

2
src/main/java/org/gcube/informationsystem/utils/documentation/model/entities/FacetDocumentationGenerator.java
View File

@ -35,7 +35,7 @@ public class FacetDocumentationGenerator extends EntityDocumentationGenerator {
UsageKnowledge fk = UsageKnowledge.getFacetKnowledge();
Set<LinkedEntity> usage = fk.getUsage(type.getName());
addLinkedEntities(table, usage);
addLinkedEntities(table, usage, NO_SPECIFIC_KNOWN_USAGE);
return table;
}

13
src/main/java/org/gcube/informationsystem/utils/documentation/model/entities/ResourceDocumentationGenerator.java
View File

@ -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<LinkedEntity> 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<LinkedEntity> resources = rk.getUsage(resourceType.getName());
addLinkedEntities(table, resources);
addLinkedEntities(table, resources, NO_SPECIFIC_RESOURCE_RELATIONS);
return table;
}

2
src/main/java/org/gcube/informationsystem/utils/documentation/model/relations/ConsistsOfDocumentationGenerator.java
View File

@ -30,7 +30,7 @@ public class ConsistsOfDocumentationGenerator extends RelationDocumentationGener
table.appendRow(getSourceTargetBoldRow());
UsageKnowledge fk = UsageKnowledge.getFacetKnowledge();
Set<LinkedEntity> facets = fk.getUsage(type.getName());
addLinkedEntities(table, facets);
addLinkedEntities(table, facets, NO_SPECIFIC_KNOWN_USAGE);
return table;
}

2
src/main/java/org/gcube/informationsystem/utils/documentation/model/relations/IsRelatedToDocumentationGenerator.java
View File

@ -30,7 +30,7 @@ public class IsRelatedToDocumentationGenerator extends RelationDocumentationGene
table.appendRow(getSourceTargetBoldRow());
UsageKnowledge rk = UsageKnowledge.getResourceKnowledge();
Set<LinkedEntity> resources = rk.getUsage(type.getName());
addLinkedEntities(table, resources);
addLinkedEntities(table, resources, NO_SPECIFIC_KNOWN_USAGE);
return table;
}

20
src/main/java/org/gcube/informationsystem/utils/documentation/rst/Section.java
View File

@ -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<lenght; i++) {
@ -30,7 +48,7 @@ public class Section {
return stringBuffer;
}
public StringBuffer generateSection(SectionType sectionType, String sectionTitle) {
public StringBuffer generate(String sectionTitle) {
StringBuffer stringBuffer = new StringBuffer();
int lenght = sectionTitle.length();
if(sectionType.overline) {

1
src/test/java/org/gcube/informationsystem/utils/documentation/table/TableTest.java
View File

@ -4,7 +4,6 @@ import org.gcube.informationsystem.utils.documentation.rst.table.Cell;
import org.gcube.informationsystem.utils.documentation.rst.table.Row;
import org.gcube.informationsystem.utils.documentation.rst.table.RowType;
import org.gcube.informationsystem.utils.documentation.rst.table.Table;
import org.junit.Test;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;