Package org.variantsync.diffdetective.util

Interface Source

All Known Subinterfaces:

GitPatch, Relevance

All Known Implementing Classes:

BadVDiff, CommitDiffVariationDiffSource, CompositeSource, Configure, ConfigureSpec, FileSource, GitPatch.SimpleGitPatch, GitSource, LineGraphFileSource, PatchDiff, PatchString, ProjectionSource, Search, Trace, TraceSup, VariationDiff, VariationTree, ViewSource

public interface Source

An interface for source traceability. For testing and debugging, it can be really useful to know where some value originated from. For example, imagine an error during you analysis of a VariationDiff. Now you want to know where the variation diff came from. The solution: DiffDetectice tracks the source and transformations of important data structures like VariationDiff.getSource() and allows you to inspect them using this interface.

Source represents a hierarchy of inputs, processing steps, and results (the distinction between these types is not directly reflected in the API and only serve as explanation of the interface).

• An input (e.g., FileSource) is a Source that has no children. Inputs are the leafs of the Source hierarchy and contain the name of the input (e.g., "file" or "URL") and some arguments (e.g., the file name or URL).
• A step (e.g., ProjectionSource) processed one or more sources, has a name and may be configurable by some arguments. Unconfigurable processing steps (or steps whose configurability should not be tracked) are most commonly represented by CompositeSource. Note that a step might also include (interim) results and might thus be considered a result too.
• A result (e.g., VariationDiff) contains some data and the source of that data. The contained data is not directly accessible by this interface but can be obtained by looking up the subclass representing that result with <T>findFirst(org.variantsync.diffdetective.util.Source,java.lang.Class<T>) or <T>findAll(org.variantsync.diffdetective.util.Source,java.lang.Class<T>). Results are not necessary to trace the source of some data (and it might thus be omitted from the Source hierarchy) but can help to identify a buggy processing step.

In summary, each Source in the hierarchy has a short explanation and a number of arguments. A source may contain additional data (e.g., the diff a variation diff originated from) that is too big to be printed by the standard formatting functions (shallowExplanation(), shortExplanation(org.variantsync.diffdetective.util.Source), fullExplanation(int,java.lang.StringBuilder)) of this interface. To access such data, or the arguments of specific subclasses, you can use <T>findFirst(org.variantsync.diffdetective.util.Source,java.lang.Class<T>) and <T>findAll(org.variantsync.diffdetective.util.Source,java.lang.Class<T>).

For dealing with generic sources, it is recommended to use the static methods of this interface. They provide a more readable interface (e.g., variationDiff.shallowExplanation() vs. Source.shallowExplanation(variationDiff)) and correctly deal with null sources (treated as Unknown).

See Also:

• CompositeSource
• FileSource

Field Summary

Fields

Modifier and Type	Field	Description
static final Source	Unknown	A placeholder for an unknown source without any explanation.

Method Summary

Modifier and Type	Method	Description
private static <T> void	findAll(List<T> result, Source source, Class<T> clazz)	Implementation of <T>findAll(org.variantsync.diffdetective.util.Source,java.lang.Class<T>) using an result accumulator.
static <T> List<T>	findAll(Source source, Class<T> clazz)	Uses a depth first traversal of the Source hierarchy to find and return all instances of clazz.
static <T> T	findFirst(Source source, Class<T> clazz)	Uses a depth first traversal of the Source hierarchy to find and return the first instances of clazz.
default void	fullExplanation(int level, StringBuilder result)	Explains this source hierarchy in detail.
static String	fullExplanation(Source source)	Calls fullExplanation(int,java.lang.StringBuilder) on source but handles null like Unknown and returns the resulting string.
default String	functionExplanation()	The same as fullExplanation(Source) but with a different formatting.
default Source	getRootSource()	Returns one representative Source that identifies the initial data.
default List<Object>	getSourceArguments()	Returns a list of arguments required to understand this source.
String	getSourceExplanation()	Returns a short, one line explanation or identifier of this source.
default List<Source>	getSources()	Returns a list of sources that influenced this source.
static String	rootExplanation(Source source)	Returns a shallowExplanation() of the root source of source.
default String	shallowExplanation()	An explanation of this source disregarding all child sources.
static String	shallowExplanation(Source source)	Calls shallowExplanation() on source but handles null like Unknown.
static String	shortExplanation(Source source)	Returns a short one line explanation of source by pairing shortExplanation(org.variantsync.diffdetective.util.Source) with rootExplanation(org.variantsync.diffdetective.util.Source).

Field Details

Unknown

static final Source Unknown

