8 - Identity and root vars (#19)

* Add vocab reference object

* Add classes for composing RDF model

* Add RDF model test utils and tests

* Add binary array to model conversion API impl

* Add NetCDF binary array factory method impl, tests

* Add CLI impl, test, docs

* Add file container, refactor

* Add file container to tests

* Fix tests

* Changed test data to CDL format

* Fix Java version on demo

* ADD name and subgroups to container concept

* Enhance binary array converter to describe subgroups

* Fix test consistency

Author: simonoakesepimorphics

README.md

@@ -11,6 +11,11 @@ RDF representations are provided by [Apache Jena](https://jena.apache.org/).
 * **binary-array-ld-test** Common test utilities used by other modules.
 * **binary-array-ld-demo** Demonstrations of BALD API usage.
 
+## Development
+
+Note that, in order to run the automated tests for this project,
+the `ncgen` command line tool must be available on your system.
+
 ## Usage
 
 This project can be used either as a library or as a command line application.
@@ -60,7 +65,29 @@ try (OutputStream output = new FileOutputStream("/path/to/output.ttl")) {
 ```
 
 ### Command Line Interface
-( TODO )
+
+To use the BALD CLI, build the project using `mvn clean package` on the root directory.
+Then, you can run the JAR located at `binary-array-ld-cli/target/bald-cli.jar` using the `java-jar` command.
+
+The application accepts arguments in the following format: 
+ ```
+java -jar binary-array-ld-cli/target/bald-cli.jar [options] inputFile [outputFile]
+```
+Where `inputFile` is the location of the NetCDF file to convert,
+and `outputFile` is the location of the file in which to output the RDF graph.
+If you don't specify an `outputFile`, the graph will be printed on the command line.
+
+You can also supply various options.
+Use the `-h` or `--help` option to emit full documentation for the available options.
+```
+java -jar binary-array-ld-cli/target/bald-cli.jar -h
+```
+
+#### Example
+From the `binary-array-ld-cli/target` directory:
+```
+java -jar bald-cli.jar --uri http://test.binary-array-ld.net/example /path/to/netcdf.nc /path/to/graph.ttl
+```
 
 
 

binary-array-ld-cli/pom.xml

@@ -55,6 +55,8 @@
                             <goal>single</goal>
                         </goals>
                         <configuration>
+                            <finalName>bald-cli</finalName>
+                            <appendAssemblyId>false</appendAssemblyId>
                             <archive>
                                 <manifest>
                                     <mainClass>net.bald.BinaryArrayConvertCliKt</mainClass>

binary-array-ld-cli/src/main/kotlin/net/bald/BinaryArrayConvertCli.kt

@@ -1,14 +1,65 @@
 package net.bald
 
+import net.bald.model.ModelBinaryArrayConverter
+import net.bald.netcdf.NetCdfBinaryArray
+import org.apache.commons.cli.DefaultParser
+import org.apache.commons.cli.HelpFormatter
+import org.apache.commons.cli.Options
+import java.io.File
+import java.io.OutputStream
+import kotlin.system.exitProcess
+
 /**
  * Command Line Interface for converting NetCDF metadata to Linked Data graphs.
  */
 class BinaryArrayConvertCli {
+    private val opts = Options().apply {
+        this.addOption("u", "uri", true, "The URI which identifies the dataset.")
+        this.addOption("h", "help", false, "Show help.")
+    }
+
     fun run(vararg args: String) {
-        TODO()
+        val cmdOpts = options(opts, *args)
+        if (cmdOpts.help) {
+            help()
+        } else {
+            try {
+                doRun(cmdOpts)
+            } catch (e: Exception) {
+                help()
+                throw e
+            }
+        }
+    }
+
+    private fun doRun(opts: CommandLineOptions) {
+        val inputLoc = opts.inputLoc ?: throw IllegalArgumentException("First argument is required: NetCDF file to convert.")
+        val ba = NetCdfBinaryArray.create(inputLoc, opts.uri)
+        val model = ba.use(ModelBinaryArrayConverter::convert)
+
+        modelOutput(opts.outputLoc).use { output ->
+            model.write(output, "ttl")
+        }
+    }
+
+    private fun options(opts: Options, vararg args: String): CommandLineOptions {
+        return DefaultParser().parse(opts, args).let(::CommandLineOptions)
+    }
+
+    private fun help() {
+        HelpFormatter().printHelp("[options] inputFile [outputFile]", opts)
+    }
+
+    private fun modelOutput(outputLoc: String?): OutputStream {
+        return outputLoc?.let(::File)?.outputStream() ?: System.out
     }
 }
 
 fun main(args: Array<String>) {
-    BinaryArrayConvertCli().run(*args)
+    try {
+        BinaryArrayConvertCli().run(*args)
+    } catch (e: Exception) {
+        println("Conversion failed due to error: ${e.message}")
+        exitProcess(1)
+    }
 }

binary-array-ld-cli/src/main/kotlin/net/bald/CommandLineOptions.kt

@@ -0,0 +1,14 @@
+package net.bald
+
+import org.apache.commons.cli.CommandLine
+
+class CommandLineOptions(
+    private val cmd: CommandLine,
+) {
+    val inputLoc: String? get() {
+        return cmd.args.getOrNull(0)
+    }
+    val outputLoc: String? get() = cmd.args.getOrNull(1)
+    val uri: String? get() = cmd.getOptionValue("uri")
+    val help: Boolean get() = cmd.hasOption("help")
+}

binary-array-ld-cli/src/test/kotlin/net/bald/BinaryArrayConvertCliTest.kt

@@ -0,0 +1,120 @@
+package net.bald
+
+import bald.model.ModelVerifier
+import bald.netcdf.CdlConverter.convertToNetCdf
+import net.bald.vocab.BALD
+import org.apache.jena.rdf.model.ModelFactory.createDefaultModel
+import org.apache.jena.vocabulary.RDF
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
+import kotlin.test.assertEquals
+
+/**
+ * Integration test for [BinaryArrayConvertCli].
+ */
+class BinaryArrayConvertCliTest {
+    private fun run(vararg args: String) {
+        BinaryArrayConvertCli().run(*args)
+    }
+
+    @Test
+    fun run_withoutInputFile_fails() {
+        val iae = assertThrows<IllegalArgumentException> {
+            run()
+        }
+        assertEquals("First argument is required: NetCDF file to convert.", iae.message)
+    }
+
+    @Test
+    fun run_withHelp_doesNotValidate() {
+        run("-h")
+    }
+
+    @Test
+    fun run_withoutUri_outputsToFileWithInputFileUri() {
+        val inputFile = convertToNetCdf("/netcdf/identity.cdl")
+        val inputFileUri = inputFile.toPath().toUri().toString()
+        val outputFile = createTempFile()
+        run(inputFile.absolutePath, outputFile.absolutePath)
+
+        val model = createDefaultModel().read(outputFile.toURI().toString(), "ttl")
+        ModelVerifier(model).apply {
+            resource(inputFileUri) {
+                statement(RDF.type, BALD.Container)
+                statement(BALD.contains, model.createResource("$inputFileUri/")) {
+                    statement(RDF.type, BALD.Container)
+                    statement(BALD.contains, model.createResource("$inputFileUri/var0")) {
+                        statement(RDF.type, BALD.Resource)
+                    }
+                    statement(BALD.contains, model.createResource("$inputFileUri/var1")) {
+                        statement(RDF.type, BALD.Resource)
+                    }
+                }
+            }
+        }
+    }
+
+    @Test
+    fun run_withUri_withOutputFile_outputsToFile() {
+        val inputFile = convertToNetCdf("/netcdf/identity.cdl")
+        val outputFile = createTempFile()
+        run("--uri", "http://test.binary-array-ld.net/example", inputFile.absolutePath, outputFile.absolutePath)
+
+        val model = createDefaultModel().read(outputFile.toURI().toString(), "ttl")
+        ModelVerifier(model).apply {
+            resource("http://test.binary-array-ld.net/example") {
+                statement(RDF.type, BALD.Container)
+                statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/")) {
+                    statement(RDF.type, BALD.Container)
+                    statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/var0")) {
+                        statement(RDF.type, BALD.Resource)
+                    }
+                    statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/var1")) {
+                        statement(RDF.type, BALD.Resource)
+                    }
+                }
+            }
+        }
+    }
+
+    @Test
+    fun run_withSubgroups_outputsWithSubgroups() {
+        val inputFile = convertToNetCdf("/netcdf/identity-subgroups.cdl")
+        val outputFile = createTempFile()
+        run("--uri", "http://test.binary-array-ld.net/example", inputFile.absolutePath, outputFile.absolutePath)
+
+        val model = createDefaultModel().read(outputFile.toURI().toString(), "ttl")
+        ModelVerifier(model).apply {
+            resource("http://test.binary-array-ld.net/example") {
+                statement(RDF.type, BALD.Container)
+                statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/")) {
+                    statement(RDF.type, BALD.Container)
+                    statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/group0")) {
+                        statement(RDF.type, BALD.Container)
+                        statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/group0/var2")) {
+                            statement(RDF.type, BALD.Resource)
+                        }
+                        statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/group0/var3")) {
+                            statement(RDF.type, BALD.Resource)
+                        }
+                    }
+                    statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/group1")) {
+                        statement(RDF.type, BALD.Container)
+                        statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/group1/var4")) {
+                            statement(RDF.type, BALD.Resource)
+                        }
+                        statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/group1/var5")) {
+                            statement(RDF.type, BALD.Resource)
+                        }
+                    }
+                    statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/var0")) {
+                        statement(RDF.type, BALD.Resource)
+                    }
+                    statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/var1")) {
+                        statement(RDF.type, BALD.Resource)
+                    }
+                }
+            }
+        }
+    }
+}

binary-array-ld-demo/pom.xml

@@ -11,6 +11,18 @@
 
     <artifactId>binary-array-ld-demo</artifactId>
     <version>1.0.0-SNAPSHOT</version>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>1.8</source>
+                    <target>1.8</target>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
 
     <name>Binary Array Linked Data - Demos</name>
     <description>Examples of Binary Array to Linked Data API usage.</description>

binary-array-ld-lib/src/main/kotlin/net/bald/Container.kt

@@ -5,9 +5,21 @@ package net.bald
  * See https://www.opengis.net/def/binary-array-ld/Container
  */
 interface Container {
+    /**
+     * The local name of the container, if it has one.
+     * The root container may have no name or an empty name.
+     */
+    val name: String?
+
     /**
      * Obtain the variables associates with this container.
      * @return The variables.
      */
     fun vars(): Sequence<Var>
+
+    /**
+     * Obtain the sub-containers of this container.
+     * @return The containers.
+     */
+    fun subContainers(): Sequence<Container>
 }

binary-array-ld-lib/src/main/kotlin/net/bald/model/ModelBinaryArrayBuilder.kt

@@ -0,0 +1,23 @@
+package net.bald.model
+
+import net.bald.BinaryArray
+import net.bald.vocab.BALD
+import org.apache.jena.rdf.model.Model
+
+class ModelBinaryArrayBuilder(
+    private val model: Model,
+    private val containerFct: ModelContainerBuilder.Factory
+) {
+    fun addBinaryArray(ba: BinaryArray) {
+        val baRes = model.createResource(ba.uri, BALD.Container)
+        containerFct.forParent(baRes).addContainer(ba.root)
+    }
+
+    class Factory(
+        private val containerFct: ModelContainerBuilder.Factory
+    ) {
+        fun forModel(model: Model): ModelBinaryArrayBuilder {
+            return ModelBinaryArrayBuilder(model, containerFct)
+        }
+    }
+}

binary-array-ld-lib/src/main/kotlin/net/bald/model/ModelBinaryArrayConverter.kt

@@ -8,13 +8,21 @@ import org.apache.jena.rdf.model.ModelFactory
  * API for converting a [BinaryArray] to a linked data [Model].
  */
 object ModelBinaryArrayConverter {
+    private val modelFct = run {
+        val varFct = ModelVarBuilder.Factory()
+        val containerFct = ModelContainerBuilder.Factory(varFct)
+        ModelBinaryArrayBuilder.Factory(containerFct)
+    }
+
     /**
      * Convert the given binary array metadata into a linked data model.
      * @param ba The binary array to convert.
      * @return The resulting model.
      */
     @JvmStatic
     fun convert(ba: BinaryArray): Model {
-        TODO()
+        val model = ModelFactory.createDefaultModel()
+        modelFct.forModel(model).addBinaryArray(ba)
+        return model
     }
 }

binary-array-ld-lib/src/main/kotlin/net/bald/model/ModelContainerBuilder.kt

@@ -0,0 +1,47 @@
+package net.bald.model
+
+import net.bald.vocab.BALD
+import net.bald.Container
+import org.apache.jena.rdf.model.Resource
+
+open class ModelContainerBuilder(
+    private val parent: Resource,
+    private val varFct: ModelVarBuilder.Factory
+) {
+    open fun addContainer(container: Container) {
+        val containerUri = containerUri(container)
+        val containerRes = parent.model.createResource(containerUri, BALD.Container)
+        buildSubgroups(container, containerRes)
+        buildVars(container, containerRes)
+        parent.addProperty(BALD.contains, containerRes)
+    }
+
+    private fun containerUri(container: Container): String {
+        val parentUri = parent.uri
+        val prefix = if (parentUri.endsWith('/')) parentUri else "$parentUri/"
+        return prefix + (container.name ?: "")
+    }
+
+    private fun buildSubgroups(container: Container, containerRes: Resource) {
+        val builder = ModelContainerBuilder(containerRes, varFct)
+        container.subContainers().forEach(builder::addContainer)
+    }
+
+    private fun buildVars(container: Container, containerRes: Resource) {
+        varFct.forContainer(containerRes).apply {
+            container.vars().forEach(::addVar)
+        }
+    }
+
+    open class Factory(
+        private val varFct: ModelVarBuilder.Factory
+    ) {
+        open fun forParent(parent: Resource): ModelContainerBuilder {
+            return ModelContainerBuilder(parent, varFct)
+        }
+    }
+}
+
+
+
+