Merge pull request #30 from gchq/develop

Release 2.0.0

Author: GCHQDeveloper42

Diff for: .gitignore

@@ -6,11 +6,13 @@
 target/
 bin/
 tdb/
+out
 *.code-workspace
 *.iml
 *.ttl
 .DS_Store
 .factorypath
+.devcontainer
 
 
 # Compiled class file
@@ -36,3 +38,8 @@ tdb/
 
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
 hs_err_pid*
+
+# Vim files
+*.swp
+tags
+.vim/

Diff for: .gitmodules

@@ -43,6 +43,8 @@ Where possible a pull request should correlate to a single GitHub issue. An issu
 
 Please ensure your coding style is consistent with rest of the project and follows our coding standards and best practices.
 
+> A `java-formatter.xml` configuration file is provided in the root of the project. Please include this in for editor settings when developing Magma Core.
+
 Checkstyle is run as part of `mvn install` so you should ensure your code is compliant with these rules. The project will not build if there are checkstyle errors.
 
 In particular please ensure you have adhered to the following:

Diff for: CONTRIBUTING.md

@@ -10,22 +10,35 @@ This code release is a contribution to support the adoption of data models that
 
 \* Dr. West was not involved in the creation of this project. GCHQ are grateful for his open contributions to the field of ontology and data quality management.
 
