Mutability Detector is designed to analyse Java classes and report on whether instances of a given class are immutable. It can be used:
- In a unit test, with an assertion like
assertImmutable(MyClass.class). Is your class actually immutable? What about after that change you just made? - As a FindBugs plugin. Those classes you annotated with
@Immutable, are they actually? - At runtime. Does your API require being given immutable objects?
- From the command line. Do you want to quickly run Mutability Detector over an entire code base?
Developing classes to be immutable has several benefits. An immutable object is one which cannot be changed once it is constructed. While writing concurrent programs, using immutable objects can greatly simplify complex systems, as sharing an object across threads is much safer. There are a few rules for what makes an object immutable, and it is easy to break the rules and render the object unsafe. This could lead to subtle, hard-to-detect bugs which could lower the integrity of the system. Using an automated tool to recognise mutability where it's not intended can reduce the complexity of writing immutable classes.
Mutability Detector is in the very early stages of development. To give an idea of the performance, on a Thinkpad T61 the tool runs over the JVM's rt.jar (48MB, 17,000 classes) in under 2 minutes. The tool analyses on the strict side, very few classes are found to be perfectly immutable, for instance, java.lang.String and java.lang.Integer are not immutable because of a non-final field, and primitive array field, respectively. Mutability Detector will not be released under a 1.0 version until these cases can be correctly analysed.
If this sounds like it may be interesting or useful to you, continue reading for more information on getting started. You may also want to take a look at the Mutability Detector Blog.
To use Mutability Detector directly, either from the command line, at runtime in your application, or as part of your unit tests, grab the jar available here. Or you can declare it in your Maven-compatible build tool, with the following coordinates:
<dependency>
<groupId>org.mutabilitydetector</groupId>
<artifactId>MutabilityDetector</artifactId>
<version>0.9.6</version>
<scope>test</scope>
</dependency>
Just add MutabilityDetector to your unit testing classpath. Adding your first assertion is as simple as:
import static org.mutabilitydetector.unittesting.MutabilityAssert.assertImmutable;
@Test public void checkMyClassIsImmutable() {
assertImmutable(MyClass.class);
}
Though it is possible (or likely) that you will have to configure the assertion to deal with any false positives that arise. See the JavaDoc on MutabilityAssert for further information.
An example of how to run it is probably the most useful. If you want to analyse MyCodebase.jar use:
java -jar MutabilityDetector.jar -classpath path/to/MyCodebase.jar
Mutability Detector can handle jars as seen above, or directories of class files (thanks go to the authors of classpath-explorer). So if your codebase was in the filesystem as directories and .class files, and the directory MyCodebase was the root of that, you could run:
java -jar MutabilityDetector.jar -classpath path/to/MyCodebase
The output is a list of the analysed classes against the result of asking "Is immutable?", ie. IMMUTABLE, NOT_IMMUTABLE, EFFECTIVELY_IMMUTABLE.
The command line has the following usage:
$ java -jar MutabilityDetector-0.9.jar --help
usage: MutabilityDetector
-cl,--classlist <filename> Only report results on the classes listed
within <filename>. Currently this option
only supports plain text files with one
class per line. It is also rather limited in
the format it accepts: each line must
contain the equivalent of
someClass.getName(), e.g. it must be
java.lang.Integer, with dot delimiters and
no suffixes such as .java or .class. Can be
used in conjunction with -match to reduce
the time taken to perform analysis.
-cp,--classpath <path> The classpath to be analysed by Mutability
Detector
-e,--reportErrors Reports on errors in the analysis. Defaults
to false.
-f,--failFast When true, encountering an unhandled
exception will cause analysis to abort
immediately. When false, exceptions during
analysis of a particular class will be
reflected in the result assigned to that
class. Defaults to false.
-h,--help print this message
-m,--match <regex> A regular expression used to match class
names to analyse. This is matched against
the fully qualified class name, minus the
.class suffix (i.e. it matches against
'java.lang.Object', not
'java/lang/Object.class'). The default is
'.*', meaning all classes will be analysed.
-r,--report <arg> Choose what is reported from the analysis.
Valid options are [ALL|IMMUTABLE|MUTABLE].
If not specified, or doesn't match an
available mode, defaults to 'ALL'
-s,--summary Show summary of analysis result.
-v,--verbose Print details of analysis and reasons for
results.
It is possible to use Mutability Detector at runtime. For example, consider if you have a library which requires that objects passed to it are immutable. On receiving such an object, you can ask Mutability Detector if it is actually immutable.
Check out the code snippet in this example, which shows correct usage against trunk code.
To have Mutability Detector inspect your classes during a FindBugs analysis, grab the MutabilityDetector4FindBugs jar, and configure it to be picked up by FindBugs during a normal analysis, as described here.
Mutability Detector will perform it's analysis on any classes annotated with @Immutable.
MutabilityDetector4FindBugs is also available from Maven Central, with the following coordinates:
<dependency>
<groupId>org.mutabilitydetector</groupId>
<artifactId>MutabilityDetector4FindBugs</artifactId>
<version>0.9.1</version>
<scope>test</scope>
</dependency>
Contact can be made either by leaving comments, by email, or through Gitter.
Gitter is available for OSX, Windows, Linux, iPhone, and Android. It can also be mirror over and IRC Bridge. To install Gitter head over to https://gitter.im/apps for your system.
