org.mutabilitydetector

Interface Configuration

public interface Configuration

Allows customisation of Mutability Detector's analysis.

The most significant feature of Configuration is to allow defining hardcoded results for particular classes, which should be respected during analysis.

See Also:

ConfigurationBuilder, MutabilityAsserter.configured(Configuration), MutabilityAsserter.configured(ConfigurationBuilder), DefaultCachingAnalysisSession.createWithCurrentClassPath(Configuration)

Method Summary

Modifier and Type	Method and Description
AsmVerifierFactory.ClassloadingOption	classloadingOption() Configures whether Mutability Detector loads classes or not during analysis.
CheckerRunner.ExceptionPolicy	exceptionPolicy() Configures how Mutability Detector's analysis should respond to exceptions during analysis.
com.google.common.collect.ImmutableSetMultimap<String,CopyMethod>	hardcodedCopyMethods() Safe methods for copying collections when being assigned to a field in a class's constructor.
Map<Dotted,AnalysisResult>	hardcodedResults() Add a predefined result used during analysis.
HardcodedResultsUsage	howToUseHardcodedResults() Decide how hardcoded results should be used.
Set<Dotted>	immutableContainerClasses()
MutabilityCheckerFactory.ReassignedFieldAnalysisChoice	reassignedFieldAlgorithm() Deprecated.

Method Detail

hardcodedResults

Map<Dotted,AnalysisResult> hardcodedResults()

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:

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

howToUseHardcodedResults

HardcodedResultsUsage howToUseHardcodedResults()

Decide how hardcoded results should be used.

The default is HardcodedResultsUsage.LOOKUP_WHEN_REFERENCED.

See Also:

HardcodedResultsUsage.LOOKUP_WHEN_REFERENCED, HardcodedResultsUsage.DIRECTLY_IN_ASSERTION

immutableContainerClasses

Set<Dotted> immutableContainerClasses()

exceptionPolicy

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.

Setting this configuration flag to CheckerRunner.ExceptionPolicy.FAIL_FAST, will cause any unhandled exceptions will propagate, causing a failing test or aborting a command line run.

Setting this configuration flag to CheckerRunner.ExceptionPolicy.CARRY_ON may allow analysis 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 class which causes exceptions during analysis, please report it to the Mutability Detector project, at the project homepage.

Returns:

ExceptionPolicy - how to respond to exceptions during analysis. Defaults to

classloadingOption

AsmVerifierFactory.ClassloadingOption classloadingOption()

Configures whether Mutability Detector loads classes or not during analysis.

Mutability Detector often needs to analyse classes other than the one specified in order to gain a more accurate result. The default behaviour is to load these classes from the current classpath. Setting this flag to AsmVerifierFactory.ClassloadingOption.DISABLED will instruct Mutability Detector not to attempt to load classes, and instead use a method of analysing all classes, which guarantees not to load classes. This can save on heap requirements as Mutability Detector's non classloading approach requires less data than class loading.

For the moment, this option is recommended if you find classloading takes up too much heap, and the classes loaded for analysis won't be loaded anyway.

Returns:

ClassloadingOption - whether to allow class loading for analysis or not

reassignedFieldAlgorithm

@Deprecated
MutabilityCheckerFactory.ReassignedFieldAnalysisChoice reassignedFieldAlgorithm()

Deprecated.

Only to be used in development. This method will never appear in a released version.

hardcodedCopyMethods

com.google.common.collect.ImmutableSetMultimap<String,CopyMethod> hardcodedCopyMethods()

Safe methods for copying collections when being assigned to a field in a class's constructor.

Returns:

hardcodedCopyMethods - methods that are deemed safe for copying