Merge pull request #42 from com-pas/develop

New release

README.md

@@ -30,13 +30,61 @@ described in the URL above that the URL can be overwritten locally with an HTTPS
 Check the [Development](DEVELOPMENT.md) page for more detail information how to work with this repository, because of
 the mixture with RiseClipse.
 
+## Custom OCL Files
+
+There is a way to add custom OCL Files to the validator, for instance to force company specific rules. In the Docker
+Image there is a volume `/data/ocl` which can be used to add these files, see our compas-deployment project for an
+example how to.
+
+In this directory, you can use subdirectories like `SemanticConstraints` as RiseClipse is doing. And there is a special
+filter that when you create a directory `FileSpecifics`. In this directory you can create for instance a directory `CID`
+to put constraints specific for an SCL File Type. Known types are `SSD`, `IID`, `ICD`, `SCD`, `CID`, `SED`, `ISD`,
+`STD`.
+
+For instance,
+
+```
+data
+└── ocl
+    ├── FileSpecifics
+    │         └── CID
+    │             └── Busbar.ocl
+    └── SemanticConstraints
+        └── Busbar.ocl
+```
+
+If you are using the validator are library (using JAR Files) there is a property to configure the directory, see
+[Common Environment variables](#common-environment-variables)
+
+## NSDoc Files
+
+Because NSDoc File can't be distributed in an OpenSource Project these need to be added during deployment. In the Docker
+Image there is a volume `/data/nsdoc` which can be used to add these files, see our compas-deployment project for an
+example how to.
+
+Only direct files found in this directory will be processed. Invalid NSDoc Files will be ignored. A directory can look
+like this for instance,
+
+```
+data
+└── nsdoc
+    ├── IEC_61850-7-2_2007B3-en.nsdoc
+    ├── IEC_61850-7-3_2007B3-en.nsdoc
+    └── IEC_61850-7-4_2007B3-en.nsdoc
+    
+```
+
+If you are using the validator are library (using JAR Files) there is a property to configure the directory, see
+[Common Environment variables](#common-environment-variables)
+
 ## Common Environment variables
 
 Below environment variable(s) can be used to configure the validator.
 
-| Environment variable                  | Java Property                         | Description                                       | Example   |
-|---------------------------------------|---------------------------------------|---------------------------------------------------|-----------|
-| COMPAS_VALIDATOR_OCL_CUSTOM_DIRECTORY | compas.validator.ocl.custom.directory | Reference to a directory to load custom OCL Files | /data/ocl |
+| Environment variable                  | Java Property                         | Description                                                 | Example     |
+|---------------------------------------|---------------------------------------|-------------------------------------------------------------|-------------|
+| COMPAS_VALIDATOR_OCL_CUSTOM_DIRECTORY | compas.validator.ocl.custom.directory | Reference to a directory to load custom OCL Files           | /data/ocl   |
+| COMPAS_VALIDATOR_NSDOC_DIRECTORY      | compas.validator.nsdoc.directory      | Reference to a directory where the NSDoc Files can be found | /data/nsdoc | 
 
 ## Security
 

app/pom.xml

@@ -22,11 +22,6 @@ SPDX-License-Identifier: Apache-2.0
         <quarkus.container-image.name>compas-scl-validator</quarkus.container-image.name>
     </properties>
 
-    <dependencyManagement>
-        <dependencies>
-        </dependencies>
-    </dependencyManagement>
-
     <dependencies>
         <dependency>
             <groupId>org.lfenergy.compas.scl.validator</groupId>

app/src/main/docker/Dockerfile.jvm

@@ -49,10 +49,12 @@ COPY --chown=1001 target/quarkus-app/app/ /deployments/app/
 COPY --chown=1001 target/quarkus-app/quarkus/ /deployments/quarkus/
 
 RUN mkdir -p /data/ocl \
+    && mkdir -p /data/nsdoc \
     && mkdir -p /data/temp \
     && chown -R 1001 /data \
     && chmod -R "g+rwX" /data
 VOLUME /data/ocl
+VOLUME /data/nsdoc
 
 EXPOSE 8080
 USER 1001

app/src/main/docker/Dockerfile.native

@@ -22,10 +22,12 @@ RUN chown 1001 /work \
 COPY --chown=1001:root target/*-runner /work/application
 
 RUN mkdir -p /data/ocl \
+    && mkdir -p /data/nsdoc \
     && mkdir -p /data/temp \
     && chown -R 1001 /data \
     && chmod -R "g+rwX" /data
 VOLUME /data/ocl
+VOLUME /data/nsdoc
 
 EXPOSE 8080
 USER 1001

app/src/main/java/org/lfenergy/compas/scl/validator/rest/CompasSclValidatorConfiguration.java

@@ -3,9 +3,11 @@
 // SPDX-License-Identifier: Apache-2.0
 package org.lfenergy.compas.scl.validator.rest;
 
+import io.quarkus.runtime.Startup;
 import org.lfenergy.compas.core.commons.ElementConverter;
 import org.lfenergy.compas.scl.validator.collector.CompasOclFileCollector;
 import org.lfenergy.compas.scl.validator.collector.OclFileCollector;
+import org.lfenergy.compas.scl.validator.common.NsdocFinder;
 import org.lfenergy.compas.scl.validator.impl.SclRiseClipseValidator;
 
 import javax.enterprise.context.ApplicationScoped;
@@ -33,4 +35,11 @@ public SclRiseClipseValidator createSclRiseClipseValidator(OclFileCollector oclF
                                                                ValidatorProperties properties) {
         return new SclRiseClipseValidator(oclFileCollector, properties.tempDirectory());
     }
+
+    @Produces
+    @Startup
+    @ApplicationScoped
+    public NsdocFinder createNsdocFinder(ValidatorProperties properties) {
+        return new NsdocFinder(properties.nsdocDirectory());
+    }
 }

app/src/main/java/org/lfenergy/compas/scl/validator/rest/SclResourceConstants.java

@@ -9,4 +9,5 @@ public final class SclResourceConstants {
     }
 
     public static final String TYPE_PATH_PARAM = "type";
+    public static final String ID_PARAM = "id";
 }

app/src/main/java/org/lfenergy/compas/scl/validator/rest/ValidatorProperties.java

@@ -13,6 +13,9 @@ public interface ValidatorProperties {
     @WithName("ocl.custom.directory")
     String oclCustomDirectory();
 
+    @WithName("nsdoc.directory")
+    String nsdocDirectory();
+
     @WithName("temp.directory")
     Path tempDirectory();
 }

app/src/main/java/org/lfenergy/compas/scl/validator/rest/exception/NsdocNotFoundExceptionHandler.java

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2021 Alliander N.V.
+//
+// SPDX-License-Identifier: Apache-2.0
+package org.lfenergy.compas.scl.validator.rest.exception;
+
+import org.lfenergy.compas.core.jaxrs.model.ErrorResponse;
+import org.lfenergy.compas.scl.validator.exception.NsdocFileNotFoundException;
+
+import javax.ws.rs.core.Response;
+import javax.ws.rs.ext.ExceptionMapper;
+import javax.ws.rs.ext.Provider;
+
+@Provider
+public class NsdocNotFoundExceptionHandler implements ExceptionMapper<NsdocFileNotFoundException> {
+    @Override
+    public Response toResponse(NsdocFileNotFoundException exception) {
+        var response = new ErrorResponse();
+        response.addErrorMessage(exception.getErrorCode(), exception.getMessage());
+        return Response.status(Response.Status.NOT_FOUND).entity(response).build();
+    }
+}

app/src/main/java/org/lfenergy/compas/scl/validator/rest/v1/NsdocResource.java

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2022 Alliander N.V.
+//
+// SPDX-License-Identifier: Apache-2.0
+package org.lfenergy.compas.scl.validator.rest.v1;
+
+import io.quarkus.security.Authenticated;
+import org.lfenergy.compas.scl.validator.rest.v1.model.NsdocListResponse;
+import org.lfenergy.compas.scl.validator.service.NsdocService;
+
+import javax.enterprise.context.RequestScoped;
+import javax.ws.rs.*;
+import javax.ws.rs.core.MediaType;
+import java.util.UUID;
+
+import static org.lfenergy.compas.scl.validator.rest.SclResourceConstants.ID_PARAM;
+
+@Authenticated
+@RequestScoped
+@Path("/nsdoc/v1")
+public class NsdocResource {
+    private final NsdocService nsdocService;
+
+    public NsdocResource(NsdocService nsdocService) {
+        this.nsdocService = nsdocService;
+    }
+
+    @GET
+    @Consumes(MediaType.APPLICATION_XML)
+    @Produces(MediaType.APPLICATION_XML)
+    public NsdocListResponse list() {
+        NsdocListResponse response = new NsdocListResponse();
+        response.setNsdocFiles(nsdocService.list());
+        return response;
+    }
+
+    @GET
+    @Path("{" + ID_PARAM + "}")
+    @Consumes(MediaType.APPLICATION_XML)
+    @Produces(MediaType.APPLICATION_XML)
+    public String get(@PathParam(ID_PARAM) UUID id) {
+        return nsdocService.get(id);
+    }
+}

app/src/main/java/org/lfenergy/compas/scl/validator/rest/v1/model/NsdocListResponse.java

@@ -0,0 +1,32 @@
+// SPDX-FileCopyrightText: 2022 Alliander N.V.
+//
+// SPDX-License-Identifier: Apache-2.0
+package org.lfenergy.compas.scl.validator.rest.v1.model;
+
+import org.eclipse.microprofile.openapi.annotations.media.Schema;
+import org.lfenergy.compas.scl.validator.model.NsdocFile;
+
+import javax.xml.bind.annotation.XmlAccessType;
+import javax.xml.bind.annotation.XmlAccessorType;
+import javax.xml.bind.annotation.XmlElement;
+import javax.xml.bind.annotation.XmlRootElement;
+import java.util.Collection;
+
+import static org.lfenergy.compas.scl.validator.SclValidatorConstants.SCL_VALIDATOR_SERVICE_V1_NS_URI;
+
+@Schema(description = "The response with the list of known NSDoc Files.")
+@XmlRootElement(name = "NsdocListResponse", namespace = SCL_VALIDATOR_SERVICE_V1_NS_URI)
+@XmlAccessorType(XmlAccessType.FIELD)
+public class NsdocListResponse {
+    @Schema(description = "The list of known NSDoc Files")
+    @XmlElement(name = "NsdocFile", namespace = SCL_VALIDATOR_SERVICE_V1_NS_URI)
+    private Collection<NsdocFile> nsdocFiles;
+
+    public Collection<NsdocFile> getNsdocFiles() {
+        return nsdocFiles;
+    }
+
+    public void setNsdocFiles(Collection<NsdocFile> nsdocFiles) {
+        this.nsdocFiles = nsdocFiles;
+    }
+}

app/src/main/java/org/lfenergy/compas/scl/validator/rest/v1/model/SclValidateRequest.java

@@ -14,11 +14,11 @@
 
 import static org.lfenergy.compas.scl.validator.SclValidatorConstants.SCL_VALIDATOR_SERVICE_V1_NS_URI;
 
-@Schema(description = "")
+@Schema(description = "The Validation Request retrieved")
 @XmlRootElement(name = "SclValidateRequest", namespace = SCL_VALIDATOR_SERVICE_V1_NS_URI)
 @XmlAccessorType(XmlAccessType.FIELD)
 public class SclValidateRequest {
-    @Schema(description = "")
+    @Schema(description = "The SCL Data to be validated")
     @NotBlank
     @XmlElement(name = "SclData", namespace = SCL_VALIDATOR_SERVICE_V1_NS_URI)
     protected String sclData;

app/src/main/java/org/lfenergy/compas/scl/validator/rest/v1/model/SclValidateResponse.java

@@ -14,11 +14,11 @@
 
 import static org.lfenergy.compas.scl.validator.SclValidatorConstants.SCL_VALIDATOR_SERVICE_V1_NS_URI;
 
-@Schema(description = "")
+@Schema(description = "The Validation Response returned")
 @XmlRootElement(name = "SclValidateResponse", namespace = SCL_VALIDATOR_SERVICE_V1_NS_URI)
 @XmlAccessorType(XmlAccessType.FIELD)
 public class SclValidateResponse {
-    @Schema(description = "")
+    @Schema(description = "The list with Validation Errors, if any.")
     @XmlElement(name = "ValidationErrors", namespace = SCL_VALIDATOR_SERVICE_V1_NS_URI)
     protected List<ValidationError> validationErrorList;
 

app/src/main/resources/application.properties

@@ -3,6 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 compas.validator.ocl.custom.directory = /data/ocl
+compas.validator.nsdoc.directory      = /data/nsdoc
 compas.validator.temp.directory       = /data/temp
 
 quarkus.http.cors                 = false
@@ -14,6 +15,7 @@ quarkus.log.category."org.lfenergy.compas.scl.validator".level = INFO
 
 # Dev Profile overrides.
 %dev.compas.validator.ocl.custom.directory = ./src/test/data/ocl
+%dev.compas.validator.nsdoc.directory      = ./src/test/data/nsdoc
 %dev.compas.validator.temp.directory       = ./target/data/temp
 
 %dev.quarkus.http.port      = 9093
@@ -24,6 +26,7 @@ quarkus.log.category."org.lfenergy.compas.scl.validator".level = INFO
 
 # Test Profile overrides.
 %test.compas.validator.ocl.custom.directory = ./src/test/data/ocl
+%test.compas.validator.nsdoc.directory      = ./src/test/data/nsdoc
 %test.compas.validator.temp.directory       = ./target/data/temp
 
 %test.quarkus.log.category."org.lfenergy.compas.scl.validator.collector.CompasOclFileCollector".level = WARN
@@ -43,5 +46,8 @@ quarkus.http.auth.permission.allow-quarkus-services.policy=permit
 %dev.quarkus.http.auth.permission.develop-quarkus-services.paths=/compas-scl-validator/q/swagger-ui/*,/compas-scl-validator/index.html
 %dev.quarkus.http.auth.permission.develop-quarkus-services.policy=permit
 
-quarkus.http.auth.permission.common.paths=/compas-scl-validator/validate/v1/*
-quarkus.http.auth.permission.common.policy=authenticated
+quarkus.http.auth.permission.validate.paths=/compas-scl-validator/validate/v1/*
+quarkus.http.auth.permission.validate.policy=authenticated
+
+quarkus.http.auth.permission.nsdoc.paths=/compas-scl-validator/nsdoc/v1/*
+quarkus.http.auth.permission.nsdoc.policy=authenticated

app/src/test/data/nsdoc/invalid.nsdoc

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- SPDX-FileCopyrightText: 2022 Alliander -->
+<!-- -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+<NSDoc>
+</NSDoc>

app/src/test/data/nsdoc/testFile73.nsdoc

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- SPDX-FileCopyrightText: 2022 Alliander -->
+<!-- -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+<NSDoc id="IEC 61850-7-3"
+       version="2007"
+       revision="B"
+       release="3"
+       lang="en">
+   <Doc id="IEC61850_7_3.CDCControl::ENC.q.desc"><![CDATA[Some DA description]]></Doc>
+   <Doc id="IEC61850_7_3.AnalogueValue::AnalogueValue.i.desc"><![CDATA[Some i description]]></Doc>
+</NSDoc>

app/src/test/data/nsdoc/testFile74.nsdoc

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- SPDX-FileCopyrightText: 2022 Alliander -->
+<!-- -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+<NSDoc id="IEC 61850-7-4"
+       version="2007"
+       revision="B"
+       release="3"
+       lang="en">
+   <Doc id="IEC61850_7_4.LNGroupL::LLN0.cl.title"><![CDATA[Some LN title]]></Doc>
+   <Doc id="IEC61850_7_4.LNGroupL::LLN0.Beh.desc"><![CDATA[Some DO description]]></Doc>
+   <Doc id="IEC61850_7_4.AbstractLNsCommon::DomainLN.Beh.desc"><![CDATA[Some DomainLN Descriptions]]></Doc>
+</NSDoc>

app/src/test/java/org/lfenergy/compas/scl/validator/rest/exception/NsdocNotFoundExceptionHandlerTest.java

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2021 Alliander N.V.
+//
+// SPDX-License-Identifier: Apache-2.0
+package org.lfenergy.compas.scl.validator.rest.exception;
+
+import org.junit.jupiter.api.Test;
+import org.lfenergy.compas.core.jaxrs.model.ErrorResponse;
+import org.lfenergy.compas.scl.validator.exception.NsdocFileNotFoundException;
+
+import static javax.ws.rs.core.Response.Status.NOT_FOUND;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+class NsdocNotFoundExceptionHandlerTest {
+    @Test
+    void toResponse_WhenCalledWithException_ThenNotFoundReturnedWithBody() {
+        var exception = new NsdocFileNotFoundException("Some message that will only be logged");
+        var handler = new NsdocNotFoundExceptionHandler();
+
+        var result = handler.toResponse(exception);
+        assertEquals(NOT_FOUND.getStatusCode(), result.getStatus());
+        var errorMessage = ((ErrorResponse) result.getEntity()).getErrorMessages().get(0);
+        assertEquals(exception.getErrorCode(), errorMessage.getCode());
+        assertEquals(exception.getMessage(), errorMessage.getMessage());
+        assertNull(errorMessage.getProperty());
+    }
+}