Package org.variantsync.diffdetective.analysis

Interface Analysis.Hooks

All Known Implementing Classes:
ConstructionValidation, EditClassOccurenceAnalysis, EditClassValidation, ExampleFinder, FilterAnalysis, LineGraphExportAnalysis, PreprocessingAnalysis, StatisticsAnalysis, ViewAnalysis
Enclosing class:
Analysis
public static interface Analysis.Hooks
Hooks for analyzing commits using VariationDiffs.

In general the hooks of different Hook instances are called in sequence according to the order specified in Analysis(java.lang.String, java.util.List<org.variantsync.diffdetective.analysis.Analysis.Hooks>, org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path) (except end hooks). Hooks are separated into two categories: phases and events.

A phase consists of two hooks with the prefix begin and end. It is guaranteed that the end hook is called if and only if the begin hook was called, even in the presence of exceptions, so they are safe to use for resource management. For this purpose, end hooks are called in reverse order as specified in Analysis(java.lang.String, java.util.List<org.variantsync.diffdetective.analysis.Analysis.Hooks>, org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path).

Phases can be called an arbitrary number of times but are nested in the following order (from outer to inner):

  • batch
  • commit
  • patch
An inner phase is only executed while an outer phase runs (in between the phase's begin and end hooks).

An analysis implementing Hooks can perform various actions during each hook. This includes the creation and modification of analysis results, modifying their internal state, performing IO operations and throwing exceptions. In contrast, the only analysis state hooks are allowed to modify is the result of an Analysis. All other state (e.g. Analysis.getCurrentCommit()) must not be modified. Care must be taken to avoid the reliance of the internal state on a specific commit batch being processed as only the results of each commit batch are merged and returned by Analysis.forEachCommit(java.util.function.Supplier<org.variantsync.diffdetective.analysis.Analysis>).

Hooks that return a boolean are called filter hooks and can, in addition to the above, skip any further processing in the current phase (including following inner phases) by returning false. If a hook starts skipping, any invocations of the same filter hook of following Hook instances won't be executed. Processing continues (after calling missing end hooks of the current phase) in the next outer phase after the skipped phase.

Hooks without a begin or end prefix are events emitted during some specified conditions. See their respective documentation for details.