Make ArDoCo a Platform with Runners (#213)

To have different workflows and defined pipelines, we need to have different runners that each configure/define their own pipeline (i.e., which steps they want to execute). This allows us to not use every pipeline step in every run if you are only interested in parts like TLR where you do not need the ID step. At the same time, we can extend ArDoCo to have totally different pipeline definitions, e.g., for TLR between models and code where we do not need the NLP steps.

.gitignore

@@ -8,6 +8,8 @@ tests/tests-inconsistency/src/test/resources/testout/*
 
 tests/src/test/resources/config.properties
 
+/pipeline/src/test/resources/testout/
+
 tmp*
 
 .vscode/*

framework/common/pom.xml

@@ -8,7 +8,11 @@
   </parent>
 
   <artifactId>common</artifactId>
-  <name>Common Utilities &amp; Pipeline Definitions</name>
+  <name>Common Utilities and Pipeline Definitions</name>
+
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
   <dependencies>
     <dependency>
       <groupId>org.junit.jupiter</groupId>

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/api/data/connectiongenerator/ConnectionState.java

@@ -81,6 +81,7 @@ default ImmutableSet<TraceLink> getTraceLinks() {
      *
      * @param recommendedModelInstance the recommended instance
      * @param instance                 the model instance
+     * @param claimant                 the claimant
      * @param probability              the probability of the link
      */
     void addToLinks(RecommendedInstance recommendedModelInstance, ModelInstance instance, Claimant claimant, double probability);

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/api/data/inconsistency/Inconsistency.java

@@ -3,6 +3,9 @@
 
 import org.eclipse.collections.api.collection.ImmutableCollection;
 
+/**
+ * This interface represents an identified inconsistency of a certain type with a certain reason.
+ */
 public interface Inconsistency {
 
     /**

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/api/data/inconsistency/InconsistentSentence.java

@@ -11,14 +11,13 @@
 /**
  * This record represents an inconsistent sentence consisting of a sentence and all the inconsistencies that were found
  * within this sentence.
- * 
  */
 public record InconsistentSentence(Sentence sentence, List<Inconsistency> inconsistencies) {
 
     /**
      * Creates a new instance with only one inconsistency. The underlying list is populated with the given
      * inconsistency.
-     * 
+     *
      * @param sentence      the sentence
      * @param inconsistency the inconsistency
      */
@@ -28,8 +27,9 @@ public InconsistentSentence(Sentence sentence, Inconsistency inconsistency) {
 
     /**
      * Adds an inconsistency to the list of inconsistencies of this sentence.
-     * 
+     *
      * @param inconsistency the inconsistency
+     * @return whether the inconsistency was added successfully
      */
     public boolean addInconsistency(Inconsistency inconsistency) {
         return inconsistencies.add(inconsistency);
@@ -38,7 +38,7 @@ public boolean addInconsistency(Inconsistency inconsistency) {
     /**
      * Creates and returns an info string that contains the sentence number, the text of the sentence, and the reasons
      * of the inconsistencies
-     * 
+     *
      * @return an info string
      */
     public String getInfoString() {

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/api/data/textextraction/NounMapping.java

@@ -70,6 +70,7 @@ public interface NounMapping {
     /**
      * Gets the probability for name.
      *
+     * @param mappingKind the kind of mapping
      * @return the probability for name
      */
     double getProbabilityForKind(MappingKind mappingKind);
@@ -96,7 +97,7 @@ public interface NounMapping {
 
     /**
      * Register a listener that will be notified on certain events.
-     * 
+     *
      * @param listener the listener
      * @see #onDelete(NounMapping)
      */

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/common/util/CommonUtilities.java

@@ -31,7 +31,6 @@
 
 /**
  * General helper class for outsourced, common methods.
- *
  */
 public final class CommonUtilities {
     private static final Logger logger = LoggerFactory.getLogger(CommonUtilities.class);
@@ -202,6 +201,7 @@ public static boolean containsSeparator(String reference) {
      * @param nameMappings        the noun mappings
      * @param typeMappings        the type mappings
      * @param recommendationState the state the new RecommendedInstances should be added to
+     * @param claimant            the claimant that argued in favor of adding the RI
      * @param probability         the probability that should be annotated
      */
     public static void addRecommendedInstancesFromNounMappings(ImmutableList<String> similarTypes, ImmutableList<NounMapping> nameMappings,
@@ -373,10 +373,21 @@ public static boolean wordListContainsAnyWordFromRecommendedInstance(ImmutableLi
         return false;
     }
 
+    /**
+     * Return the current time as String. Can be used for output to show the date of processing.
+     *
+     * @return the current time as String
+     */
     public static String getCurrentTimeAsString() {
         return DATE_FORMATTER.format(LocalDateTime.now(ZoneId.systemDefault()));
     }
 
+    /**
+     * Reads text from the {@link InputStream} into a String
+     *
+     * @param text the input stream
+     * @return the text as String
+     */
     public static String readInputText(InputStream text) {
         var scanner = new Scanner(text, StandardCharsets.UTF_8);
         scanner.useDelimiter("\\A");
@@ -385,6 +396,12 @@ public static String readInputText(InputStream text) {
         return inputText;
     }
 
+    /**
+     * Reads the contents of a File into a String
+     *
+     * @param textFile the file to be read
+     * @return the content of the File as String
+     */
     public static String readInputText(File textFile) {
         try {
             return readInputText(new FileInputStream(textFile));

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/common/util/DataRepositoryHelper.java

@@ -195,12 +195,15 @@ public static boolean hasInconsistencyStates(DataRepository dataRepository) {
      * @return the state
      */
     public static InconsistencyStates getInconsistencyStates(DataRepository dataRepository) {
-        return dataRepository.getData(InconsistencyStates.ID, InconsistencyStates.class).orElseThrow();
+        if (hasInconsistencyStates(dataRepository)) {
+            return dataRepository.getData(InconsistencyStates.ID, InconsistencyStates.class).orElseThrow();
+        }
+        return null;
     }
 
     /**
      * Put the given {@link PreprocessingData} into the given {@link DataRepository}. This will override existing data!
-     * 
+     *
      * @param dataRepository    the dataRepository
      * @param preprocessingData the preprocessingData
      */

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/data/AbstractState.java

@@ -5,6 +5,9 @@
 
 import edu.kit.kastel.mcse.ardoco.core.configuration.AbstractConfigurable;
 
+/**
+ * This abstract class represents a state that can be saved to the {@link DataRepository} as {@link PipelineStepData}.
+ */
 public abstract class AbstractState extends AbstractConfigurable implements PipelineStepData {
 
     @Override

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/data/Confidence.java

@@ -12,18 +12,34 @@
 import edu.kit.kastel.mcse.ardoco.core.common.tuple.Triple;
 import edu.kit.kastel.mcse.ardoco.core.pipeline.agent.Claimant;
 
+/**
+ * This class represents a confidence for a certain (intermediate) result.
+ * Different {@link Claimant Claimants} can add their confidences that get aggregated via one of the {@link AggregationFunctions} to a single confidence value.
+ */
 public final class Confidence implements Comparable<Confidence>, ICopyable<Confidence> {
 
     private final AggregationFunctions confidenceAggregator;
 
     // Claimant, Confidence, MethodName
     private List<Triple<Claimant, Double, String>> agentConfidences;
 
+    /**
+     * Constructor for the confidence with a given aggregator function.
+     *
+     * @param confidenceAggregator the aggregation function for the confidence
+     */
     public Confidence(AggregationFunctions confidenceAggregator) {
         this.confidenceAggregator = confidenceAggregator;
         this.agentConfidences = new ArrayList<>();
     }
 
+    /**
+     * Constructor for the confidence with a given aggregator function and an initial claimant with a certain probability (confidence).
+     *
+     * @param claimant             the claimant
+     * @param probability          the probability
+     * @param confidenceAggregator the aggregation function
+     */
     public Confidence(Claimant claimant, double probability, AggregationFunctions confidenceAggregator) {
         this(confidenceAggregator);
         this.addAgentConfidence(claimant, probability);
@@ -34,6 +50,11 @@ private Confidence(AggregationFunctions confidenceAggregator, List<Triple<Claima
         this.agentConfidences = new ArrayList<>(agentConfidence);
     }
 
+    /**
+     * Returns the set of claimants that contribute to this confidence
+     *
+     * @return the claimants
+     */
     public Set<Claimant> getClaimants() {
         return this.agentConfidences.stream().map(Triple::first).collect(Collectors.toUnmodifiableSet());
     }
@@ -43,6 +64,12 @@ public Confidence createCopy() {
         return new Confidence(this.confidenceAggregator, this.agentConfidences);
     }
 
+    /**
+     * Add a confidence of an agent ({@link Claimant}.
+     *
+     * @param claimant   the claimant
+     * @param confidence the confidence
+     */
     public void addAgentConfidence(Claimant claimant, double confidence) {
         String method = getMethodInClaimant(claimant);
         agentConfidences.add(new Triple<>(claimant, confidence, method));
@@ -68,6 +95,11 @@ public String toString() {
         return "Confidence{" + confidenceAggregator + "=>" + getConfidence() + '}';
     }
 
+    /**
+     * Returns the (aggregated) confidence value
+     *
+     * @return the (aggregated) confidence value
+     */
     public double getConfidence() {
         if (agentConfidences.isEmpty()) {
             return 0;

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/pipeline/AbstractExecutionStage.java

@@ -9,12 +9,18 @@
 /**
  * This abstract class represents an execution step within ArDoCo. Examples are Text-Extraction, Recommendation-Generator, Connection-Generator, and
  * Inconsistency-Checker.
- *
+ * <p>
  * Implementing classes need to implement {@link #initializeState()} that cares for setting up the state for processing.
  * Additionally, implementing classes need to implement {@link #getEnabledAgents()} that returns the listof enabled {@link PipelineAgent pipeline agents}
  */
 public abstract class AbstractExecutionStage extends Pipeline {
 
+    /**
+     * Constructor for ExecutionStages
+     *
+     * @param id             the id of the stage
+     * @param dataRepository the {@link DataRepository} that should be used
+     */
     protected AbstractExecutionStage(String id, DataRepository dataRepository) {
         super(id, dataRepository);
     }

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/pipeline/AbstractPipelineStep.java

@@ -12,6 +12,12 @@ public abstract class AbstractPipelineStep extends AbstractConfigurable {
     private final String id;
     private final DataRepository dataRepository;
 
+    /**
+     * Constructor for a pipeline step
+     *
+     * @param id             the id of the stage
+     * @param dataRepository the {@link DataRepository} that should be used
+     */
     protected AbstractPipelineStep(String id, DataRepository dataRepository) {
         this.id = id;
         this.dataRepository = dataRepository;
@@ -24,7 +30,7 @@ protected AbstractPipelineStep(String id, DataRepository dataRepository) {
 
     /**
      * Returns the {@link DataRepository} that is used for saving and fetching data.
-     * 
+     *
      * @return the repository for used data
      */
     protected DataRepository getDataRepository() {
@@ -33,7 +39,7 @@ protected DataRepository getDataRepository() {
 
     /**
      * Returns the id
-     * 
+     *
      * @return the id
      */
     public final String getId() {

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/pipeline/Pipeline.java

@@ -40,6 +40,15 @@ public Pipeline(String id, DataRepository dataRepository, List<AbstractPipelineS
         this.pipelineSteps = pipelineSteps;
     }
 
+    /**
+     * Returns whether there were any pipeline steps added
+     *
+     * @return whether there were any pipeline steps added
+     */
+    public boolean hasPipelineSteps() {
+        return !pipelineSteps.isEmpty();
+    }
+
     /**
      * Adds a {@link AbstractPipelineStep} to the execution list of this pipeline
      *

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/pipeline/agent/Agent.java

@@ -1,7 +1,15 @@
 /* Licensed under MIT 2022-2023. */
 package edu.kit.kastel.mcse.ardoco.core.pipeline.agent;
 
+/**
+ * An Agent is a {@link Claimant} with an ID
+ */
 public interface Agent extends Claimant {
 
+    /**
+     * Return the id of the agent
+     *
+     * @return the id of the agent
+     */
     String getId();
 }

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/pipeline/agent/Claimant.java

@@ -1,5 +1,8 @@
 /* Licensed under MIT 2022-2023. */
 package edu.kit.kastel.mcse.ardoco.core.pipeline.agent;
 
+/**
+ * This is a marker interface for classes that claim something, i.e., an intermediate result with usually a certain confidence.
+ */
 public interface Claimant {
 }

framework/models/pom.xml

@@ -9,6 +9,10 @@
 
   <artifactId>models</artifactId>
   <name>Model Connections</name>
+
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
   <dependencies>
     <dependency>
       <groupId>org.fuchss</groupId>

framework/models/src/main/java/edu/kit/kastel/mcse/ardoco/core/models/java/CodeComment.java

@@ -70,10 +70,9 @@ public boolean equals(Object obj) {
         if (this == obj) {
             return true;
         }
-        if ((obj == null) || (getClass() != obj.getClass())) {
+        if (!(obj instanceof CodeComment other)) {
             return false;
         }
-        var other = (CodeComment) obj;
         return lineNumber == other.lineNumber && Objects.equals(text, other.text);
     }
 }

framework/models/src/main/java/edu/kit/kastel/mcse/ardoco/core/models/java/JavaClassOrInterface.java

@@ -90,10 +90,9 @@ public boolean equals(Object obj) {
         if (this == obj) {
             return true;
         }
-        if (obj == null || getClass() != obj.getClass()) {
+        if (!(obj instanceof JavaClassOrInterface other)) {
             return false;
         }
-        var other = (JavaClassOrInterface) obj;
         return Objects.equals(fullyQualifiedName, other.fullyQualifiedName);
     }
 

framework/models/src/main/java/edu/kit/kastel/mcse/ardoco/core/models/java/JavaMethod.java

@@ -65,10 +65,9 @@ public boolean equals(Object obj) {
         if (this == obj) {
             return true;
         }
-        if (obj == null || getClass() != obj.getClass()) {
+        if (!(obj instanceof JavaMethod other)) {
             return false;
         }
-        var other = (JavaMethod) obj;
         return Objects.equals(fullQualified, other.fullQualified);
     }