Added documentation

qanary_commons/src/main/java/eu/wdaqua/qanary/commons/triplestoreconnectors/QanaryTripleStoreProxy.java

@@ -4,30 +4,49 @@
 import org.apache.jena.query.ResultSet;
 import org.apache.jena.rdf.model.Model;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.beans.factory.annotation.Value;
 
 import java.net.URI;
 import java.net.URISyntaxException;
 
+/**
+ * This QanaryTripleStoreConnector acts as a proxy for the QanaryPipeline, mainly for the use-case "pipeline as component".
+ * It can handle requests for two endpoints and therefore, it can recursively send requests to higher-level pipelines.
+ * In the case of "pipeline as pipeline" the internalConnector will remain unassigned and null.
+ */
 public class QanaryTripleStoreProxy extends QanaryTripleStoreConnector {
 
-    @Autowired
-    private QanaryTripleStoreConnector externalConnector; // Injects external connector
+    @Autowired // Injects external connector
+    private QanaryTripleStoreConnector externalConnector;
 
-    private QanaryTripleStoreConnectorQanaryInternal internalConnector; // set if necessary
-    @Value("#{new Boolean('${pipeline.as.component}')}")
-    private boolean isPipelineComponent;
+    private QanaryTripleStoreConnectorQanaryInternal internalConnector;
     private URI internEndpointGraph;
     private URI externalEndpointGraph;
 
+    /**
+     * Sets the internalConnector if the pipeline acts as component
+     *
+     * @param endpoint        Endpoint to higher-level (=parent) pipeline
+     * @param applicationName This components' application name
+     * @throws URISyntaxException
+     */
     public void setInternalConnector(URI endpoint, String applicationName) throws URISyntaxException {
         internalConnector = new QanaryTripleStoreConnectorQanaryInternal(endpoint, applicationName);
     }
 
+    /**
+     * Used only for "pipeline as component", to store the context
+     *
+     * @param externalEndpointGraph graph of this pipelines' QA process
+     */
     public void setExternalEndpointGraph(URI externalEndpointGraph) {
         this.externalEndpointGraph = externalEndpointGraph;
     }
 
+    /**
+     * Used only for "pipeline as component", to store the context
+     *
+     * @param internEndpointGraph graph of the higher-level pipeline QA process
+     */
     public void setInternEndpointGraph(URI internEndpointGraph) {
         this.internEndpointGraph = internEndpointGraph;
     }
@@ -40,7 +59,7 @@ public void connect() {
     @Override
     public ResultSet select(String sparql) throws SparqlQueryFailed, URISyntaxException {
         ResultSet results = externalConnector.select(sparql);
-        if (isPipelineComponent && !results.hasNext()) {
+        if (internalConnector != null && !results.hasNext()) {
             getLogger().info("Requesting parent endpoint and graph");
             sparql = externalEndpointGraph == null ? sparql : sparql.replace(externalEndpointGraph.toASCIIString(), internEndpointGraph.toASCIIString());
             results = internalConnector.select(sparql);
@@ -63,6 +82,12 @@ public void update(String sparql) throws SparqlQueryFailed {
         externalConnector.update(sparql);
     }
 
+    /**
+     * Executes a UPDATE on the internalConnector
+     *
+     * @param sparql SPARQL query
+     * @throws SparqlQueryFailed
+     */
     public void updateInternal(String sparql) throws SparqlQueryFailed {
         internalConnector.update(sparql);
     }

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

@@ -16,6 +16,7 @@
 @Component
 @Configuration
 @EnableCaching
+// Used by default, but excluded when a pipeline doesn't act as component
 @ConditionalOnProperty(name = "pipeline.as.component", matchIfMissing = true, havingValue = "true")
 public class QanaryComponentConfiguration {
     private final Logger logger = LoggerFactory.getLogger(QanaryComponentConfiguration.class);

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

@@ -27,6 +27,7 @@
  * provides access to the components definition in different RDF formats
  */
 @Controller
+// Used by default, but excluded when a pipeline doesn't act as component
 @ConditionalOnProperty(name = "pipeline.as.component", matchIfMissing = true, havingValue = "true")
 public class QanaryComponentDescriptionController {
 

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

@@ -15,6 +15,7 @@
 @RestController
 @Configuration
 @ComponentScan("eu.wdaqua.qanary.component")
+// Used by default, but excluded when a pipeline doesn't act as component
 @ConditionalOnProperty(name = "pipeline.as.component", matchIfMissing = true, havingValue = "true")
 public class QanaryService {
 

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

@@ -22,6 +22,7 @@
 import java.net.URI;
 
 @Controller
+// Used by default, but excluded when a pipeline doesn't act as component
 @ConditionalOnProperty(name = "pipeline.as.component", matchIfMissing = true, havingValue = "true")
 public class QanaryServiceController {
 

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

@@ -22,7 +22,9 @@
 
 // Conditional controller
 @Controller
+// Used by default, but excluded when a pipeline doesn't act as component
 @ConditionalOnProperty(name = "pipeline.as.component", matchIfMissing = true, havingValue = "true")
+
 public class QanaryServiceControllerRoot {
 
     private final Logger logger = LoggerFactory.getLogger(QanaryServiceControllerRoot.class);

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

@@ -28,6 +28,7 @@
 import java.util.List;
 
 @Component
+// Only created when the pipeline should act as a component, otherwise not
 @ConditionalOnProperty(name = "pipeline.as.component", havingValue = "true")
 public class QanaryPipelineComponent extends QanaryComponent {
 
@@ -45,9 +46,17 @@ public class QanaryPipelineComponent extends QanaryComponent {
     public QanaryPipelineComponent() {
     }
 
+    /**
+     * Implementation of the QanaryComponent 'process()' method. Executes its own pipeline with pre-defined components and writes the results
+     * to the parent triplestore as annotated of this component.
+     *
+     * @param myQanaryMessage QanaryMessage passed from the "parent" pipeline
+     * @throws Exception
+     */
     @Override
     public QanaryMessage process(QanaryMessage myQanaryMessage) throws Exception {
 
+        // Get required information
         URI externalEndpoint = this.qanaryConfigurator.getEndpoint();
         URI internalEndpoint = myQanaryMessage.getEndpoint();
         QanaryTripleStoreProxy qanaryTripleStoreConnector = this.qanaryConfigurator.getQanaryTripleStoreConnector();
@@ -76,6 +85,15 @@ public QanaryMessage process(QanaryMessage myQanaryMessage) throws Exception {
         return myQanaryMessage;
     }
 
+    /**
+     * Inserts all statements within the passed @param constructedTriples Model to an UPDATE query and executes it.
+     * Uses a separate query and string replacement rather than variable replacement (readResourcesFromFileWithMap), as the converted map
+     * cannot be parsed to a single RDFNode.
+     *
+     * @param graph                      Target graph
+     * @param constructedTriples         Model with statements
+     * @param qanaryTripleStoreConnector
+     */
     private void updateTriplesFromModel(URI graph, Model constructedTriples, QanaryTripleStoreProxy qanaryTripleStoreConnector) {
         try (ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream()) {
             constructedTriples.write(byteArrayOutputStream, "Turtle");
@@ -89,13 +107,31 @@ private void updateTriplesFromModel(URI graph, Model constructedTriples, QanaryT
         }
     }
 
+    /**
+     * Executes a construct query to the graph @param graph with the passed QanaryTripleStoreConnector
+     *
+     * @param graph                      Graph on which the CONSTRUCT is executed
+     * @param qanaryTripleStoreConnector
+     * @return Model
+     * @throws IOException
+     */
     public Model constructTriplesFromSubGraph(URI graph, QanaryTripleStoreConnector qanaryTripleStoreConnector) throws IOException {
         QuerySolutionMap qsm = new QuerySolutionMap();
         qsm.add("newComponent", ResourceFactory.createResource("urn:qanary:" + this.getApplicationName()));
         String sparqlQuery = QanaryTripleStoreConnector.readFileFromResourcesWithMap(CONSTRUCT_QUERY, qsm);
         return qanaryTripleStoreConnector.construct(sparqlQuery, graph);
     }
 
+    /**
+     * Fetches the questionID from the parent.
+     *
+     * @param graphUri                   The parent's graph
+     * @param qanaryTripleStoreConnector
+     * @return QuestionID as String
+     * @throws IOException
+     * @throws URISyntaxException
+     * @throws SparqlQueryFailed
+     */
     private String getQuestionIdWithQuery(String graphUri, QanaryTripleStoreConnector qanaryTripleStoreConnector) throws IOException, URISyntaxException, SparqlQueryFailed {
         QuerySolutionMap qsm = new QuerySolutionMap();
         qsm.add("graph", ResourceFactory.createResource(graphUri));

qanary_pipeline-template/src/main/resources/application.properties

@@ -111,6 +111,8 @@ springdoc.api-docs.path=/api-docs
 #cors.global.addAllowedOriginPattern=
 #cors.global.endpointPattern=
 ### SETTINGS FOR QANARY PIPELINE AS COMPONENT
+### False == Pipeline as pipeline, True == Pipeline as component
 pipeline.as.component=false
+# Uncomment (and edit) this, if pipeline.as.component == true
 #spring.boot.admin.url=http://localhost:8080
 #spring.boot.admin.client.url=http://localhost:8080