<commit_before>= Introduction =

== What is Mutability Detector? == 
Mutability Detector is designed to analyse Java classes and report on whether instances of a given class are immutable. It is intended that Mutability Detector will be usable at runtime or statically.
== What is Mutability Detector *NOT*? ==
  * Heavily used, production ready, well tested, extensively documented. Mutability Detector is very much in a pre-release state. As such it has very limited capability, but there is functionality there. Functionality which may just be useful.
  * A general tool for static code analysis - if you're looking for a tool which does static analysis for a wide range of code defects, you're probably looking for Findbugs.
  * A JSR-305 implementation - the tool does not yet recognise the annotations for concurrency described in that JSR. Thus, Mutability Detector does not look for, or change behaviour on finding, a class annotated with `@Immutable`.

= Getting Started =
Both static analysis and runtime analysis should use the same jar, available from [http://mutability-detector.googlecode.com/files/MutabilityDetector-0.02.jar here]. In the former case the tool is a command line app, in the latter it should be added to your classpath for inclusion in your project.

== Static Analysis ==

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 [http://code.google.com/p/classpath-explorer/ 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. DEFINITELY, DEFINITELY_NOT. Currently there is no way to select individual classes to be analysed with this command. As a workaround I'd suggest piping the output through {{{grep}}}.

The command line has the following usage:
{{{
usage: MutabilityDetector
 -classpath <path>   The classpath to be analysed by Mutability Detector
 -help               print this message
 -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'
 -v,--verbose        Print details of analysis and reasons for results.
}}}

== Runtime use == 

Create an instance of AnalysisSession using the default constructor. Classes can then be analysed on request, given the class name (this is the dotted class name, e.g. java.lang.String as opposed to java/lang/String.class). Like so:

{{{
// Initialise AnalysisSession
// This should be done only once per run, as each instance caches the result
IAnalysisSession analysisSession = new AnalysisSession(); 

...

// If you want to then test if a class is immutable, call the following:<commit_msg>Edited wiki page MainPage through web user interface.<commit_after>= Introduction =

== What is Mutability Detector? == 
Mutability Detector is designed to analyse Java classes and report on whether instances of a given class are immutable. It is intended that Mutability Detector will be usable at runtime or statically.
== What is Mutability Detector *NOT*? ==
  * Heavily used, production ready, well tested, extensively documented. Mutability Detector is very much in a pre-release state. As such it has very limited capability, but there is functionality there. Functionality which may just be useful.
  * A general tool for static code analysis - if you're looking for a tool which does static analysis for a wide range of code defects, you're probably looking for Findbugs.
  * A JSR-305 implementation - the tool does not yet recognise the annotations for concurrency described in that JSR. Thus, Mutability Detector does not look for, or change behaviour on finding, a class annotated with `@Immutable`.

= Getting Started =
Both static analysis and runtime analysis should use the same jar, available from [http://mutability-detector.googlecode.com/files/MutabilityDetector-0.02.jar here]. In the former case the tool is a command line app, in the latter it should be added to your classpath for inclusion in your project.

== Static Analysis ==

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 [http://code.google.com/p/classpath-explorer/ 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. DEFINITELY, DEFINITELY_NOT. Currently there is no way to select individual classes to be analysed with this command. As a workaround I'd suggest piping the output through {{{grep}}}.

The command line has the following usage:
{{{
usage: MutabilityDetector
 -classpath <path>   The classpath to be analysed by Mutability Detector
 -help               print this message
 -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'
 -v,--verbose        Print details of analysis and reasons for results.
}}}

== Runtime use == 

*The exact code listing here is out of date. It still gives a rough idea of how to use Mutability Detector at run time, but it CANNOT be copy/pasted.* I'm working on providing an up to date example.

Create an instance of AnalysisSession using the default constructor. Classes can then be analysed on request, given the class name (this is the dotted class name, e.g. java.lang.String as opposed to java/lang/String.class). Like so:

{{{
// Initialise AnalysisSession
// This should be done only once per run, as each instance caches the result
IAnalysisSession analysisSession = new AnalysisSession(); 

...

// If you want to then test if a class is immutable, call the following:
{'fraction_non_alphanumeric': 0.06274688544515344, 'fraction_numerical': 0.0018231540565177757, 'mean_word_length': 3.8262463343108504, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4967519', 'n_tokens_mistral': 1692, 'n_tokens_neox': 1605, 'n_words': 909}