Package org.variantsync.diffdetective.analysis

Class Analysis

java.lang.Object

org.variantsync.diffdetective.analysis.Analysis

public class Analysis
extends Object

Encapsulates the state and control flow during an analysis of the commit history of multiple repositories using VariationDiffs. Each repository is processed sequentially but the commits of each repository can be processed in parallel.

For thread safety, each thread receives its own instance of Analysis. The getters provides access to the current state of the analysis in one thread. Depending on the current phase only a subset of the state accessible via getters may be valid.

Author:

Paul Bittner, Benjamin Moosherr

See Also:

• forEachRepository(java.util.List<org.variantsync.diffdetective.datasets.Repository>, java.nio.file.Path, java.util.function.BiConsumer<org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path>)
• forEachCommit(java.util.function.Supplier<org.variantsync.diffdetective.analysis.Analysis>)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Analysis.Hooks	Hooks for analyzing commits using VariationDiffs.
static final class	Analysis.RuntimeWithMultithreadingResult	The effective runtime in seconds that we have when using multithreading.
static final class	Analysis.TotalNumberOfCommitsResult	The total number of commits in the observed history of the given repository.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	COMMITS_TO_PROCESS_PER_THREAD_DEFAULT	Default value for commitsToProcessPerThread
protected org.eclipse.jgit.revwalk.RevCommit	currentCommit
protected CommitDiff	currentCommitDiff
protected PatchDiff	currentPatch
protected VariationDiff<DiffLinesLabel>	currentVariationDiff
protected GitDiffer	differ
static final String	EXTENSION	File extension that is used when writing AnalysisResults to disk.
protected final List<Analysis.Hooks>	hooks
protected final Path	outputDir
protected Path	outputFile
protected final Repository	repository
protected final AnalysisResult	result
static final String	TOTAL_RESULTS_FILE_NAME	File name that is used to store the analysis results for each repository.

Constructor Summary

Constructors

Constructor	Description
Analysis(String taskName, List<Analysis.Hooks> hooks, Repository repository, Path outputDir)	Constructs the state used during an analysis.

Method Summary

Modifier and Type	Method	Description
<T extends Metadata<T>> void	append(AnalysisResult.ResultKey<T> resultKey, T value)	Convenience function for AnalysisResult.append(org.variantsync.diffdetective.analysis.AnalysisResult.ResultKey<T>, T) on getResult().
static <T> void	exportMetadata(Path outputDir, Metadata<T> metadata)	Exports the given metadata object to a file named according TOTAL_RESULTS_FILE_NAME in the given directory.
static <T> void	exportMetadataToFile(Path outputFile, Metadata<T> metadata)	Exports the given metadata object to the given file.
static AnalysisResult	forEachCommit(Supplier<Analysis> analysis)	Same as forEachCommit(Supplier, int, int).
static AnalysisResult	forEachCommit(Supplier<Analysis> analysisFactory, int commitsToProcessPerThread, int nThreads)	Runs the analysis for the repository given in Analysis(java.lang.String, java.util.List<org.variantsync.diffdetective.analysis.Analysis.Hooks>, org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path).
static void	forEachRepository(List<Repository> repositoriesToAnalyze, Path outputDir, BiConsumer<Repository,Path> analyzeRepository)	Runs analyzeRepository on each repository, skipping repositories where an analysis was already run.
static AnalysisResult	forSingleCommit(String commitHash, Analysis analysis)	Runs the analysis for the repository given in Analysis(java.lang.String, java.util.List<org.variantsync.diffdetective.analysis.Analysis.Hooks>, org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path) on the given commit only.
static void	forSinglePatch(String commitHash, String fileName, Analysis analysis)	Runs the analysis for the repository given in Analysis(java.lang.String, java.util.List<org.variantsync.diffdetective.analysis.Analysis.Hooks>, org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path) on the given patch only.
<T extends Metadata<T>> T	get(AnalysisResult.ResultKey<T> resultKey)	Convenience getter for AnalysisResult.get(org.variantsync.diffdetective.analysis.AnalysisResult.ResultKey<T>) on getResult().
org.eclipse.jgit.revwalk.RevCommit	getCurrentCommit()	The currently processed commit.
CommitDiff	getCurrentCommitDiff()	The currently processed commit diff.
PatchDiff	getCurrentPatch()	The currently processed patch.
VariationDiff<DiffLinesLabel>	getCurrentVariationDiff()	The currently processed patch.
Path	getOutputDir()	The destination for results which are written to disk.
Path	getOutputFile()	The destination for results which are written to disk and specific to the currently processed commit batch.
Repository	getRepository()	The repository this analysis is run on.
AnalysisResult	getResult()	The results of the analysis.
protected void	processCommit()
protected void	processCommitBatch(List<org.eclipse.jgit.revwalk.RevCommit> commits)	Sequential analysis of all commits as one batch.
protected void	processPatch()
protected <Hook> boolean	runFilterHook(ListIterator<Hook> hook, org.apache.commons.lang3.function.FailableBiFunction<Hook,Analysis,Boolean,Exception> callHook)
protected <Hook> void	runHook(ListIterator<Hook> hook, org.apache.commons.lang3.function.FailableBiConsumer<Hook,Analysis,Exception> callHook)
protected <Hook> void	runReverseHook(ListIterator<Hook> hook, org.apache.commons.lang3.function.FailableBiConsumer<Hook,Analysis,Exception> callHook)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