+
+## The High Quality Data Model for Data Integration in Java
+
+HQDM contains the replication of an openly available data model based on key ontological foundations to enable the consistent integration of data. The HQDM Java package comprises a set of Java classes and respective interfaces, 230 in total, to replicate the entity-relationship model published by Dr Matthew West as the [High Quality Data Model Framework](http://www.informationjunction.co.uk/hqdm_framework/). This class model can be used to create extensions of the entity types, based on the founding ontological commitments and logical restrictions (such as cardinalities), and instances of those types all in Java application code. This, in theory at least, provides a framework for the consistent representation of almost anything that is, or could be, real\*. All the data model patterns published in the HQDM framework are supported by the HQDM package. The object properties are constructed around a top-level Java HQDM Object class with some root attributes to enable class-instances to be managed in a database. The choice of database can be left to the user but the structure of the attributes is optimised for the use of [Linked Data IRIs](https://www.w3.org/TR/rdf11-concepts/#section-IRIs) and [RDF triples](https://www.w3.org/TR/rdf11-concepts/#section-triples) to represent HQDM object relationships and other object properties as predicates. All of the HQDM objects can be created and searched using the HQDMObject methods and collections can be handled using the Object Factory. To complement this there is an OWL version of the HQDM data model that is a close match for the original EXPRESS model and the HQDM Java package.
+
+\* This is a gross simplification, but it characterises the goal of the model and in use it has proved to be very capable. The UK's National Digital Twin programme is developing a model that aims to address this goal with even more rigour, called the Foundation Data Model (FDM). Data created using HQDM is likely to be mappable to the FDM with low mapping (due to similar ontological commitments).
+
 ## Getting Started
 
-An introduction to Magma Core and the [HQDM Java object library](https://github.com/gchq/HQDM) is provided in the [Magma Core Wiki](https://github.com/gchq/MagmaCore/wiki).
+An introduction to Magma Core is provided in the [Magma Core Wiki](https://github.com/gchq/MagmaCore/wiki).
 
 ### Prerequisites
 
-- [Java 15](https://openjdk.java.net/projects/jdk/15/) - Core language
+- [Java 17](https://openjdk.java.net/projects/jdk/17/) - Core language
 - [Maven](https://maven.apache.org/) - Dependency management
 
-## Setup
+### Inclusion in other projects
+
+Magma Core can be incorporated into other maven projects using the following dependency:
+
+```xml
+<dependency>
+  <groupId>uk.gov.gchq.magmacore</groupId>
+  <artifactId>core</artifactId>
+  <version>1.0</version>
+</dependency>
+```
 
-- To run Magma Core, run `mvn compile exec:java -Dexec.mainClass="uk.gov.gchq.magmacore.MagmaCore"`. This will execute the selected example method from the demo package. Alternatively, if you are using an IDE, you should be able to run the main method in MagmaCore.java from the editor.
-- To select which example to run, change the FusekiService.run() call in MagmaCore.java to the desired demo class in magmacore/demo. Each of these demos have slightly different behaviours, which are described in the code.
-- By default, this is set to the Fuseki server example, which will build and populate a Jena dataset hosted on a Fuseki server accessible at `localhost:3330/tdb`
-  - The dataset can then be queried via a web browser by going to `http://localhost:3330/tdb/sparql?query=SELECT ?s ?p ?o WHERE {?s ?p ?o.}`
-  - This can also be done via curl on the command line using: `curl -X POST -d "query=select ?s ?p ?o where { ?s ?p ?o . }" localhost:3330/tdb/query`
+_Magma Core is not currently hosted on Maven Central, so a local install of this repository will be required._
 
 ## Contributing
 

Diff for: HQDM

@@ -2,6 +2,21 @@
 <!DOCTYPE suppressions PUBLIC "-//Checkstyle//DTD Suppressions 1.2//EN" "https://checkstyle.org/dtds/suppressions_1_2.dtd">
 
 <suppressions>
-  <suppress checks="Indentation|HiddenField" files="\.java" />
-  <suppress checks="MethodLength|LineLength" files="ExampleDataObjects.java" />
-</suppressions>
+  <!-- global suppressions -->
+  <suppress checks="AvoidStarImport" files="\.java" />
+
+  <!-- core suppressions -->
+  <suppress checks="AbbreviationAsWordInName" files="UID\.java" />
+
+  <!-- examples suppressions -->
+  <suppress checks="LineLength" files="ExampleDataObjects.java|ExampleRdl.java|ExampleAssociations.java" />
+  <suppress checks="MethodLength" files="ExampleDataObjects.java" />
+
+  <!-- hqdm-core suppressions -->
+  <suppress checks="MethodName" files="impl/*" />
+  <suppress checks="TypeName" files="Function_.java" />
+
+  <!-- hqdm-rdf suppressions -->
+  <suppress checks="ConstantName" files="HQDM.java" />
+  <suppress checks="AbbreviationAsWordInName" files="IRI.java|HQDM.java|RDFS.java|UID.java" />
+</suppressions>

Diff for: README.md

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>uk.gov.gchq.magma-core</groupId>
+    <artifactId>magma-core</artifactId>
+    <version>2.0.0</version>
+  </parent>
+
+  <groupId>uk.gov.gchq.magma-core</groupId>
+  <artifactId>core</artifactId>
+  <version>2.0.0</version>
+
+  <name>core</name>
+
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <maven.compiler.release>17</maven.compiler.release>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>uk.gov.gchq.magma-core</groupId>
+      <artifactId>hqdm</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>uk.gov.gchq.magma-core</groupId>
+      <artifactId>hqdm-rdf</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.jena</groupId>
+      <artifactId>apache-jena-libs</artifactId>
+      <type>pom</type>
+    </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-jdk14</artifactId>
+    </dependency>
+  </dependencies>
+</project>

Diff for: checkstyle-suppressions.xml

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2021 Crown Copyright
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+/**
+ * Magma Core is a lightweight set of Java classes to enable HQDM data objects to be created and
+ * used as RDF Linked Data through Apache Jena.
+ */
+module uk.gov.gchq.magmacore {
+    requires org.apache.jena.arq;
+    requires org.apache.jena.base;
+    requires org.apache.jena.core;
+    requires org.apache.jena.dboe.base;
+    requires org.apache.jena.rdfconnection;
+    requires org.apache.jena.tdb2;
+    requires com.fasterxml.jackson.annotation;
+
+    requires uk.gov.gchq.magmacore.hqdm;
+    requires transitive uk.gov.gchq.magmacore.hqdm.rdf;
+
+    exports uk.gov.gchq.magmacore.service;
+    exports uk.gov.gchq.magmacore.service.transformation;
+    exports uk.gov.gchq.magmacore.exception;
+    exports uk.gov.gchq.magmacore.util;
+}

Diff for: core/pom.xml

@@ -17,15 +17,37 @@
 import java.io.PrintStream;
 import java.util.List;
 
-import uk.gov.gchq.hqdm.iri.HqdmIri;
-import uk.gov.gchq.hqdm.iri.IRI;
-import uk.gov.gchq.hqdm.model.Thing;
+import uk.gov.gchq.magmacore.hqdm.model.Thing;
+import uk.gov.gchq.magmacore.hqdm.rdf.iri.HqdmIri;
+import uk.gov.gchq.magmacore.hqdm.rdf.iri.IRI;
 
 /**
  * Interface defining CRUD operations and generic queries for Magma Core data collections.
  */
 public interface MagmaCoreDatabase {
 
+    /**
+     * Start a transaction in READ mode and which will switch to WRITE if an update is attempted but
+     * only if no intermediate transaction has performed an update.
+     */
+    void begin();
+
+    /**
+     * Commit a transaction - Finish the current transaction and make any changes permanent (if a
+     * "write" transaction).
+     */
+    void commit();
+
+    /**
+     * Abort a transaction - Finish the transaction and undo any changes (if a "write" transaction).
+     */
+    void abort();
+
+    /**
+     * Drop all data from the dataset.
+     */
+    void drop();
+
     /**
      * Get an object from the collection.
      *
@@ -59,35 +81,34 @@ public interface MagmaCoreDatabase {
      * Find object(s) that have a specific object associated with them.
      *
      * @param predicateIri IRI of the predicate being queried.
-     * @param objectIri IRI of the object to match.
-     * @return The object(s).
+     * @param objectIri    IRI of the object to match.
+     * @return The {@link Thing}(s) found.
      */
     List<Thing> findByPredicateIri(IRI predicateIri, IRI objectIri);
 
     /**
      * Find object(s) that have a specific HQDM-defined predication.
      *
      * @param predicateIri IRI of the HQDM relationship type being queried.
-     * @return The object(s).
+     * @return The {@link Thing}(s) found.
      */
     List<Thing> findByPredicateIriOnly(HqdmIri predicateIri);
 
     /**
-     * Find object(s) that have a specific case-sensitive string-value attribute associated with
-     * them.
+     * Find object(s) that have a specific case-sensitive string-value attribute associated with them.
      *
      * @param predicateIri IRI of the predicate being queried.
-     * @param value Case-sensitive string to match.
-     * @return The object(s).
+     * @param value        Case-sensitive string to match.
+     * @return The {@link Thing}(s) found.
      */
     List<Thing> findByPredicateIriAndStringValue(IRI predicateIri, String value);
 
     /**
      * Find object(s) that have a specific string-value attribute associated with them.
      *
      * @param predicateIri IRI of the predicate being queried.
-     * @param value Case-insensitive string to match.
-     * @return The object(s).
+     * @param value        Case-insensitive string to match.
+     * @return The {@link Thing}(s).
      */
     List<Thing> findByPredicateIriAndStringCaseInsensitive(IRI predicateIri, String value);