Package com.tngtech.archunit.library.freeze

Class FreezingArchRule

java.lang.Object

com.tngtech.archunit.library.freeze.FreezingArchRule

All Implemented Interfaces:

HasDescription, CanOverrideDescription<ArchRule>, ArchRule, CanBeEvaluated

@PublicAPI(usage=ACCESS)
public final class FreezingArchRule
extends Object
implements ArchRule

A decorator around an existing ArchRule that "freezes" the state of all violations on the first call instead of failing the test. This means in particular that the first run of a FreezingArchRule will always pass. Consecutive calls will only fail if "unknown" violations are introduced (read below for further explanations when a violation is "unknown"). Once resolved, initially "known" violations will fail again if they were re-introduced.

You might consider using this class when introducing a new ArchRule to an existing project that causes too many violations to solve at the current time. A typical example is a huge legacy project where a new rule might cause thousands of violations. Even if it is impossible to fix all those violations at the moment, it is typically a good idea to a) make sure no further violations are introduced and b) incrementally fix those violations over time one by one.

FreezingArchRule uses two concepts to support this use case:

• a ViolationStore to store the result of the current evaluation and retrieve the result of the previous evaluation of this rule.
  The default ViolationStore stores violations in plain text files within the path specified by freeze.store.default.path of "archunit.properties" (default: archunit_store)
  A custom implementation can be provided in two ways. Either programmatically via persistIn(ViolationStore), or by specifying the fully qualified class name within "archunit.properties", e.g.

  freeze.store=com.fully.qualified.MyViolationStore

• a ViolationLineMatcher to decide which violations are "known", i.e. have already been present in the previous evaluation.
  The default ViolationLineMatcher compares violations ignoring the line number of their source code location and auto-generated numbers of anonymous classes or lambda expressions.
  A custom implementation can be configured in two ways. Again either programmatically via associateViolationLinesVia(ViolationLineMatcher), or within "archunit.properties", e.g.

  freeze.lineMatcher=com.fully.qualified.MyViolationLineMatcher

Nested Class Summary

Nested classes/interfaces inherited from interface com.tngtech.archunit.lang.ArchRule

ArchRule.Assertions, ArchRule.Factory, ArchRule.Transformation

Method Summary

Modifier and Type	Method	Description
ArchRule	allowEmptyShould(boolean allowEmptyShould)	If set to true allows the should-clause of this rule to be checked against an empty set of elements.
FreezingArchRule	as(String newDescription)	Allows to adjust the description of this object.
FreezingArchRule	associateViolationLinesVia(ViolationLineMatcher matcher)	Allows to reconfigure how this FreezingArchRule will decide if an occurring violation is known or not.
FreezingArchRule	because(String reason)
void	check(JavaClasses classes)
EvaluationResult	evaluate(JavaClasses classes)
static FreezingArchRule	freeze(ArchRule rule)
String	getDescription()
FreezingArchRule	persistIn(ViolationStore store)	Allows to reconfigure the ViolationStore to use.
String	toString()

Methods inherited from class java.lang.Object

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

Method Details

check

@PublicAPI(usage=ACCESS)
public void check(JavaClasses classes)

Specified by:

check in interface ArchRule

because

@PublicAPI(usage=ACCESS)
public FreezingArchRule because(String reason)

Specified by:

because in interface ArchRule

allowEmptyShould

@PublicAPI(usage=ACCESS)
public ArchRule allowEmptyShould(boolean allowEmptyShould)

Description copied from interface: ArchRule

If set to true allows the should-clause of this rule to be checked against an empty set of elements. Otherwise, the rule will fail with a respective message. This is to prevent possible implementation errors, like filtering for a non-existing package in the that-clause causing an always-passing rule.
Note that this method will override the configuration property archRule.failOnEmptyShould.

Specified by:

allowEmptyShould in interface ArchRule

Parameters:

allowEmptyShould - Whether the rule fails if the should-clause is evaluated with an empty set of elements

Returns:

A (new) ArchRule with adjusted allowEmptyShould behavior

as

@PublicAPI(usage=ACCESS)
public FreezingArchRule as(String newDescription)

Description copied from interface: CanOverrideDescription

Allows to adjust the description of this object. Note that this method will not modify the current object, but instead return a new object with adjusted description.

Specified by:

as in interface CanOverrideDescription<ArchRule>

Parameters:

newDescription - The description the result of this method will hold

Returns:

A new equivalent object with adjusted description

evaluate

@PublicAPI(usage=ACCESS)
public EvaluationResult evaluate(JavaClasses classes)

Specified by:

evaluate in interface CanBeEvaluated

getDescription

@PublicAPI(usage=ACCESS)
public String getDescription()

Specified by:

getDescription in interface HasDescription

persistIn

@PublicAPI(usage=ACCESS)
public FreezingArchRule persistIn(ViolationStore store)

Allows to reconfigure the ViolationStore to use. The ViolationStore will be used to store the initial state of a FreezingArchRule and update this state on further evaluation of this rule.

Parameters:

store - The ViolationStore to use

Returns:

An adjusted FreezingArchRule which will store violations in the passed ViolationStore

See Also:

• FreezingArchRule

associateViolationLinesVia

@PublicAPI(usage=ACCESS)
public FreezingArchRule associateViolationLinesVia(ViolationLineMatcher matcher)

Allows to reconfigure how this FreezingArchRule will decide if an occurring violation is known or not.

Parameters:

matcher - A ViolationLineMatcher that decides which lines of a violation description are known and which are unknown and should cause a failure of this rule

Returns:

An adjusted FreezingArchRule which will compare occurring violations to stored ones with the given ViolationLineMatcher

See Also:

• FreezingArchRule

toString

public String toString()

Overrides:

toString in class Object

freeze

@PublicAPI(usage=ACCESS)
public static FreezingArchRule freeze(ArchRule rule)

Parameters:

rule - An ArchRule that should be "frozen" on the first call, i.e. all occurring violations will be stored for comparison on consecutive calls.

Returns:

A FreezingArchRule wrapping the original rule

See Also:

• FreezingArchRule