Unit testing Java data classes immutability with the Mutability Detector

In all our project, we use data classes which, by definition, contain data (fields) but no (business) logic.

According to the best coding practices, a data class should preferably be immutable because immutability means thread safety. Main reference here is Joshua Bloch’s Effective Java book; this Yegor Bugayenko’s post is also very interesting reading.

An immutable class has several interesting properties:

  • it should be not sub-classable (i.e. it should be final or it should have a static factory method and a private constructor)
  • all fields should be private (to prevent direct access)
  • all fields should be written once (at instance creation time) (i.e. they should be final and without setters)
  • all mutable type (like java.util.Date) fields should be protected to prevent client write access by reference

An example of immutable class is the following:

    public final class ImmutableBean {

      private final String aStr;
      private final int anInt;

      public ImmutableBean(String aStr, int anInt) {
        this.aStr = aStr;
        this.anInt = anInt;
      }

      public String getAStr() {
        return aStr;
      }

      public int getAnInt() {
        return anInt;
      }
    }

Note: as frequent in Java, there is a lot of boilerplate code which hides the immutability definitions.

Libraries like Project Lombok makes our life easier because we can use the @Value annotation to easily define an immutable class as follows:

    @Value
    public class LombokImmutableBean {
        String aStr;
        int anInt;
    }

which is a lot more more readable.

Should we (unit) test a class to check its immutability?

In a perfect world, the answer is no.

With the help of our preferred IDE automatic code generation features or with libraries like Lombok it is not difficult to add immutability to a class.

But in a real world, human errors can be happen, when we create the class or when we (or may be a junior member of the team) modify the class later on. What happen if a new field is added without final and a setter is generated by using IDE code generator? The class is no more immutable.

It is important to guarantee that the class is and remains immutable along all project lifetime.

And with the help of the Mutability Detector we can easily create a test to check the immutability status of a class.

As usual, Maven/Gradle dependencies can be found on Maven Central.

To test our ImmutableBean we can create the following jUnit test class:

    import static org.mutabilitydetector.unittesting.MutabilityAssert.assertImmutable;

    public class ImmutableBeanTest {

      @Test
      public void testClassIsImmutable() {
        assertImmutable(ImmutableBean.class);
      }
    }

the test will fail if the class is not immutable.

For example, if a field is not final and it has a setter method, the test fails and the error message is very descriptive:

org.mutabilitydetector.unittesting.MutabilityAssertionError: 
Expected: it.gualtierotesta.testsolutions.general.beans.ImmutableBean to be IMMUTABLE
 but: it.gualtierotesta.testsolutions.general.beans.ImmutableBean is actually NOT_IMMUTABLE
Reasons:
    Field is not final, if shared across threads the Java Memory Model will not guarantee it is initialised before it is read. 
        [Field: aStr, Class: it.gualtierotesta.testsolutions.general.beans.ImmutableBean]
    Field [aStr] can be reassigned within method [setaStr] 
        [Field: aStr, Class: it.gualtierotesta.testsolutions.general.beans.ImmutableBean]

The complete project can be found on my Test Solutions gallery project on GitHub. See module general.

The approach I suggest is to use Lombok without any immutability test. If Lombok cannot be used (for example in a legacy project), use the Mutability Detector to assert that the class is really immutable.

Advertisements

Tutorial: using FindBugs with Maven

FindBugs can be executed using Maven in two different modes: as stand-alone command or as part of the Maven site command.

These two modes require different settings in the project pom.xml but they are not incompatible to each other so we can use both of them.

info48
You can find complete Maven project here.

Stand-alone mode

Let’s start with the stand-alone mode which requires the following configuration in the pom.xml:

<build>
    <plugins>       
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>findbugs-maven-plugin</artifactId>
            <version>3.0.1</version>
        </plugin>
         ... other build plugins ....
    </plugins>
</build>

Please note that the FindBugs plugin definition is inside build – plugins section of the pom file.

Giving the following command:

mvn findbugs:findbugs

FindBugs is run against our project with the following log in the console output:

[INFO] --- findbugs-maven-plugin:3.0.1:findbugs (default-cli) @ CodeQualityGallery ---
[INFO] Fork Value is true
     [java] Warnings generated: 1
[INFO] Done FindBugs Analysis....

