Documentation & Release workflow (#30)

* Test upload

* Fix path

* fix packaging

* conditional upload

* conditional upload fix

* Release workflow

* release

* fix

* fix upload and tag

* Set theme jekyll-theme-slate

* Create index.md

Initialise GH pages

* Docs

* Move index

* GH pages links

* Refator model context and aliases as separate concepts

* Add branch specifier on release workflow

* Fix cyclic method call

* Move alias class to separate package

* Move model alias definition into alias package

* Add Javadoc plugin for lib and netcdf modules

Author: simonoakesepimorphics

.github/workflows/release.yaml

@@ -0,0 +1,44 @@
+# This workflow will build a Java project with Maven
+# For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-maven
+name: GitHub tagged release
+on:
+  push:
+    branches: [ "master" ]
+    tags: [ "*" ]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up JDK 1.8
+        uses: actions/setup-java@v1
+        with:
+          java-version: 1.8
+      - name: Cache Maven packages
+        uses: actions/cache@v2
+        with:
+          path: ~/.m2
+          key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
+          restore-keys: ${{ runner.os }}-m2
+      - name: Install NetCDF tools
+        run: sudo apt install netcdf-bin
+      - name: Maven build
+        run: mvn clean package
+      - name: Create Release
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ github.ref }}
+      - name: Upload Release Asset
+        id: upload-release-asset
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: ./binary-array-ld-cli/target/bald-cli.jar
+          asset_name: bald-cli.jar
+          asset_content_type: application/java-archive

README.md

