Merge pull request #10 from WSE-research/348_explanation_annotationOf…

…SpotInstance

348 explanation annotation of spot instance

README.adoc

@@ -20,6 +20,18 @@ This webservice provides some functionalities to compute explanations for some Q
 
 toc::[]
 
+== Supported Annotation Types
+
+The explanation's creation follows a rule-based approach, what means that each explanation for a component is created different depending on the annotationType of its written output.
+
+Therefor not all Annotation types (=components) are supported yet.
+The supported ones are the following:
+
+. AnnotationOfInstance
+. AnnotationOfSpotInstance
+
+You can check the output annotation type for existing components in the component's README at https://github.com/WDAqua/Qanary-question-answering-component .
+
 == Build and Run
 
 === Build
@@ -38,22 +50,21 @@ sparqlEndpoint = http://demos.swe.htwk-leipzig.de:40111/sparql
 ==== *from scratch using Java*
 
 * create a executable -jar-file like so:
-  
- ** `mvn clean install`
+
+** `mvn clean install`
 
 ==== *by using Docker*
 
 . *_locally:_*
-  
-  - build a Docker image with the existing Dockerfile by using the following command inside the projects folder
-  - `docker build . -t qanary-explanation-service`
-  
+
+- build a Docker image with the existing Dockerfile by using the following command inside the projects folder
+- `docker build . -t qanary-explanation-service`
+
 . *_from Dockerhub:_*
 
-  - pull the repository *wseresearch/qanary-explanation-service* with `docker pull wseresearch/qanary-explanation-service:latest`
-
-  - you might replace the tag `latest` with your desired release-tag from `https://hub.docker.com/repository/docker/wseresearch/qanary-explanation-service/tags`
-
+- pull the repository *wseresearch/qanary-explanation-service* with `docker pull wseresearch/qanary-explanation-service:latest`
+
+- you might replace the tag `latest` with your desired release-tag from `https://hub.docker.com/repository/docker/wseresearch/qanary-explanation-service/tags`
 
 === Running the application
 
@@ -69,7 +80,7 @@ sparqlEndpoint = http://demos.swe.htwk-leipzig.de:40111/sparql
 * run the built image with `docker run -p 12345:4000 qanary-explanation-service` with parameters:
 ** *_"p":_* is the optional port mapping if you wish to run the application on a different port on your machine, e.g. in this case the *applications port (default: 4000) is mapped to port 12345*
 
-. *_from Dockerhub:_* 
+. *_from Dockerhub:_*
 
 * run the pulled image with `docker run -p 12345:4000 qanary-explanation-service:latest` with:
 ** your previous selected tag (replace *latest* with *your tag*)
@@ -84,9 +95,11 @@ Currently, there are several endpoints with different tasks, as of the latest ve
 --
 *Path variables:*
 --
+
 --
 ** required: graphURI::String
 --
+
 --
 *Returns:*
 
