Merge pull request #257 from com-pas/develop

New release

.gitignore

@@ -1,69 +1,47 @@
-# SPDX-FileCopyrightText: 2021 Alliander N.V.
+# SPDX-FileCopyrightText: 2022 Alliander N.V.
 #
 # SPDX-License-Identifier: Apache-2.0
 
-# Compiled class file
-*.class
+#Maven
+/.mvn/wrapper/maven-wrapper.jar
+target/
+pom.xml.tag
+pom.xml.releaseBackup
+pom.xml.versionsBackup
+release.properties
 
-# Log file
-*.log
-
-# BlueJ files
-*.ctxt
-
-# Mobile Tools for Java (J2ME)
-.mtj.tmp/
-
-# Package Files #
-*.jar
-*.war
-*.nar
-*.ear
-*.zip
-*.tar.gz
-*.rar
-
-# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
-hs_err_pid*
-
-# Alliander specific
-oc
+# Eclipse
+.project
+.classpath
+.settings/
+bin/
 
-# Gradle stuff
-.gradle
-**/build/
-!src/**/build/
+# IntelliJ
+.idea
+*.ipr
+*.iml
+*.iws
 
-# Ignore Gradle GUI config
-gradle-app.setting
+# NetBeans
+nb-configuration.xml
 
-# Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
-!gradle-wrapper.jar
+# Visual Studio Code
+.vscode
+.factorypath
 
-# Cache of project
-.gradletasknamecache
+# OSX
+.DS_Store
 
-# IDE specific
-.vscode/
-.idea
+# Vim
+*.swp
+*.swo
 
-# General
-.DS_Store
-target
-*.iml
-.settings
-.project
-.classpath
-out
-lib
-bin
-.java-version
+# patch
 *.orig
 *.rej
-*.swp
-*.swo
-.cache
-build
+
+# Local environment
+.env
 
 # Quarkus specific
-quarkus.log
+quarkus.log

DEVELOPMENT.md