EXTENSION

public static final String EXTENSION

File extension that is used when writing AnalysisResults to disk.

See Also:

• Constant Field Values

TOTAL_RESULTS_FILE_NAME

public static final String TOTAL_RESULTS_FILE_NAME

File name that is used to store the analysis results for each repository.

See Also:

• Constant Field Values

COMMITS_TO_PROCESS_PER_THREAD_DEFAULT

public static final int COMMITS_TO_PROCESS_PER_THREAD_DEFAULT

Default value for commitsToProcessPerThread

See Also:

• forEachCommit(Supplier, int, int)
• Constant Field Values

hooks

protected final List<Analysis.Hooks> hooks

repository

protected final Repository repository

differ

protected GitDiffer differ

currentCommit

protected org.eclipse.jgit.revwalk.RevCommit currentCommit

currentCommitDiff

protected CommitDiff currentCommitDiff

currentPatch

protected PatchDiff currentPatch

currentVariationDiff

protected VariationDiff<DiffLinesLabel> currentVariationDiff

outputDir

protected final Path outputDir

outputFile

protected Path outputFile

result

protected final AnalysisResult result

Constructor Details

Analysis

public Analysis(String taskName,
 List<Analysis.Hooks> hooks,
 Repository repository,
 Path outputDir)

Constructs the state used during an analysis.

Parameters:

taskName - the name of the overall analysis task

hooks - the hooks to be run for analysis

repository - the repository to analyze

outputDir - the directory where all results are saved

Method Details

getRepository

public Repository getRepository()

The repository this analysis is run on. Always valid.

getCurrentCommit

public org.eclipse.jgit.revwalk.RevCommit getCurrentCommit()

The currently processed commit. Valid during the commit phase.

getCurrentCommitDiff

public CommitDiff getCurrentCommitDiff()

The currently processed commit diff. Valid when Analysis.Hooks.onParsedCommit(org.variantsync.diffdetective.analysis.Analysis) is called until the end of the commit phase.

getCurrentPatch

public PatchDiff getCurrentPatch()

The currently processed patch. Valid during the patch phase.

getCurrentVariationDiff

public VariationDiff<DiffLinesLabel> getCurrentVariationDiff()

The currently processed patch. Valid only during Analysis.Hooks.analyzeVariationDiff(org.variantsync.diffdetective.analysis.Analysis).

getOutputDir

public Path getOutputDir()

The destination for results which are written to disk. Always valid.

getOutputFile

public Path getOutputFile()

The destination for results which are written to disk and specific to the currently processed commit batch. Valid during the batch phase.

getResult

public AnalysisResult getResult()

The results of the analysis. This may be modified by any hook and should be initialized in Analysis.Hooks.initializeResults(org.variantsync.diffdetective.analysis.Analysis) (e.g. by using append(org.variantsync.diffdetective.analysis.AnalysisResult.ResultKey<T>, T)). Always valid.

get

public <T extends Metadata<T>> T get(AnalysisResult.ResultKey<T> resultKey)

Convenience getter for AnalysisResult.get(org.variantsync.diffdetective.analysis.AnalysisResult.ResultKey<T>) on getResult(). Always valid.

append

public <T extends Metadata<T>> void append(AnalysisResult.ResultKey<T> resultKey,
 T value)

Convenience function for AnalysisResult.append(org.variantsync.diffdetective.analysis.AnalysisResult.ResultKey<T>, T) on getResult(). Always valid.

forEachRepository

public static void forEachRepository(List<Repository> repositoriesToAnalyze,
 Path outputDir,
 BiConsumer<Repository,Path> analyzeRepository)

Runs analyzeRepository on each repository, skipping repositories where an analysis was already run. This skipping mechanism doesn't distinguish between different analyses as it only checks for the existence of TOTAL_RESULTS_FILE_NAME. Delete this file to rerun the analysis.

For each repository a directory in outputDir is passed to analyzeRepository where the results of the given repository should be written.

Parameters:

repositoriesToAnalyze - the repositories for which analyzeRepository is run

outputDir - the directory where all repositories will save their results

analyzeRepository - the callback which is invoked for each repository

forSingleCommit

public static AnalysisResult forSingleCommit(String commitHash,
 Analysis analysis)

Runs the analysis for the repository given in Analysis(java.lang.String, java.util.List<org.variantsync.diffdetective.analysis.Analysis.Hooks>, org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path) on the given commit only. Analysis.Hooks passed to Analysis(java.lang.String, java.util.List<org.variantsync.diffdetective.analysis.Analysis.Hooks>, org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path) are the main customization point for executing different analyses.

Parameters:

commitHash - the commit to analyze relative to its first parent

analysis - the analysis to run

forSinglePatch

public static void forSinglePatch(String commitHash,
 String fileName,
 Analysis analysis)

Runs the analysis for the repository given in Analysis(java.lang.String, java.util.List<org.variantsync.diffdetective.analysis.Analysis.Hooks>, org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path) on the given patch only. Analysis.Hooks passed to Analysis(java.lang.String, java.util.List<org.variantsync.diffdetective.analysis.Analysis.Hooks>, org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path) are the main customization point for executing different analyses. The Hooks will be manipulated in that a new hook for patch filtering will be inserted as the first hook for as long as the analysis runs. This hook will be removed afterwards. It is assumed that this hook remains at the same place and is not manipulated by the user.

Parameters:

commitHash - the commit to analyze relative to its first parent

fileName - the name of the file that was edited in the given commit

analysis - the analysis to run

forEachCommit

public static AnalysisResult forEachCommit(Supplier<Analysis> analysis)

Same as forEachCommit(Supplier, int, int). Defaults to COMMITS_TO_PROCESS_PER_THREAD_DEFAULT and a machine dependent number of Diagnostics.getNumberOfAvailableProcessors().

forEachCommit

public static AnalysisResult forEachCommit(Supplier<Analysis> analysisFactory,
 int commitsToProcessPerThread,
 int nThreads)

Runs the analysis for the repository given in Analysis(java.lang.String, java.util.List<org.variantsync.diffdetective.analysis.Analysis.Hooks>, org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path). The repository history is processed in batches of commitsToProcessPerThread on nThreads in parallel. Analysis.Hooks passed to Analysis(java.lang.String, java.util.List<org.variantsync.diffdetective.analysis.Analysis.Hooks>, org.variantsync.diffdetective.datasets.Repository, java.nio.file.Path) are the main customization point for executing different analyses. By default only the total number of commits and the total runtime with multithreading of the VariationDiff parsing is recorded.

Parameters:

analysisFactory - creates independent (at least thread safe) instances the analysis state

commitsToProcessPerThread - the commit batch size

nThreads - the number of parallel processed commit batches

processCommitBatch

protected void processCommitBatch(List<org.eclipse.jgit.revwalk.RevCommit> commits)
                           throws Exception

Sequential analysis of all commits as one batch.

Parameters:

commits - the commit batch to be processed

Throws:

Exception

See Also:

• forEachCommit(java.util.function.Supplier<org.variantsync.diffdetective.analysis.Analysis>)

processCommit

protected void processCommit()
                      throws Exception

Throws:

Exception

processPatch

protected void processPatch()
                     throws Exception

Throws:

Exception

runHook

protected <Hook> void runHook(ListIterator<Hook> hook,
 org.apache.commons.lang3.function.FailableBiConsumer<Hook,Analysis,Exception> callHook)
                       throws Exception

Throws:

Exception

runFilterHook

protected <Hook> boolean runFilterHook(ListIterator<Hook> hook,
 org.apache.commons.lang3.function.FailableBiFunction<Hook,Analysis,Boolean,Exception> callHook)
                                throws Exception

Throws:

Exception

runReverseHook

protected <Hook> void runReverseHook(ListIterator<Hook> hook,
 org.apache.commons.lang3.function.FailableBiConsumer<Hook,Analysis,Exception> callHook)
                              throws Exception

Throws:

Exception

exportMetadata

public static <T> void exportMetadata(Path outputDir,
 Metadata<T> metadata)

Exports the given metadata object to a file named according TOTAL_RESULTS_FILE_NAME in the given directory.

Type Parameters:

T - Type of the metadata.

Parameters:

outputDir - The directory into which the metadata object file should be written.

metadata - The metadata to serialize

exportMetadataToFile

public static <T> void exportMetadataToFile(Path outputFile,
 Metadata<T> metadata)

Exports the given metadata object to the given file. Overwrites existing files.

Type Parameters:

T - Type of the metadata.

Parameters:

outputFile - The file to write.

metadata - The metadata to serialize