Package org.gcube.informationsystem.resourceregistry.documentation

Class RegistryDocumentationGenerator

java.lang.Object

org.gcube.informationsystem.resourceregistry.documentation.RegistryDocumentationGenerator

public class RegistryDocumentationGenerator
extends Object

Renders the live-registry documentation product distinct from the committed static docs (see the Architectural Decisions Log, "Two distinct documentation products"): the is-model bucket still comes from the classpath, since is-model is compile-time and never runtime-mutable, but the domain-model bucket comes from a SchemaSnapshot via SchemaSnapshotTypesDiscoverer, so a runtime-registered type is included exactly like a classpath-declared one.

Writing is atomic with respect to whatever serves outputDirectory: the whole documentation set is rendered into a fresh temporary directory first, then swapped into place by two directory renames, so a reader of outputDirectory never observes a partially written set. Neither the wiring of when this runs (on startup, on schema change) nor how outputDirectory is exposed to clients is this class's concern.

Author:

Luca Frosini (ISTI - CNR)

Constructor Summary

Constructors

Constructor	Description
RegistryDocumentationGenerator(String format)	Creates a generator that renders in the given format.

Method Summary

Modifier and Type	Method	Description
void	generate(SchemaSnapshot snapshot, org.gcube.informationsystem.registry.RegistryMetadata registryMetadata, File outputDirectory)	Renders the documentation for snapshot and atomically publishes it to outputDirectory, showing the models of registryMetadata in the sidebar.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

RegistryDocumentationGenerator

public RegistryDocumentationGenerator(String format)

Creates a generator that renders in the given format.

Parameters:

format - the template format to render (e.g. "md")

Method Details

generate

public void generate(SchemaSnapshot snapshot,
 org.gcube.informationsystem.registry.RegistryMetadata registryMetadata,
 File outputDirectory)
              throws Exception

Renders the documentation for snapshot and atomically publishes it to outputDirectory, showing the models of registryMetadata in the sidebar.

Parameters:

snapshot - the schema snapshot to document the domain-model bucket from

registryMetadata - the record the sidebar shows: one line per model, is-model first and the runtime model last, and the global revision count; it also names the domain-model bucket, after the domain model or, with none, after the runtime model

outputDirectory - the directory readers observe; replaced atomically on success, left untouched on failure

Throws:

Exception - if building the model knowledge or rendering the templates fails

IOException - if the temporary directory cannot be created or the swap fails