@@ -0,0 +1,114 @@
+<!--
+SPDX-FileCopyrightText: 2021 Alliander N.V.
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Development for CIM Mapping
+
+This project uses Java 17 and Quarkus to build and run the application. The project is split into multi modules.
+The app module will use Quarkus to expose the services as REST XML Endpoints. The service module contains all
+the logic to convert CIM Data into IEC 61850 XML. This module uses no Quarkus dependencies, but mainly standard java
+dependencies and PowSyBl/MapStruct dependencies to do the conversion. This way the service module can also be used in
+other environment as Java library, for instance a Spring project.
+
+## Building the application
+
+You can use Maven to build the application and see if all tests are working using:
+
+```shell script
+./mvnw clean verify
+```
+
+This should normally be enough to also run the application, but there were cases that we need to build using:
+
+```shell script
+./mvnw clean install
+```
+
+This to make the local modules available for the app module to run the application.
+
+## Running the application locally in dev mode
+
+You can run your application in dev mode that enables live coding using:
+
+```shell script
+./mvnw package io.quarkus:quarkus-maven-plugin::dev
+```
+
+### Application depends on a running KeyCloak instance for dev mode
+
+A KeyCloak instance needs to be running on port 8089 by default in dev mode. If a custom KeyCloak instance is used see
+[Security](README.md#security) for more details.
+
+There is a preconfigured Demo KeyCloak instance available for CoMPAS in the
+[CoMPAS Deployment Repository](https://github.com/com-pas/compas-deployment). This repository can be cloned and
+used to execute the following commands to create a local Docker Image with the CoMPAS Demo configuration.
+
+```shell
+cd <CoMPAS Deployment Repository Directory>/compas/keycloak
+docker build -t compas_keycloak . 
+```
+
+A Docker Image `compas_keycloak` is created that can be started using the following command
+
+```shell
+docker run --rm --name compas_keycloak \
+   -p 8089:8080 
+   -d compas_keycloak:latest
+```
+
+There are now 3 users available to be used, `scl-data-editor`, `scl-data-reader`, `scd-reader`. See
+[CoMPAS Deployment Repository](https://github.com/com-pas/compas-deployment) for more information about the users.
+
+## Testing the application
+
+The application is tested with unit and integration tests, but you can also manually test the application using for
+instance Postman. And there is also a way to test this service with the CoMPAS OpenSCD Frontend application.
+
+### Postman
+
+To manually test the application there is a Postman collection in the directory `postman` that can be imported
+and used to execute REST XML Calls.
+
+To make the call work we also need to import an environment and authorisation collection. These files can be found
+in [CoMPAS Deployment Repository](https://github.com/com-pas/compas-deployment) in the directory `postman`
+(`auth.collection.json` and `local.environment.json`).
+
+In the authorisation collection there are called for the 3 users known within the Demo KeyCloak instance.
+If one of these calls are executed there is a variable `bearer` filled.
+
+Now one of the CIM Mapping calls can be executed, the variable `bearer` is added to the header of the request.
+After the call is executed the result should be shown in Postman.
+
+### CoMPAS OpenSCD Frontend application
+
+To test the CIM Mapping with the CoMPAS OpenSCD application just run the application in dev mode, including the
+KeyCloak instance. For further instruction how to start the CoMPAS OpenSCD application and use this locally see
+the file `DEVELOPMENT.md` in [CoMPAS OpenSCD application](https://github.com/com-pas/compas-open-scd).
+
+## Docker Images
+
+### Creating a Docker image with native executable
+
+The releases created in the repository will create a docker image with a native executable. If you're running a Linux
+system it's possible to create and run the executable locally. You can create a Docker image with native executable
+using:
+
+```shell script
+./mvnw package -Pnative-image
+```
+
+You can then execute your native executable with: `./app/target/app-local-SNAPSHOT-runner`
+
+### Creating a Docker image with JVM executable
+
+There is also a profile to create a Docker Image which runs the application using a JVM. You can create a Docker Image
+with JVM executable using:
+
+```shell script
+./mvnw package -Pjvm-image
+```
+
+The JVM Image can also (temporary) be created by the release action if there are problems creating or running the
+native executable.

README.md

@@ -10,64 +10,20 @@ SPDX-License-Identifier: Apache-2.0
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5925/badge)](https://bestpractices.coreinfrastructure.org/projects/5925)
 [![Slack](https://raw.githubusercontent.com/com-pas/compas-architecture/master/public/LFEnergy-slack.svg)](http://lfenergy.slack.com/)
 
-# compas-cim-mapping
+# CoMPAS CIM Mapping
 
 ## Mapping between IEC CIM and IEC 61850
 
 The Mapping between IEC CIM and IEC 61850 is described in [Mapping](MAPPING.md).
 
-## Running the application in dev mode
+## Development
 
-You can run your application in dev mode that enables live coding using:
-
-```shell script
-./mvnw package io.quarkus:quarkus-maven-plugin::dev
-```
-
-> **_NOTE:_**  Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8080/q/dev/.
-
-## Packaging and running the application
-
-The application can be packaged using:
-
-```shell script
-./mvnw package
-```
-
-It produces the `quarkus-run.jar` file in the `app/target/quarkus-app/` directory. Be aware that it’s not an _über-jar_
-as the dependencies are copied into the `app/target/quarkus-app/lib/` directory.
-
-If you want to build an _über-jar_, execute the following command:
-
-```shell script
-./mvnw package -Dquarkus.package.type=uber-jar
-```
-
-The application is now runnable using `java -jar app/target/quarkus-app/quarkus-run.jar`.
-
-## Creating a native executable
-
-You can create a native executable using:
-
-```shell script
-./mvnw package -Pnative
-```
-
-Or, if you don't have GraalVM installed, you can run the native executable build in a container using:
-
-```shell script
-./mvnw package -Pnative -Dquarkus.native.container-build=true
-```
-
-You can then execute your native executable with: `./app/target/code-with-quarkus-local-SNAPSHOT-runner`
-
-If you want to learn more about building native executables, please consult https://quarkus.io/guides/maven-tooling.html
-.
+Information about how to run and develop for this project check [Development](DEVELOPMENT.md).
 
 ## Environment variables
 
-Below environment variable(s) can be used to configure which claims are used to fill user information, for instance Who
-in History Record.
+Below environment variable(s) can be used to configure which claim is used to fill user information, for instance the
+Who Attribute in the History Record.
 
 | Environment variable             | Java Property                  | Description                                   | Example          |
 | -------------------------------- | ------------------------------ | --------------------------------------------- | ---------------- |

app/src/main/docker/Dockerfile.jvm

@@ -23,7 +23,7 @@
 ###
 FROM registry.access.redhat.com/ubi8/ubi-minimal:8.6 
 
-ARG JAVA_PACKAGE=java-11-openjdk-headless
+ARG JAVA_PACKAGE=java-17-openjdk-headless
 ARG RUN_JAVA_VERSION=1.3.8
 ENV LANG='en_US.UTF-8' LANGUAGE='en_US:en'
 # Install java and the run-java script

pom.xml

@@ -25,7 +25,7 @@ SPDX-License-Identifier: Apache-2.0
 
         <compas.core.version>0.9.1</compas.core.version>
 
-        <quarkus.platform.version>2.10.2.Final</quarkus.platform.version>
+        <quarkus.platform.version>2.11.2.Final</quarkus.platform.version>
         <microprofile-openapi-api.version>3.0</microprofile-openapi-api.version>
         <slf4j.version>1.7.36</slf4j.version>
         <powsybl.version>4.9.2</powsybl.version>