A placeholder for an unknown source without any explanation. Should be preferred to a null Source to make it easily grepable.

Method Details

getSourceExplanation

String getSourceExplanation()

Returns a short, one line explanation or identifier of this source. The result is used by shallowExplanation() and is formatted together with getSourceArguments() like "sourceExplanation(argument1, argument2)".

getSourceArguments

default List<Object> getSourceArguments()

Returns a list of arguments required to understand this source. Each argument in the result list should represent a string without newlines and will be formatted together with getSourceExplanation() like "sourceExplanation(argument1, argument2)" by shallowExplanation(). This method is only intended to access the arguments for printing. In case access to the well-typed object is required, use <T>findFirst(org.variantsync.diffdetective.util.Source,java.lang.Class<T>) or <T>findAll(org.variantsync.diffdetective.util.Source,java.lang.Class<T>) and use the accessors of the underlying type.

For ease of implementing Source, the return value is a list of Objects instead of a list of Strings to allow code like List.of(arg0, arg1, arg2) instead of List.of(arg0.toString(), arg1.toString(), arg2.toString()). Users of this function should assume nothing from the returned objects except that Object.toString() is well behaved.

Returns:

an empty list by default

See Also:

• shallowExplanation()

getSources

default List<Source> getSources()

Returns a list of sources that influenced this source. Noteworthy processing steps and incorporation of multiple sources are implemented as a tree of sources. This functions returns the children of this source.

By default, the first child source is treated specially in getRootSource().

Returns:

an empty list by default

shallowExplanation

default String shallowExplanation()

An explanation of this source disregarding all child sources. The resulting string should not contain any newlines.

Returns:

"sourceExplanation(argument1, argument2, ...)" by default

See Also:

• getSourceExplanation()
• getSourceArguments()

shallowExplanation

static String shallowExplanation(Source source)

Calls shallowExplanation() on source but handles null like Unknown.

getRootSource

default Source getRootSource()

Returns one representative Source that identifies the initial data. A good root source should help humans to understand at what data they are looking at. Good examples is a filename or a commit and repository combination. Note that sometimes this is an arbitrary decision (e.g., the state before or after a diff) and might depend on the problem that is currently worked on. Hence, there is might not be one correct result in all circumstances.

Returns:

the first child or this if there are no children

rootExplanation

static String rootExplanation(Source source)

Returns a shallowExplanation() of the root source of source.

shortExplanation

static String shortExplanation(Source source)

Returns a short one line explanation of source by pairing shortExplanation(org.variantsync.diffdetective.util.Source) with rootExplanation(org.variantsync.diffdetective.util.Source).

fullExplanation

default void fullExplanation(int level,
 StringBuilder result)

Explains this source hierarchy in detail. The result will contain at least one line per Source in the hierarchy (by default in the shallowExplanation() format). The state of result must be in a new line before and after a call to this method.

Parameters:

level - the current indentation level (two spaces per level) that needs to be added before each line

result - the string containing the result of this method

fullExplanation

static String fullExplanation(Source source)

Calls fullExplanation(int,java.lang.StringBuilder) on source but handles null like Unknown and returns the resulting string.

functionExplanation

default String functionExplanation()

The same as fullExplanation(Source) but with a different formatting. Where fullExplanation renders this tree of sources as using newlines and indentation, functionExplanation renders this tree as one large, nested function call of the form: getSourceExplanation()(args..., nested sources...).

findAll

static <T> List<T> findAll(Source source,
 Class<T> clazz)

Uses a depth first traversal of the Source hierarchy to find and return all instances of clazz. This method is intended to provide access to the data contained in the source hierarchy. For example, Source.findAll(src, File.class) finds all source files. Note that arguments are not inspected. In case an implementation Source contains a file as argument it is not included in the result.

See Also:

• <T>findFirst(org.variantsync.diffdetective.util.Source,java.lang.Class<T>)

findAll

private static <T> void findAll(List<T> result,
 Source source,
 Class<T> clazz)

Implementation of <T>findAll(org.variantsync.diffdetective.util.Source,java.lang.Class<T>) using an result accumulator.

findFirst

static <T> T findFirst(Source source,
 Class<T> clazz)

Uses a depth first traversal of the Source hierarchy to find and return the first instances of clazz. This method is intended to provide access to the data contained in the source hierarchy. For example, Source.findFirst(src, PatchDiff.class) finds the first PatchDiff. This allows access to data and arguments like PatchDiff.getDiff() but it does not traverse the getSourceArguments() directly.

See Also:

• <T>findAll(org.variantsync.diffdetective.util.Source,java.lang.Class<T>)