9.1 Internal Prefixes (#20)

* 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

* Fix Java version in maven compiler plugin

* Add prefix mapping concept on binary array

* Add prefix mapping to model composition, tests

* Add NetCDF impl of prefix mapping concept

* Add tests, upgrade test format to NetCDF4 to support prefix group.

* Add logback config on CLI to suppress debug logs

* NetCDF4 considerations in tests

* Add file container, refactor

* Add file container to tests

* Fix tests

* Changed test data to CDL format

* Remove NCML references

* Fix Java version on demo

* ADD name and subgroups to container concept

* Enhance binary array converter to describe subgroups

* Fix test consistency

* Add prefix var support

* Remove prefix group / var from graph

* Replace BALD prefix mapping concept with Jena prefix mapping

* Fix merge issue

* Use common test method

* Add prefix mapping validation

Author: simonoakesepimorphics

binary-array-ld-cli/src/main/resources/logback.xml

@@ -0,0 +1,11 @@
+<configuration>
+    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+        </encoder>
+    </appender>
+
+    <root level="info">
+        <appender-ref ref="STDOUT" />
+    </root>
+</configuration>

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

@@ -1,16 +1,23 @@
 package net.bald
 
 import bald.model.ModelVerifier
-import bald.netcdf.CdlConverter.convertToNetCdf
+import bald.netcdf.CdlConverter.writeToNetCdf
 import net.bald.vocab.BALD
 import org.apache.jena.rdf.model.ModelFactory.createDefaultModel
 import org.apache.jena.vocabulary.RDF
+import org.apache.jena.vocabulary.SKOS
+import org.junit.Assume
+import org.junit.jupiter.api.BeforeEach
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.assertThrows
+import ucar.nc2.jni.netcdf.Nc4Iosp
 import kotlin.test.assertEquals
 
 /**
  * Integration test for [BinaryArrayConvertCli].
+ *
+ * Test resources are stored in CDL format and converted to temporary NetCDF 4 files.
+ * In order to write the NetCDF 4 files, the ncgen command line utility must be available.
  */
 class BinaryArrayConvertCliTest {
     private fun run(vararg args: String) {
@@ -32,7 +39,7 @@ class BinaryArrayConvertCliTest {
 
     @Test
     fun run_withoutUri_outputsToFileWithInputFileUri() {
-        val inputFile = convertToNetCdf("/netcdf/identity.cdl")
+        val inputFile = writeToNetCdf("/netcdf/identity.cdl")
         val inputFileUri = inputFile.toPath().toUri().toString()
         val outputFile = createTempFile()
         run(inputFile.absolutePath, outputFile.absolutePath)
@@ -56,12 +63,33 @@ class BinaryArrayConvertCliTest {
 
     @Test
     fun run_withUri_withOutputFile_outputsToFile() {
-        val inputFile = convertToNetCdf("/netcdf/identity.cdl")
+        val inputFile = writeToNetCdf("/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/var0")) {
+                    statement(RDF.type, BALD.Resource)
+                }
+                statement(BALD.contains, model.createResource("http://test.binary-array-ld.net/example/var1")) {
+                    statement(RDF.type, BALD.Resource)
+                }
+            }
+        }
+    }
+
+    private fun run_withPrefixMapping_outputsPrefixMapping(cdlLoc: String) {
+        val inputFile = writeToNetCdf(cdlLoc)
+        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 {
+            prefix("bald", BALD.prefix)
+            prefix("skos", SKOS.uri)
             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/")) {
@@ -77,9 +105,19 @@ class BinaryArrayConvertCliTest {
         }
     }
 
+    @Test
+    fun run_withPrefixMappingGroup_outputsPrefixMapping() {
+        run_withPrefixMapping_outputsPrefixMapping("/netcdf/prefix.cdl")
+    }
+
+    @Test
+    fun run_withPrefixMappingVar_outputsPrefixMapping() {
+        run_withPrefixMapping_outputsPrefixMapping("/netcdf/prefix-var.cdl")
+    }
+
     @Test
     fun run_withSubgroups_outputsWithSubgroups() {
-        val inputFile = convertToNetCdf("/netcdf/identity-subgroups.cdl")
+        val inputFile = writeToNetCdf("/netcdf/identity-subgroups.cdl")
         val outputFile = createTempFile()
         run("--uri", "http://test.binary-array-ld.net/example", inputFile.absolutePath, outputFile.absolutePath)
 

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

@@ -1,5 +1,7 @@
 package net.bald
 
+import org.apache.jena.shared.PrefixMapping
+
 /**
  * Represents the metadata of a binary array dataset.
  * See https://www.opengis.net/def/binary-array-ld/Array
@@ -10,6 +12,11 @@ interface BinaryArray {
      */
     val uri: String
 
+    /**
+     * The prefix mapping to apply to the RDF graph.
+     */
+    val prefixMapping: PrefixMapping
+
     /**
      * The root container.
      */

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

@@ -3,16 +3,46 @@ package net.bald.model
 import net.bald.BinaryArray
 import net.bald.vocab.BALD
 import org.apache.jena.rdf.model.Model
+import org.apache.jena.shared.PrefixMapping
+import java.net.URI
 
 class ModelBinaryArrayBuilder(
     private val model: Model,
     private val containerFct: ModelContainerBuilder.Factory
 ) {
     fun addBinaryArray(ba: BinaryArray) {
+        addPrefixMapping(ba.prefixMapping)
         val baRes = model.createResource(ba.uri, BALD.Container)
         containerFct.forParent(baRes).addContainer(ba.root)
     }
 
+    private fun addPrefixMapping(prefixMapping: PrefixMapping) {
+        prefixMapping.nsPrefixMap.onEach { (prefix, uri) ->
+            validatePrefixMapping(prefix, uri)
+        }.let(model::setNsPrefixes)
+    }
+
+    private fun validatePrefixMapping(prefix: String, uri: String) {
+        try {
+            if (!Prefix.pattern.matches(prefix)) {
+                throw IllegalArgumentException("Prefix must match pattern ${Prefix.pattern}.")
+            } else if (!uri.endsWith('/') && !uri.endsWith('#')) {
+                throw IllegalArgumentException("URI must end with / or #.")
+            } else {
+                val scheme = URI.create(uri).scheme
+                if (scheme != "http" && scheme != "https") {
+                    throw IllegalArgumentException("URI must have HTTP or HTTPS scheme.")
+                }
+            }
+        } catch (e: Exception) {
+            throw IllegalArgumentException("Unable to add prefix mapping $prefix to model: ${e.message}")
+        }
+    }
+
+    private object Prefix {
+        val pattern = Regex("[A-Za-z_]+")
+    }
+
     class Factory(
         private val containerFct: ModelContainerBuilder.Factory
     ) {

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

@@ -11,7 +11,7 @@ import org.apache.jena.rdf.model.ResourceFactory.createResource
  * See https://www.opengis.net/def/binary-array-ld/.
  */
 object BALD {
-    private const val prefix = "https://www.opengis.net/def/binary-array-ld/"
+    const val prefix = "https://www.opengis.net/def/binary-array-ld/"
 
     /**
      * Resources

binary-array-ld-lib/src/test/kotlin/net/bald/model/ModelBinaryArrayBuilderTest.kt

@@ -9,8 +9,13 @@ import net.bald.BinaryArray
 import net.bald.Container
 import net.bald.vocab.BALD
 import org.apache.jena.rdf.model.ModelFactory
+import org.apache.jena.shared.PrefixMapping
 import org.apache.jena.vocabulary.RDF
-import org.junit.jupiter.api.*
+import org.apache.jena.vocabulary.SKOS
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
+import java.lang.IllegalArgumentException
+import kotlin.test.assertEquals
 
 class ModelBinaryArrayBuilderTest {
     private val containerBuilder = mock<ModelContainerBuilder>()
@@ -20,9 +25,13 @@ class ModelBinaryArrayBuilderTest {
     private val model = ModelFactory.createDefaultModel()
     private val builder = ModelBinaryArrayBuilder.Factory(containerFct).forModel(model)
     private val root = mock<Container>()
+    private val prefix = PrefixMapping.Factory.create()
+        .setNsPrefix("bald", BALD.prefix)
+        .setNsPrefix("skos", SKOS.uri)
     private val ba = mock<BinaryArray> {
         on { uri } doReturn "http://test.binary-array-ld.net/example"
         on { this.root } doReturn root
+        on { prefixMapping } doReturn prefix
     }
 
     @Test
@@ -39,4 +48,40 @@ class ModelBinaryArrayBuilderTest {
         verify(containerFct).forParent(model.getResource("http://test.binary-array-ld.net/example"))
         verify(containerBuilder).addContainer(root)
     }
+
+    @Test
+    fun addBinaryArray_addsPrefixMapping() {
+        builder.addBinaryArray(ba)
+        ModelVerifier(model).apply {
+            prefix("bald", BALD.prefix)
+            prefix("skos", SKOS.uri)
+        }
+    }
+
+    @Test
+    fun addBinaryArray_prefixMappingWithInvalidChar_throwsException() {
+        prefix.setNsPrefix("bald-eg", "http://example.org/prefix/")
+        val iae = assertThrows<IllegalArgumentException> {
+            builder.addBinaryArray(ba)
+        }
+        assertEquals("Unable to add prefix mapping bald-eg to model: Prefix must match pattern [A-Za-z_]+.", iae.message)
+    }
+
+    @Test
+    fun addBinaryArray_prefixMappingWithInvalidScheme_throwsException() {
+        prefix.setNsPrefix("eg", "file:///example/prefix/")
+        val iae = assertThrows<IllegalArgumentException> {
+            builder.addBinaryArray(ba)
+        }
+        assertEquals("Unable to add prefix mapping eg to model: URI must have HTTP or HTTPS scheme.", iae.message)
+    }
+
+    @Test
+    fun addBinaryArray_prefixMappingWithoutTrailingChar_throwsException() {
+        prefix.setNsPrefix("eg", "http://example.org/prefix")
+        val iae = assertThrows<IllegalArgumentException> {
+            builder.addBinaryArray(ba)
+        }
+        assertEquals("Unable to add prefix mapping eg to model: URI must end with / or #.", iae.message)
+    }
 }

binary-array-ld-lib/src/test/kotlin/net/bald/model/ModelBinaryArrayConverterTest.kt

@@ -8,7 +8,9 @@ import net.bald.Container
 import net.bald.Var
 import net.bald.vocab.BALD
 import org.apache.jena.rdf.model.Model
+import org.apache.jena.shared.PrefixMapping
 import org.apache.jena.vocabulary.RDF
+import org.apache.jena.vocabulary.SKOS
 import org.junit.jupiter.api.*
 
 /**
@@ -33,13 +35,19 @@ class ModelBinaryArrayConverterTest {
             on { vars() } doReturn vars.asSequence()
             on { subContainers() } doReturn emptySequence()
         }
+        val prefix = PrefixMapping.Factory.create()
+            .setNsPrefix("bald", BALD.prefix)
+            .setNsPrefix("skos", SKOS.uri)
         val ba = mock<BinaryArray> {
             on { uri } doReturn "http://test.binary-array-ld.net/example"
             on { this.root } doReturn root
+            on { prefixMapping } doReturn prefix
         }
         val model = convert(ba)
 
         ModelVerifier(model).apply {
+            prefix("bald", BALD.prefix)
+            prefix("skos", SKOS.uri)
             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/")) {

binary-array-ld-netcdf/src/main/kotlin/net/bald/netcdf/NetCdfBinaryArray.kt

@@ -2,10 +2,11 @@ package net.bald.netcdf
 
 import net.bald.BinaryArray
 import net.bald.Container
-import ucar.nc2.NetcdfFile
-import ucar.nc2.NetcdfFiles
+import org.apache.jena.shared.PrefixMapping
+import ucar.nc2.*
 import java.io.Closeable
 import java.io.File
+import java.lang.IllegalStateException
 
 /**
  * NetCDF implementation of [BinaryArray].
@@ -15,12 +16,41 @@ class NetCdfBinaryArray(
     override val uri: String,
     private val file: NetcdfFile
 ): BinaryArray, Closeable {
-    override val root: Container get() = NetCdfContainer(file.rootGroup)
+    override val root: Container get() = container(file.rootGroup)
+    override val prefixMapping: PrefixMapping get() = prefixMapping() ?: PrefixMapping.Factory.create()
 
     override fun close() {
         file.close()
     }
 
+    private fun container(group: Group): Container {
+        val prefixSrc = prefixSourceName()
+        return NetCdfContainer(group, prefixSrc)
+    }
+
+    private fun prefixMapping(): PrefixMapping? {
+        return prefixSource()?.let(::NetCdfPrefixMappingBuilder)?.build()
+    }
+
+    private fun prefixSource(): AttributeContainer? {
+        return prefixSourceName()?.let { name ->
+            file.findGroup(name)
+                ?: file.findVariable(name)
+                ?: throw IllegalStateException("Prefix group or variable $name not found.")
+        }
+    }
+
+    private fun prefixSourceName(): String? {
+        return file.findGlobalAttribute(Attribute.prefix)?.let { attr ->
+            attr.stringValue
+                ?: throw IllegalStateException("Global prefix attribute ${Attribute.prefix} has a non-string value.")
+        }
+    }
+
+    private object Attribute {
+        const val prefix = "bald__isPrefixedBy"
+    }
+
     companion object {
         /**
          * Instantiate a [BinaryArray] representation of the given NetCDF file and identifying URI.
@@ -31,9 +61,17 @@ class NetCdfBinaryArray(
          */
         @JvmStatic
         fun create(fileLoc: String, uri: String? = null): NetCdfBinaryArray {
-            val requiredUri = uri ?: uri(fileLoc)
             val file = NetcdfFiles.open(fileLoc)
-            return NetCdfBinaryArray(requiredUri, file)
+            val requiredUri = uri ?: uri(fileLoc)
+            return create(file, requiredUri)
+        }
+
+        /**
+         * @see [create].
+         */
+        @JvmStatic
+        fun create(file: NetcdfFile, uri: String): NetCdfBinaryArray {
+            return NetCdfBinaryArray(uri, file)
         }
 
         private fun uri(fileLoc: String): String {

binary-array-ld-netcdf/src/main/kotlin/net/bald/netcdf/NetCdfContainer.kt

@@ -3,20 +3,30 @@ package net.bald.netcdf
 import net.bald.Container
 import net.bald.Var
 import ucar.nc2.Group
+import ucar.nc2.Variable
 
 /**
  * NetCDF implementation of [Container].
  */
 class NetCdfContainer(
-    private val group: Group
+    private val group: Group,
+    private val prefixSrc: String? = null
 ): Container {
     override val name: String? get() = group.shortName
 
     override fun vars(): Sequence<Var> {
-        return group.variables.asSequence().map(::NetCdfVar)
+        return group.variables.asSequence().filter(::acceptVar).map(::NetCdfVar)
     }
 
     override fun subContainers(): Sequence<Container> {
-        return group.groups.asSequence().map(::NetCdfContainer)
+        return group.groups.asSequence().filter(::acceptGroup).map(::NetCdfContainer)
+    }
+
+    private fun acceptVar(v: Variable): Boolean {
+        return prefixSrc != v.shortName
+    }
+
+    private fun acceptGroup(group: Group): Boolean {
+        return prefixSrc != group.shortName
     }
 }