Merge branch 'explanation_api' of github.com:WDAqua/Qanary into expla…

…nation_api

qanary_commons/src/main/java/eu/wdaqua/qanary/explainability/QanaryExplanationController.java

@@ -14,7 +14,11 @@
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 
-
+/**
+ * This controller class handles HTTP POST requests for providing explanations for Qanary components.
+ * By default, it uses a {@link QanaryExplanation} service to generate explanations based on the provided data.
+ * In case of a specific explanation that should be provided by a component, it should overwrite this class by a specific implementation.
+ */
 @Controller
 public class QanaryExplanationController {
 

qanary_commons/src/main/java/eu/wdaqua/qanary/explainability/QanaryExplanationData.java

@@ -2,6 +2,11 @@
 
 import java.util.Map;
 
+/**
+ * This class represents the data structure used to store information related to a Qanary explanation request.
+ * It contains details about the Qanary process graph, the question ID, the server host, the component being 
+ * explained, and any explanations generated.
+ */
 public class QanaryExplanationData {
 
     private String graph;
@@ -10,52 +15,112 @@ public class QanaryExplanationData {
     private String component;
     private Map<String,String> explanations;
 
+    /**
+     * Default constructor for creating an empty instance of {@link QanaryExplanationData}.
+     */
     public QanaryExplanationData() {
 
     }
 
+    /**
+     * Constructor for creating an instance of {@link QanaryExplanationData} with the specified Qanary process graph, question ID, and server host.
+     *
+     * @param graph      the graph representing the QA process
+     * @param questionId the identifier for the question being explained
+     * @param serverHost the host of the server processing the explanation request
+     */
     public QanaryExplanationData(String graph, String questionId, String serverHost) {
         this.graph = graph;
         this.questionId = questionId;
         this.serverHost = serverHost;
     }
 
+    /**
+     * Gets the component being explained.
+     *
+     * @return the component being explained
+     */
     public String getComponent() {
         return component;
     }
 
-    public void setExplanations(Map<String, String> explanations) {
-        this.explanations = explanations;
+    /**
+     * Sets the component being explained.
+     *
+     * @param component the component to set
+     */
+    public void setComponent(String component) {
+        this.component = component;
     }
 
+    /**
+     * Gets the explanations generated for the component.
+     *
+     * @return a map of explanations, where keys are explanation types and values are explanations
+     */
     public Map<String, String> getExplanations() {
         return explanations;
     }
 
+    /**
+     * Sets the explanations generated for the component.
+     *
+     * @param explanations a map of explanations, where keys are explanation types and values are explanations
+     */
+    public void setExplanations(Map<String, String> explanations) {
+        this.explanations = explanations;
+    }
+
+    /**
+     * Gets the graph representing the Qanary process.
+     *
+     * @return the graph representing the Qanary process 
+     */
     public String getGraph() {
         return graph;
     }
 
+    /**
+     * Sets the graph representing the QA process.
+     *
+     * @param graph the graph to set
+     */
+    public void setGraph(String graph) {
+        this.graph = graph;
+    }
+
+    /**
+     * Gets the identifier for the question being explained.
+     *
+     * @return the question ID
+     */
     public String getQuestionId() {
         return questionId;
     }
 
+    /**
+     * Sets the identifier for the question being explained.
+     *
+     * @param questionId the question ID to set
+     */
     public void setQuestionId(String questionId) {
         this.questionId = questionId;
     }
 
-    public void setComponent(String component) {
-        this.component = component;
-    }
-
-    public void setGraph(String graph) {
-        this.graph = graph;
-    }
-
+    /**
+     * Gets the host of the server processing the explanation request.
+     *
+     * @return the server host
+     */
     public String getServerHost() {
         return serverHost;
     }
 
+    /**
+     * Sets the host of the server processing the explanation request.
+     *
+     * @param serverHost the server host to set
+     */
     public void setServerHost(String serverHost) {
         this.serverHost = serverHost;
     }

qanary_commons/src/main/resources/queries/select_all_graphs_with_questionId.rq

@@ -1,3 +1,5 @@
+# This SPARQL query is designed to identify the named graph(s) within a triplestore where a specific question, identified by its unique ID, is associated with the current question being processed in a Qanary pipeline.
+# ?componentAnnotations should be replaced in the source code
 PREFIX oa: <http://www.w3.org/ns/openannotation/core/>
 PREFIX qa: <http://www.wdaqua.eu/qa#>
 PREFIX owl: <http://www.w3.org/2002/07/owl#>
@@ -8,4 +10,4 @@ WHERE {
 		?questionId owl:sameAs <urn:qanary:currentQuestion> .
     	?componentAnnotations
 	}
-}
+}

qanary_commons/src/main/resources/queries/select_all_used_components.rq

@@ -1,8 +1,10 @@
+# This SPARQL query is designed to retrieve a distinct list of components that have been used to create annotations within a specific named graph (Qanary process graph) in a triplestore. 
+# These components are part of a Qanary pipeline.
 PREFIX oa: <http://www.w3.org/ns/openannotation/core/>
 PREFIX qa: <http://www.wdaqua.eu/qa#>
 
 SELECT DISTINCT ?component
 FROM ?graph
 WHERE {
-?annotationID oa:annotatedBy ?component .
-}
+  ?annotationID oa:annotatedBy ?component .
+}

qanary_component-template/src/main/java/eu/wdaqua/qanary/component/QanaryComponent.java

@@ -66,6 +66,18 @@ public String getQuestionRawData() throws Exception {
         return this.getQanaryQuestion().getTextualRepresentation();
     }
 
+    /**
+     * Generates an explanation for the component regarding the {@link QanaryExplanationData} object.
+     * This method sets the component name in the provided data, logs the explanation request,
+     * and then sends the data to a web service for processing. The explanation is returned as a string.
+     *
+     * @param data the {@link QanaryExplanationData} object containing details needed for generating the explanation.
+     *             This includes the graph, question ID, server host, and any other relevant information.
+     * @return a {@link String} containing the explanation generated by the web service.
+     * @throws IOException if an I/O error occurs during communication with the web service.
+     * @throws URISyntaxException if the URI of the web service is malformed.
+     * @throws SparqlQueryFailed if the SPARQL query related to the explanation fails.
+     */
     @Override
     public String explain(QanaryExplanationData data) throws IOException, URISyntaxException, SparqlQueryFailed {
         data.setComponent(this.getApplicationName());

qanary_pipeline-template/src/main/java/eu/wdaqua/qanary/QanaryPipeline.java

@@ -167,6 +167,9 @@ public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion, @
         );
     }
 
+    /**
+     * returns an explanation for the post-hoc behavior of a specific execution
+     */
     @Override
     public String explain(QanaryExplanationData qanaryExplanationData) throws IOException, URISyntaxException, SparqlQueryFailed {
         // Fetch subcomponent explanations == All annotations made on the original KG

qanary_pipeline-template/src/main/java/eu/wdaqua/qanary/QanaryPipelineComponent.java

@@ -162,6 +162,9 @@ private String getQuestionIdWithQuery(String graphUri, QanaryTripleStoreConnecto
         }
     }
 
+    /**
+     * returns an (post-hoc) explanation for a specific execution run
+     */
     @Override
     public String explain(QanaryExplanationData data) throws IOException, URISyntaxException, SparqlQueryFailed {
         logger.info("Explaining component: {}", this.getApplicationName());