warning48
FindBugs analyze the compiled files (*.class). If the project is not compiled or just cleaned, FindBugs will report nothing, without error messages. So take care to build your project before running FindBugs.

A warnings number is reported on the console. Warnings are possible bugs found by the FindBugs detectors.

The warnings details are included in a report created in the file target/findbugsXml.xml which is in XML format and so not really readable.

A better way to examine the warnings is to use the FindBugs native GUI with the command:

mvn findbugs:gui

The FindBugs window shows the bugs on the left, the (read-only) code on the right and the bug explanation below.

FindBugs GUI

You can filter bugs for bug rank from the most critical (“scariest”) to trivial and even, saving project status, comparing project evolution (which means how may bugs has been eliminated/introduced after previous FindBugs check).

warning48All main IDEs (Eclipse, NetBeans, IntelliJ) FindBugs plugins show similar views and they can also let you modify the code so I don’t suggest to use FindBugs native GUI unless you have to create exclusion files (see below) which is easier with the native GUI: select a bug, filter it out and export bug filters.

 

Site mode

Maven site command is used to generate a project “site”, which is a collection of information on the project nicely reported in HTML pages. You can configure which information is included in the site report and, of course, you can add FindBugs analysis results.

Maven site requires a “reporting section” in the pom file.

<reporting>
    <plugins>       
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>findbugs-maven-plugin</artifactId>
            <version>3.0.1</version>
        </plugin>
         ... other site plugins ....
    </plugins>
</reporting>

Giving the following command (note: clean and install options are in to assure that project is compiled and all tests run):

mvn clean install site

on the console output we will see the following:

.....
[INFO] --- maven-site-plugin:3.3:site (default-site) @ CodeQualityGallery ---
[INFO] configuring report plugin org.apache.maven.plugins:maven-jxr-plugin:2.5
[INFO] configuring report plugin org.apache.maven.plugins:maven-project-info-reports-plugin:2.8
[INFO] configuring report plugin org.codehaus.mojo:findbugs-maven-plugin:3.0.1
[INFO] Fork Value is true
     [java] Warnings generated: 2
[INFO] Done FindBugs Analysis....
[INFO] configuring report plugin org.apache.maven.plugins:maven-pmd-plugin:3.4
[WARNING] No project URL defined - decoration links will not be relativized!
[INFO] Rendering site with org.apache.maven.skins:maven-default-skin:jar:1.0 skin.
[INFO] Skipped "Source Xref" report, file "xref/index.html" already exists for the English version.
[INFO] Generating "Source Xref" report    --- maven-jxr-plugin:2.5
[INFO] Generating "Dependency Convergence" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "Dependency Information" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "About" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "Plugin Management" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "Project Plugins" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "Project Team" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "Project Summary" report    --- maven-project-info-reports-plugin:2.8
[INFO] Generating "FindBugs" report    --- findbugs-maven-plugin:3.0.1
[INFO] Generating "PMD" report    --- maven-pmd-plugin:3.4
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
.....

The “site” is created in the target/site dir. Opening the file target/site/index.html with the browser, we will see something like the following:

2015-06-08bIn the Project Reports section you will find the FindBugs report like the following:

2015-06-08c   The report is interesting because it give us the complete picture of our project in the summary section but also the list of the files which have FindBugs detected issues with all details including the priority (i.e. how dangerous could be the problem).

Configuration options

Regardless the used mode, the FindBugs plugin can be configured to modify and tune its behaviour. All below configurations should be placed in the configuration section of the plugin:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>findbugs-maven-plugin</artifactId>
    <version>3.0.1</version>
    <configuration>
        .....put here
    </configuration>
</plugin>

warning48
Configurations in the build and reporting sections are independent so we can have two different settings in the two modes, stand-alone and site.

Best practice is to use a light and fast configuration on the standalone mode, in order to run quick checks during development and an high effort, production quality configuration for the site mode.

Let’s examine the most important configuration options:

DEBUG: With <debug>true</debug> option, FindBugs will show what is doing during analysis. Useful to fine tune or checks the settings.

EFFORT: with  <effort>Max</effort> we can increase the time FindBugs is allowed to use to analyze the code. More effort means more accurate analysis but, of course, FindBugs run slower.