@@ -1,7 +1,7 @@
 # Binary Array Linked Data
 
 [Kotlin](https://kotlinlang.org/) library and CLI for Binary Array Linked Data (BALD) functionality.
-* NetCDF to RDF conversion according to [OGC draft specification](http://docs.opengeospatial.org/DRAFTS/19-002.html).
+* [GitHub Pages](https://binary-array-ld.github.io/net.binary_array_ld.bald/)
 
 This project consists of the following modules:
 * **binary-array-ld-lib** Core library containing BALD functionality. In particular, binary array to linked data (RDF) conversion.
@@ -11,87 +11,17 @@ 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.
-
-### Library
-
-To use the BALD core library, add the following dependency to your Maven project:
-
-```xml
-<dependency>
-    <groupId>net.binary-array-ld</groupId>
-    <artifactId>binary-array-ld-lib</artifactId>
-    <version>${bald.version}</version>
-</dependency>
-```
-
-You can implement the `net.bald.BinaryArray` interface with your own metadata representations and supply them to the API.
-
-For NetCDF metadata files, you can use the pre-made NetCDF implementation in the `binary-array-ld-netcdf` module.
-To use this module, add the following dependency to your Maven project:
+See the [GitHub pages](https://binary-array-ld.github.io/net.binary_array_ld.bald/usage.html) for usage documentation.
 
-```xml
-<dependency>
-    <groupId>net.binary-array-ld</groupId>
-    <artifactId>binary-array-ld-netcdf</artifactId>
-    <version>${bald.version}</version>
-</dependency>
-```
-
-#### Example
-Kotlin:
-```kotlin
-val ba = NetCdfBinaryArray.create("/path/to/input.nc", "http://test.binary-array-ld.net/example")
-val model = ModelBinaryArrayConverter.convert(ba)
-File("/path/to/output.ttl").outputStream.use { output ->
-    model.write(output, "ttl")
-}
-```
-Java:
-```
-BinaryArray ba = NetCdfBinaryArray.create("/path/to/input.ttl", "http://test.binary-array-ld.net/example");
-Model model = ModelBinaryArrayConverter.convert(ba);
-
-try (OutputStream output = new FileOutputStream("/path/to/output.ttl")) {
-    model.write(output, "ttl");
-}
-```
-
-### Command Line Interface
-
-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.
-
-By default, the RDF graph output will be in [Turtle](https://www.w3.org/TR/turtle/) format.
-You can use the `--output` or `-o` option to specify the RDF format to emit.
-This option can accept any of the RDF formats supported by Apache Jena, eg. JSON-LD and RDFXML.
+## Development
 
-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
-```
+Note that, in order to run the automated tests for this project,
+the `ncgen` command line tool must be available on your system.
 
-#### 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
-```
+You can use Maven to build this project and each of its modules with `mvn clean package`.
+After building, the JAR for the command line application is located at `binary-array-ld-cli/target/bald-cli.jar`.
 
 
 

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

@@ -1,7 +1,8 @@
 package net.bald
 
+import net.bald.alias.AliasDefinition
 import net.bald.context.ModelContext
-import net.bald.model.ModelAliasDefinition
+import net.bald.alias.ModelAliasDefinition
 import net.bald.model.ModelBinaryArrayConverter
 import net.bald.netcdf.NetCdfBinaryArray
 import org.apache.commons.cli.DefaultParser
@@ -38,9 +39,10 @@ class BinaryArrayConvertCli {
     }
 
     private fun doRun(opts: CommandLineOptions) {
-        val context = context(opts.contextLocs, opts.aliasLocs)
+        val context = context(opts.contextLocs)
+        val alias = alias(opts.aliasLocs)
         val inputLoc = opts.inputLoc ?: throw IllegalArgumentException("First argument is required: NetCDF file to convert.")
-        val ba = NetCdfBinaryArray.create(inputLoc, opts.uri, context)
+        val ba = NetCdfBinaryArray.create(inputLoc, opts.uri, context, alias)
         val model = ba.use(ModelBinaryArrayConverter::convert)
         val outputFormat = opts.outputFormat ?: "ttl"
 
@@ -49,15 +51,18 @@ class BinaryArrayConvertCli {
         }
     }
 
-    private fun context(contextLocs: List<String>, aliasLocs: List<String>): ModelContext {
+    private fun context(contextLocs: List<String>): ModelContext {
         val prefixes = contextLocs.map { contextLoc ->
             ModelFactory.createDefaultModel().read(contextLoc, "json-ld")
         }
-        val alias = ModelFactory.createDefaultModel().apply {
+
+        return ModelContext.create(prefixes)
+    }
+
+    private fun alias(aliasLocs: List<String>): AliasDefinition {
+        return ModelFactory.createDefaultModel().apply {
             aliasLocs.forEach(::read)
         }.let(ModelAliasDefinition::create)
-
-        return ModelContext.create(prefixes, alias)
     }
 
     private fun options(opts: Options, vararg args: String): CommandLineOptions {

binary-array-ld-demo/src/main/java/net/bald/NetCdfConvertJava.java

@@ -1,8 +1,8 @@
 package net.bald;
 
-import net.bald.context.AliasDefinition;
+import net.bald.alias.AliasDefinition;
 import net.bald.context.ModelContext;
-import net.bald.model.ModelAliasDefinition;
+import net.bald.alias.ModelAliasDefinition;
 import net.bald.model.ModelBinaryArrayConverter;
 import net.bald.netcdf.NetCdfBinaryArray;
 import org.apache.jena.rdf.model.Model;
@@ -26,8 +26,8 @@ public static void convert() throws Exception {
 
     public static void convertWithExternalPrefixes() throws Exception {
         PrefixMapping prefix = ModelFactory.createDefaultModel().read("/path/to/context.json", "json-ld");
-        ModelContext context = ModelContext.create(prefix, null);
-        BinaryArray ba = NetCdfBinaryArray.create("/path/to/input.nc", "http://test.binary-array-ld.net/example", context);
+        ModelContext context = ModelContext.create(prefix);
+        BinaryArray ba = NetCdfBinaryArray.create("/path/to/input.nc", "http://test.binary-array-ld.net/example", context, null);
         Model model = ModelBinaryArrayConverter.convert(ba);
 
         try (OutputStream output = new FileOutputStream("/path/to/output.ttl")) {
@@ -36,13 +36,9 @@ public static void convertWithExternalPrefixes() throws Exception {
     }
 
     public static void convertWithAliases() throws Exception {
-        PrefixMapping prefix = PrefixMapping.Factory.create();
         Model aliasModel = ModelFactory.createDefaultModel().read("/path/to/alias.ttl", "ttl");
         AliasDefinition alias = ModelAliasDefinition.create(aliasModel);
-        ModelContext context = ModelContext.create(prefix, alias);
-
-        BinaryArray ba = NetCdfBinaryArray.create("/path/to/input.nc", "http://test.binary-array-ld.net/example", context);
-
+        BinaryArray ba = NetCdfBinaryArray.create("/path/to/input.nc", "http://test.binary-array-ld.net/example", null, alias);
         Model model = ModelBinaryArrayConverter.convert(ba);
 
         try (OutputStream output = new FileOutputStream("/path/to/output.ttl")) {

binary-array-ld-lib/pom.xml

@@ -41,4 +41,13 @@
             <version>${jena.version}</version>
         </dependency>
     </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.jetbrains.dokka</groupId>
+                <artifactId>dokka-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
 </project>

binary-array-ld-lib/src/main/kotlin/net/bald/context/AliasDefinition.kt renamed to binary-array-ld-lib/src/main/kotlin/net/bald/alias/AliasDefinition.kt

@@ -1,4 +1,4 @@
-package net.bald.context
+package net.bald.alias
 
 import org.apache.jena.rdf.model.Property
 import org.apache.jena.rdf.model.Resource
@@ -29,6 +29,9 @@ interface AliasDefinition {
      */
     fun isReferenceProperty(prop: Property): Boolean
 
+    /**
+     * A substitute [AliasDefinition] implementation that represents a null or empty definition.
+     */
     object Empty: AliasDefinition {
         override fun property(identifier: String): Property? {
             return null

binary-array-ld-lib/src/main/kotlin/net/bald/model/ModelAliasDefinition.kt renamed to binary-array-ld-lib/src/main/kotlin/net/bald/alias/ModelAliasDefinition.kt

@@ -1,6 +1,5 @@
-package net.bald.model
+package net.bald.alias
 
-import net.bald.context.AliasDefinition
 import net.bald.vocab.BALD
 import org.apache.jena.rdf.model.*
 import org.apache.jena.vocabulary.DCTerms

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

@@ -1,16 +1,12 @@
 package net.bald.context
 
-import org.apache.jena.rdf.model.Property
-import org.apache.jena.rdf.model.Resource
 import org.apache.jena.shared.PrefixMapping
 
 /**
  * The external context in which a binary array can be resolved.
- * This includes resource and property aliases as defined by [AliasDefinition]
- * and the available namespace prefix mappings.
- * @see AliasDefinition
+ * This includes any available namespace prefix mappings.
  */
-interface ModelContext: AliasDefinition {
+interface ModelContext {
     /**
      * Prefix mappings that are available in this context.
      */
@@ -21,41 +17,24 @@ interface ModelContext: AliasDefinition {
      */
     object Empty: ModelContext {
         override val prefixMapping: PrefixMapping get() = PrefixMapping.Factory.create()
-        override fun property(identifier: String): Property? = null
-        override fun resource(identifier: String): Resource? = null
-        override fun isReferenceProperty(prop: Property): Boolean = false
     }
 
     /**
      * A basic [ModelContext] implementation that simply composes the prefix mapping and alias elements.
      */
     class Base(
-        override val prefixMapping: PrefixMapping,
-        private val alias: AliasDefinition
-    ): ModelContext {
-        override fun property(identifier: String): Property? {
-            return alias.property(identifier)
-        }
-
-        override fun resource(identifier: String): Resource? {
-            return alias.resource(identifier)
-        }
-
-        override fun isReferenceProperty(prop: Property): Boolean {
-            return alias.isReferenceProperty(prop)
-        }
-    }
+        override val prefixMapping: PrefixMapping
+    ): ModelContext
 
     companion object {
         /**
          * Instantiate a wrapper for the external elements which contextualise a binary array conversion.
          * @throws IllegalArgumentException If there are conflicting definitions in the prefix mappings.
          * @param prefixes The contextual prefix mappings.
-         * @param alias The contextual alias definition.
          * @return The [ModelContext].
          */
         @JvmStatic
-        fun create(prefixes: List<PrefixMapping>, alias: AliasDefinition? = null): ModelContext {
+        fun create(prefixes: List<PrefixMapping>): ModelContext {
             val prefix = if (prefixes.isEmpty()) {
                 PrefixMapping.Factory.create()
             } else {
@@ -73,15 +52,15 @@ interface ModelContext: AliasDefinition {
                     }
                 }
             }
-            return create(prefix, alias)
+            return create(prefix)
         }
 
         /**
          * @see create
          */
         @JvmStatic
-        fun create(prefix: PrefixMapping, alias: AliasDefinition? = null): ModelContext {
-            return Base(prefix, alias ?: AliasDefinition.Empty)
+        fun create(prefix: PrefixMapping): ModelContext {
+            return Base(prefix)
         }
     }
 }

binary-array-ld-lib/src/test/kotlin/net/bald/context/ModelContextTest.kt

@@ -1,19 +1,18 @@
 package net.bald.context
 
-import com.nhaarman.mockitokotlin2.mock
 import org.apache.jena.shared.PrefixMapping
 import org.apache.jena.vocabulary.DCTerms
 import org.apache.jena.vocabulary.SKOS
 import org.apache.jena.vocabulary.VCARD
-import org.junit.jupiter.api.*
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
 import kotlin.test.assertEquals
 
 class ModelContextTest {
     private val prefix = PrefixMapping.Factory.create()
         .setNsPrefix("skos", SKOS.uri)
         .setNsPrefix("dct", DCTerms.getURI())
-    private val alias = mock<AliasDefinition>()
-    private val context = ModelContext.create(prefix, alias)
+    private val context = ModelContext.create(prefix)
 
     /**
      * Requirements class B-4
@@ -41,7 +40,7 @@ class ModelContextTest {
                 .setNsPrefix("vcard", VCARD.uri)
                 .setNsPrefix("dct", DCTerms.getURI())
         )
-        val context = ModelContext.create(prefixes, alias)
+        val context = ModelContext.create(prefixes)
         val result = context.prefixMapping.nsPrefixMap
         val expected = mapOf(
             "skos" to SKOS.uri,
@@ -65,7 +64,7 @@ class ModelContextTest {
                 .setNsPrefix("dct", DCTerms.getURI())
         )
         val iae = assertThrows<IllegalArgumentException> {
-            ModelContext.create(prefixes, alias)
+            ModelContext.create(prefixes)
         }
         assertEquals("The namespace prefixes [skos] have conflicting definitions in contexts.", iae.message)
     }