@@ -117,11 +130,14 @@ WHERE {
 --
 *Path Variables:*
 --
+
 --
 ** required: graphURI::String
 ** optional: componentURI::String
 --
+
 *Returns:*
+
 --
 ** with only the graphURI given: a formatted explanation for the QA-process on the graphURI depending on the following `Accept` header:
 * none: Turtle
@@ -136,9 +152,11 @@ WHERE {
 * `text/turtle`: Turtle
 * other: no response, NOT_ACCEPTABLE (406)
 --
+
 provides two endpoints to either request an explanation for a QA process with a given graphURI or a specific explanation for one componentURI (added as another path variable).
-In both cases, the explanation format depends on the Accept-Header: RDF/XML, JSONLD, or RDF Turtle. 
+In both cases, the explanation format depends on the Accept-Header: RDF/XML, JSONLD, or RDF Turtle.
 If there`s no `Accept` header provided in the request, then the format will be RDF Turtle.
+
 --
 .*Example Return for QA system:*
 [%collapsible]
@@ -232,7 +250,6 @@ explanations:hasExplanationForCreatedData
 ====
 --
 
-
 == Example
 
 . Firstly we start a QA process with the Question "What is the real name of Superman?" and the components
@@ -336,6 +353,7 @@ explanations:hasExplanationForCreatedData
 ====
 
 == SpringDocs & SwaggerUI
+
 Swagger UI is available at http://localhost:40190/swagger-ui/index.html
 
 API Docs are available at http://localhost:40190/api-docs

pom.xml

@@ -10,7 +10,7 @@
     </parent>
     <groupId>com.wse</groupId>
     <artifactId>qanary-explanation-service</artifactId>
-    <version>1.0.2</version>
+    <version>1.1.0</version>
     <name>Qanary explanation service</name>
     <description>Webservice for rule-based explanation of QA-Systems as well as specific components</description>
     <properties>
@@ -33,7 +33,7 @@
         <dependency>
             <groupId>eu.wdaqua.qanary</groupId>
             <artifactId>qa.commons</artifactId>
-            <version>3.5.4</version>
+            <version>[3.5.4,4.0.0]</version>
         </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
@@ -63,6 +63,11 @@
             <version>2.2</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.apache.commons</groupId>
+            <artifactId>commons-lang3</artifactId>
+            <version>3.12.0</version>
+        </dependency>
         <dependency>
             <groupId>org.apache.jena</groupId>
             <artifactId>apache-jena-libs</artifactId>

src/main/java/com/wse/qanaryexplanationservice/controller/ExplanationController.java

@@ -7,15 +7,12 @@
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
-import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.*;
 
 @RestController
 @ControllerAdvice
 public class ExplanationController {
 
-    private static final String DBpediaSpotlight_SPARQL_QUERY = "/queries/explanation_for_dbpediaSpotlight_sparql_query.rq";
-    private static final String GENERAL_EXPLANATION_SPARQL_QUERY = "/queries/general_explanation.rq";
     private final Logger logger = LoggerFactory.getLogger(ExplanationController.class);
 
     @Autowired
@@ -31,30 +28,39 @@ public class ExplanationController {
     @Operation(
             summary = "Get either the explanation for a the whole QA-system on a graphURI"
                     + "or the explanation for a specific component by attaching the componentURI",
-            description = "This endpoint currently offers two sort of requests: "
-                    + "\n 1. Explanation for a QA-system by providing a graphURI and "
-                    + "\n 2. Explanation for a component within a QA-process by providing the graphURI"
-                    + "\n as well as the URI for the component"
-                    + "\n Note: You must at least provide a graphURI to use this endpoint"
+            description = """
+                    This endpoint currently offers two sort of requests:\s
+                     1. Explanation for a QA-system by providing a graphURI and\s
+                     2. Explanation for a component within a QA-process by providing the graphURI
+                     as well as the URI for the component
+                     Note: You must at least provide a graphURI to use this endpoint"""
     )
     public ResponseEntity<?> getExplanations(
-            @PathVariable(required = true) String graphURI,
+            @PathVariable String graphURI,
             @PathVariable(required = false) String componentURI,
             @RequestHeader(value = "accept", required = false) String acceptHeader) throws Exception {
         if (componentURI == null) {
-            String result = explanationService.explainQaSystem(graphURI, GENERAL_EXPLANATION_SPARQL_QUERY, acceptHeader);
+            String result = explanationService.explainQaSystem(graphURI, acceptHeader);
             if (result != null)
                 return new ResponseEntity<>(result, HttpStatus.OK);
             else
                 return new ResponseEntity<>(null, HttpStatus.NOT_ACCEPTABLE);
         } else {
-            String result = this.explanationService.explainSpecificComponent(graphURI, componentURI, GENERAL_EXPLANATION_SPARQL_QUERY, acceptHeader);
+            String result = this.explanationService.explainSpecificComponent(graphURI, componentURI, acceptHeader);
             if (result != null)
                 return new ResponseEntity<>(result, HttpStatus.OK);
             else
-                return new ResponseEntity<>(result, HttpStatus.BAD_REQUEST);
+                return new ResponseEntity<>(null, HttpStatus.BAD_REQUEST);
         }
+    }
 
+    @GetMapping("/explain/{graphURI}/{componentURI}")
+    public ResponseEntity<?> explain(
+            @PathVariable String graphURI,
+            @PathVariable String componentURI,
+            @RequestHeader(value = "accept", required = false) String acceptHeader
+    ) throws Exception {
+        return new ResponseEntity<>(this.explanationService.explainSpecificComponent(graphURI, componentURI, acceptHeader), HttpStatus.OK);
     }
 
 }

src/main/java/com/wse/qanaryexplanationservice/repositories/AbstractRepository.java

@@ -3,6 +3,10 @@
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.wse.qanaryexplanationservice.services.ParameterStringBuilder;
+import org.apache.jena.query.QueryExecution;
+import org.apache.jena.query.ResultSet;
+import org.apache.jena.rdf.model.RDFNode;
+import org.apache.jena.rdfconnection.RDFConnection;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.core.env.Environment;
 import org.springframework.http.MediaType;
@@ -15,6 +19,7 @@
 import java.net.HttpURLConnection;
 import java.net.MalformedURLException;
 import java.net.URL;
+import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Objects;
@@ -27,6 +32,7 @@ public abstract class AbstractRepository implements SparqlRepositoryIF {
     protected WebClient webClient;
 
     protected Environment environment;
+    private final RDFConnection rdfConnection = RDFConnection.connect("http://localhost:8080/sparql");
 
     @Autowired
     protected AbstractRepository(Environment environment) throws MalformedURLException {
@@ -82,4 +88,9 @@ public String fetchQuestion(String questionURI) {
                 .bodyToMono(String.class)
                 .block();
     }
+
+    public ResultSet executeSparqlQueryWithResultSet(String executableQuery) throws RuntimeException {
+        QueryExecution queryExecution = rdfConnection.query(executableQuery);
+        return queryExecution.execSelect();
+    }
 }