EXTERNAL PLUGINS: FindBugs can be extended with additional detectors. See my post on the topic. The  <pluginList>plugin1[, plugin2…]</pluginList> configuration option list the plugins to be used. See the sample project for a real example.

EXCLUSIONS: If you need to disable a detector or to disable the analysis on same classes, an exclude list can be specified with the <excludeFilterFile> path_to_exclude_file </excludeFilterFile> option. File syntax is documented here. An easy way to create this file is by using the FindBugs GUI which has an export filter function. See the sample project for a real example.

 

FindBugs plugins

FindBugs is a key code quality tool for Java based projects.

It includes several dozens of bug patterns which are used by FindBugs to identify potential bugs and, more in general, weaknesses in our code.

FindBugs has a plugin architecture which can be used to extend the set of detectors (bug patterns) used during the analysis.

There are few open source projects which aim to develop FindBugs plugin.

My preferred one is Fb-Contrib which contains a significant amount of additional detectors. See here for the complete list. Most of them are really useful to detect poor code quality.

Another interesting plugin is Find Security Bugs; the focus here is on security vulnerabilities (list here) like using unsecured random generator or not checking data received from the user.

Let’s have a look at versions dependencies:

JDK FindBugs FB-Contrib Find Security Bugs
7 and 8 3.x 6.x 1.3 and above
5 and 6 2.x 5.x 1.2

All plugins are released in .jar format and they can be easily added to the FindBugs :

  • FindBugs stand-alone: place the jar in the plugins dir inside FindBugs installation dir
  • Eclipse FindBugs plugin: use the plugin options to specify the plugin path or place the jar file inside FindBugs plugins dir
  • NetBeans FindBugs integration: use Custom FindBugs Plugins button inside Editor → Hints → FindBugs page.
  • IntelliJ FindBugs plugin: add new plugin in the Plugin Configuration tab.

After adding new plugins, review the list of detectors enabled. New detectors are usually added but not enabled.

My 5 favorite NetBeans IDE features (vs. Eclipse)

In my current project, Eclipse Kepler has been selected by the customer as the preferred IDE for all main tasks. Of course, I’m also using NetBeans 8.0 for some activities like, for example, legacy code test coding.

I have already used Eclipse some years ago and, at that time (2009), Eclipse Galileo were quite superior to NetBeans 6.x: faster, rich of code hints and warnings, full of useful plugins. So, I was not really happy when the project moved to NetBeans (because of its Swing support).

Now let me compare them again, Eclipse Kepler 4.3 vs NetBeans 8.0, on same project (a big ant based web project) and on the same PC (Win7 64bit 4G RAM).

Speed

My first big surprise. Five years ago, when I moved from Galileo to NetBeans I really missed Eclipse speed: coding, windowing, compilation, everything were significantly faster in Eclipse.

Now this speed advantage is gone. I don’t have benchmarks to demonstrate my feeling but now my coding is visibly faster with NetBeans 8.0 than with Eclipse Kepler. If you install Findbugs and PMD plugins, Eclipse becomes really slow.

Native testing support

Second surprise. Why, in 2014, an IDE for Java EE developers does not include full testing support ?

I cannot imagine any real EE developers which does not need any kind of test support from the IDE.

In NetBeans there is complete native jUnit and TestNG support (templates, test runs, jump to test option in the editor, both *Test and *IT files support) which I found very useful and efficient.

Eclipse native support is poor but of course it can be extended via plugin. I’m using MoreUnit plugin which is quite nice and add many missing features to Eclipse. See here for a small tutorial.

But even if you install a test support plugin like MoreUnit, still an important Eclipse limitation remains : the possibility to have a dir for test files separated from the main src dir, which is an essential feature to let us handling deployments. If you don’t believe me, have a look at this 2008 bug still open: https://bugs.eclipse.org/bugs/show_bug.cgi?id=224708 and its related bugs.
Simply unbelievable.

Java Hints and FindBugs integration

While coding, it is important to have feedbacks from the IDE about the quality of the code and possible errors. NetBeans Java hints is a very reach set of the code checks which helps me to avoid stupid errors and keep high the quality of my work. In addition, NetBeans includes first class support for FindBugs which, again, helps me during coding sessions.

I’ve found NetBeans code quality checks support better than the one available in Eclipse Kepler + FindBugs plugin. More checks and better control on how, for example, disable a FindBugs warning on a line (because it is ok) using an annotation: just a click with NetBeans and by hand with Eclipse.

