org.mutabilitydetector
Class ConfigurationBuilder

java.lang.Object
  org.mutabilitydetector.ConfigurationBuilder

@NotThreadSafe
public abstract class ConfigurationBuilder
extends Object

Builds a Configuration for customising Mutability Detector's analysis. The most significant feature of ConfigurationBuilder is to allow defining hardcoded results for particular classes, which should be respected during analysis. For more details, see MutabilityAssert.

Users should subclass ConfigurationBuilder and override the configure() method, which should then be used to construct a MutabilityAsserter instance. For example:

 
 MutabilityAsserter myAsserter = MutabilityAsserter.configured(new ConfigurationBuilder() {
   @Override public void configure() {
     
     hardcodeAsDefinitelyImmutable(SomeClass.class);
     setExceptionPolicy(ExceptionPolicy.CARRY_ON);
     
     mergeHardcodedResultsFrom(ConfigurationBuilder.DEFAULT_CONFIGURATION);
   }
 });
 
 

This class also provides an out-of-the-box configuration with hardcoded results for common JDK classes. This includes classes where Mutability Detector's analysis is incorrect, for example, java.lang.String, java.lang.Integer (and other primitive wrapper types) and java.math.BigDecimal.

See Also:

Configurations.JDK_CONFIGURATION

Constructor Summary

ConfigurationBuilder()

Method Summary

Configuration	build()
abstract void	configure() Subclasses should override this method to configure analysis.
protected Set<AnalysisResult>	getCurrentlyHardcodedResults() Returns an immutable snapshot of the hardcoded results as at time of calling.
protected void	hardcodeAsDefinitelyImmutable(Class<?> immutableClass) Hardcodes a result indicating the given class is Immutable.
protected void	hardcodeAsDefinitelyImmutable(String immutableClassName) Hardcodes a result indicating the given class is Immutable.
protected void	hardcodeResult(AnalysisResult result) Add a predefined result used during analysis.
protected void	hardcodeResults(AnalysisResult... result) Adds all the given AnalysisResults, as if hardcodeResult was called for each element in the var args parameter.
protected void	hardcodeResults(Iterable<AnalysisResult> result) Adds all the given AnalysisResults, as if hardcodeResult was called for each element in the iterable.
protected void	mergeHardcodedResultsFrom(Configuration otherConfiguration) Merges the hardcoded results of this Configuration with the given Configuration.
protected void	setExceptionPolicy(CheckerRunner.ExceptionPolicy exceptionPolicy) Configures how Mutability Detector's analysis should respond to exceptions during analysis.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConfigurationBuilder

public ConfigurationBuilder()

Method Detail

configure

public abstract void configure()

Subclasses should override this method to configure analysis.

It is recommended that any custom Configuration's merge with the Configurations.OUT_OF_THE_BOX_CONFIGURATION in order to remain consistent with MutabilityAssert, and the command line settings. For example:

 
 MutabilityAsserter myAsserter = MutabilityAsserter.configured(new ConfigurationBuilder() {
   @Override public void configure() {
     mergeHardcodedResultsFrom(ConfigurationBuilder.OUT_OF_THE_BOX_CONFIGURATION);
   }
 });
 
 

Similarly for ThreadUnsafeAnalysisSession.createWithCurrentClassPath(Configuration)

The available configuration methods are listed below.

See Also:

hardcodeResult(AnalysisResult), hardcodeResults(AnalysisResult...), hardcodeResults(Iterable), hardcodeAsDefinitelyImmutable(Class), hardcodeAsDefinitelyImmutable(String), mergeHardcodedResultsFrom(Configuration), #setExceptionPolicy(ExceptionPolicy), Configurations.OUT_OF_THE_BOX_CONFIGURATION

build

public final Configuration build()

setExceptionPolicy

protected final void setExceptionPolicy(CheckerRunner.ExceptionPolicy exceptionPolicy)

Configures how Mutability Detector's analysis should respond to exceptions during analysis.

During analysis, an exception may occur which is recoverable. That is, Mutability Detector is able to continue it's analysis, and may produce valid results.

The default behaviour is to use CheckerRunner.ExceptionPolicy.FAIL_FAST, meaning any unhandled exceptions will propogate up past the assertion, and cause a failing test.

Setting this configuration flag to CheckerRunner.ExceptionPolicy.CARRY_ON may allow unit tests to function where exceptions don't necessarily preclude a useful output. For example, consider a class which you wish to make immutable; a test for that class fails with an unhandled exception. If that test has, say 10 reasons for mutability, and 1 of those causes the test to abort with an exception, you have just lost out on 90% of the required information. CheckerRunner.ExceptionPolicy.CARRY_ON will allow the test to report 9 out of 10 reasons. The test may be useful, although it won't be comprehensive.

If you are unlucky enough to have a test which results in an exception, please report it to the Mutability Detector project, at the project homepage.

Parameters:

exceptionPolicy - - how to respond to exceptions during analysis. Defaults to CheckerRunner.ExceptionPolicy.FAIL_FAST

See Also:

Configuration.exceptionPolicy()

hardcodeResult

protected final void hardcodeResult(AnalysisResult result)

Add a predefined result used during analysis.

Hardcoding a result means that information queried about a class will honour the result you have set. For example, if during analysis, Mutability Detector has to discover whether a field type is mutable or not. However, requesting the AnalysisResult of the class in question directly will return the real result from the actual analysis. This holds for unit tests, command line runs, and runtime analysis. As such, calling this method will have no effect when querying an AnalysisResult directly.

See Also:

Configuration.hardcodedResults(), AnalysisResult, AnalysisSession.resultFor(org.mutabilitydetector.locations.Dotted)

hardcodeResults

protected final void hardcodeResults(Iterable<AnalysisResult> result)

Adds all the given AnalysisResults, as if hardcodeResult was called for each element in the iterable.

See Also:

AnalysisResult, hardcodeResult(AnalysisResult)

hardcodeResults

protected final void hardcodeResults(AnalysisResult... result)

Adds all the given AnalysisResults, as if hardcodeResult was called for each element in the var args parameter.

See Also:

AnalysisResult, hardcodeResult(AnalysisResult)

hardcodeAsDefinitelyImmutable

protected final void hardcodeAsDefinitelyImmutable(Class<?> immutableClass)

Hardcodes a result indicating the given class is Immutable.

See Also:

AnalysisResult.definitelyImmutable(String)

hardcodeAsDefinitelyImmutable

protected final void hardcodeAsDefinitelyImmutable(String immutableClassName)

Hardcodes a result indicating the given class is Immutable. The most reliable format of class name would be the dotted version of the fully qualified name, e.g. java.lang.String. However, there will be a "best effort" attempt to accept other formats, e.g. java/lang/String, or java.lang.String.class.

See Also:

ClassNameConverter, AnalysisResult.definitelyImmutable(String)

getCurrentlyHardcodedResults

protected final Set<AnalysisResult> getCurrentlyHardcodedResults()

Returns an immutable snapshot of the hardcoded results as at time of calling. Note changes the returned Set will not allow modifications, and will not reflect changes to the underlying configuration.

mergeHardcodedResultsFrom

protected void mergeHardcodedResultsFrom(Configuration otherConfiguration)

Merges the hardcoded results of this Configuration with the given Configuration. The resultant hardcoded results will be the union of the two sets of hardcoded results. Where the AnalysisResult for a class is found in both Configurations, the result from otherConfiguration will replace the existing result in this Configuration. This replacement behaviour will occur for subsequent calls to mergeHardcodedResultsFrom(Configuration).

Parameters:

otherConfiguration - - Configuration to merge hardcoded results with.