Coding support: templating, completion,interfaces…

I like NetBeans coding support: code templates (some letters + tab to get most used keywords and structures (see here for some examples), auto-completion, now also using sub words, I can easily jump from an interface to its implementation, the new indent guide lines.

Similar features are available in Eclipse using, for example, the Code Recommenders plugin but I’ve found it quite slow on my machine so I had to disinstall it.

User Interface

NetBeans user interfaces has improved a lot while keeping its strong point: it is easy to use. Windows and menus are easy to find and the full screen mode is very useful on small screens. I really like the color coding setup (Norway Today) which makes code reading a pleasure and the dark skins for working late in the evening.

On the contrary, Eclipse interfaces remains somehow confusing and, my personal opinio, perspectives and workspaces are simply a waste of time.

Improving NetBeans FindBugs integration

In NetBeans 7.4, the FindBugs integration inside the IDE has been improved giving us the possibility to specify additional rules to be checked.

FindBugs has a plugin architecture that let user to add custom rules sets. I usually add FindBugs rules from FBContrib, a FindBugs auxiliary rules set.

There are hundred of rules included in FBContrib. Complete list can be found here.

What is amazing in NetBeans is that not only you can tell the IDE to use the additional rules sets but that the new rules are seamless integrated in the NetBeans interface. For example, FBContrib rules are grouped together with standard FindBugs checks.

First step is to specify the path to the FBContrib jar file (downloaded from the FBContrib website) in the FindBugs configuration (Options –> Editor –> Hints –> FindBugs )

2013-10-22b-fig1

Press “Custom FindBugs Plugins” button.

2013-10-22b-fig2

The “Add” button let us specify one or more additional jar files.

As I already mentioned, the rules included in the FBContrib jar file are integrated with the other native FindBugs rules.

See for example, the rules related to the “Secure” description before

2013-10-22b-fig3

and after FBContrib has been specified:

2013-10-22b-fig4

Both native and FBContrib rules can be enabled and disabled one by one.

With NetBeans Hints, FindBugs and, may be, PMD (see this post on PMD plugin ) all enabled there is a good chance that one problematic line can have more than one warning. In this case I suggest to keep native NetBeans hints enabled and disable the check in the other tools, mainly because NetBeans native checks are faster.

PMD and Maven

After explaining how to use PMD with NetBeans in this post, let me describe how we can directly run PMD using Maven, without the help of an IDE plugin.

We can have two different approaches:

  • invoking the PMD plugin for Maven.
  • using Maven site feature.

First approach. Add the following lines to the project pom (in the build/plugins section):

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-pmd-plugin</artifactId>
  <version>3.0.1</version>
</plugin>

(Of course, maven-pmd-plugin version can vary. See here for last updates).

PMD can be invoked from the command line with the following:

mvn pmd:pmd

which will create a file named target/pmd.xml. XML is the default output format but it can be changed with the format configuration option.

The file contains all violations detected by PMD in all source files found in the project. Test files are not checked in the standard configuration.

By default, only rules from the following rulesets are checked by PMD: java-basic, java-imports and java-unusedcode. We will see later how to control which rules and rulesets should be checked.

In the second approach, PMD is invoked during the Maven site command which is a reporting command. In this case the PMD plugin definition should be placed inside the reporting/plugins section of the project pom.

<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-jxr-plugin</artifactId>
      <version>2.3</version>
    </plugin>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-pmd-plugin</artifactId>
      <version>3.0.1</version>
      <configuration>
        <targetJdk>1.6</targetJdk>
        <rulesets>
          <ruleset>pmd_rules.xml</ruleset>
        </rulesets>
      </configuration>
    </plugin>
  </plugins>
</reporting>

Note: the jxr plugin is useful for source code analysis. The reporting section usually has more plugins that the two shown in the examples.

Here the PMD plugin has been configured with a couple of important parameters: the Java version (targetJdk) and the set of rules and ruleset to be used (rulesets/ruleset).

My usual approach (described in the PMD in NetBeans post) is to define a custom list of rules and rulesets to be checked by PMD. With the Maven plugin we can use the same XML file used to generate the jar file for EasyPMD plugin.

We will have the same check results from NetBeans + EasyPMD and from Maven. Very good.

I usually save the custom rules file in the root of the project with a name like “pmd_rules.xml”. Not so smart name but easy to understand. Of course, it is versioned together with the project files.

Being versioned and saved in the repository let us share exactly the same PMD setup among all development team members. In the pom we have specified a relative path so we will not have problem to access it from different project installation paths.

If the project is multi-module with a parent pom as top dir and the modules in subdirs, I change the configuration as following:

<rulesets>
  <ruleset><strong>..\</strong>pmd_rules.xml</ruleset>
</rulesets>

so running mvn site (or mvn pmd:pmd) on a module will work. Only mvn site on parent pom will not work (but this is less important).

The two approaches I described are not exclusive and they can both be used in the same project. Just remember to have the same configuration in the two pom locations (build/plugins and reporting/plugins).

 

PMD in NetBeans: the EasyPMD plugin

PMD is a powerful source code quality checker which analyze our code and report bad coding habits, failures to respect naming conventions, inefficiencies and many others.

PMD has an internal list of rules to be checked. Rules are divided in sets. Each set contains several rules.

For example the “Comments” set includes all rules related to code comments.

PMD rules sets are documented here.

On my opinion a PMD rule violation should be intended as a suggestion to better check the code to be sure that the offending code line is really what we want to have. Often PMD is right to say the line should be fixed or at least improved.

In NetBeans PMD is enabled by the EasyPMD3 plugin available from NetBeans plugin area and from the plugin home page ( http://gianlucacosta.info/software/easypmd/ ).

Note: There is an enhancement request to introduce native PMD support in NetBeans, like what has been done with FindBugs.

One very important point to remember is that EasyPMD (and so PMD) is controlled by the “Action Items” window settings. Just click on the “Action Items” window filter icon and check that EasyPmd notifications are enabled. If not enabled,PMD will not check the code.

2013-10-05a

When enabled, PMD checks Java code and

  • reports in the “Action Items” window all rules violations
  • marks as a blue circle the lines in the open editor window that contain a rule violation

2013-10-05b

In the above picture, PMD reports that the field callCount is initialized to zero but this is a meaningless operation because zero is the default value for numeric fields. Actually this initialization will cost us few cpu cycles.

This is the PMD “RedundandFieldInitializer” rule belonging to “Optimization” rule set but there are many others.

Some PMD rules conflict with NetBeans hints because they check the same situation.

2013-10-05c

The processFindForm() method in the picture reassigns one of its parameter (owner); PMD reports it at line 86 while NetBeans at line 106.

I usually disable the PMD rule if there is an equivalent NetBeans hint, also because some NetBeans hints give us the possibility to fix the problem with a dedicated refactoring (but not the one in the picture). PMD is an pure analyzer so it does not perform any change in the code.

There are several rules and rules sets available in PMD but not all of them are relevant for us. For example the “Android” rule set is of course not interesting for Java EE applications.

Thankfully we can select rules set and single rules we want PMD to check.

EasyPMD give us two approaches: select the rules sets to use but not the single rules or full freedom in rules and rule sets selection.

The first approach can be done with the EasyPMD UI interface (Tools –> Options –> Miscellaneus –> EasyPmd3):

2013-10-05d

The list in the picture contains all rules set we want PMD to check. Single rules can be included or removed with the “Add Standard” and “Remove” buttons.

The alternative solution (full freedom) requires a preliminary activity: to prepare a jar file with the PMD rules set and rules we want to be checked. Detailed instructions to prepare the rules jar can be found here.

The basic idea is to create a xml file with contents like the following:

<?xml version="1.0"?>
<ruleset name="Custom ruleset" xmlns="http://pmd.sourceforge.net/ruleset/2.0.0">
<rule ref="rulesets/java/basic.xml"/>
<rule ref="rulesets/java/comments.xml">
    <exclude name="CommentSize"/>
</rule>

In the fragment above, I selected the complete “basic” rule set and the “comments” rule set except the “CommentSize” rule.

Source and jar file I use can be found here

Once the jar file with rules has been created, we instructs EasyPMD plugin to use it:

2013-10-05e

The rules jar is also useful to share PMD rules across the development team. The jar file can be placed in a shared area and all team members can refer to it in their (local) EasyPMD configuration.