Unit testing Java data classes immutability with the Mutability Detector

Updated post can be found on my new blog site.

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:

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 {

public void testClassIsImmutable() {

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:

Expected: it.gualtierotesta.testsolutions.general.beans.ImmutableBean to be IMMUTABLE
but: it.gualtierotesta.testsolutions.general.beans.ImmutableBean is actually NOT_IMMUTABLE
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.

Vaadin dependencies in Maven projects

Updated post can be found on my new blog site.

The Vaadin framework has several dependencies but not all of them should be included in our war/ear artifacts.

The following table shows all Vaadin version 7.6/7.7 main modules and their meaning and usage

Module Description and usage
server This is the core of the framework. It has the following (transitive) dependencies: vaadin-shared and vaadin-sass-compiler
themes Compiled version of the standard Vaadin themes
client-compiled Compiled version of the standard Vaadin widgets set
client Vaadin and GWT classes for widgets
client-compiler Widgets compiler based on GWT Google Web Toolkit
push Optional module. It includes the support for push protocols (server to client) thanks to the Atmosphere framework
shared Common modules code. It is included as dependency in the server module
sass-compiler SASS to CSS compiler, used at build time and at run-time (“on-the-fly” compilation). It is included as dependency in the server module

Depending on the project requirements, the above modules should be included or not as project dependencies. We can identify two possible scenarios:

  1. Project without a custom widget set. It can have a custom theme
  2. Project with a custom widget set

In the first case (without a custom widget set) we need the following modules:

  • server
  • themes
  • push (optional)
  • client-compiled

while, if we have a custom widget set, we need to compile the widgets so the dependencies become:

  • server
  • themes
  • push (optional)
  • client (for build only)
  • client-compiler (for build only)

Note: the compiled custom widgets are included in our artifact

The following table summarizes the Maven dependencies:

Module ArtifactId Scope Required?
server vaadin-server compile yes
themes vaadin-themes compile yes
client-compiled vaadin-client-compiled runtime only if the project does not use custom widget set
client vaadin-client provided only with custom widget set
client-compiler vaadin-client-compiler provided only with custom widget sett. See also note below.
push vaadin-push compile optional
shared vaadin-shared vaadin-server dependency. No need to be specified in the pom.xml
sass-compiler vaadin-sass-compiler vaadin-server dependency. No need to be specified in the pom.xml

Note: the vaadin-client-compiler dependency is automatically included in the classpath by the Vaadin Maven plugin (vaadin-maven-plugin) when the custom widgets set should be compiled.

Java EE schedulers

Updated post can be found on my new blog site.

Java EE application servers have native scheduling support and, in most of the applications, there is no need to include external dependencies like the famous Quartz scheduler library.

The Java EE 6 Timer Service, available on Java EE 6 and 7 full profile, give us many options to define the scheduling interval and what’s happen if we stop and restart the application which contains our scheduler.

A Java EE scheduler can be:

  • persistent: the application server saves the scheduling events when the application is down  in order to not lose them
  • automatic: simple scheduler definition, most of the details are handled by the application server
  • programmatic: we have full control of all scheduler parameters.

To decide which is the best option, we should first answer to the following questions:

1. Is it allowed to miss some scheduling events?

If we stop or restart the application (for example during an update) the scheduler will be stopped and some scheduling events could be lost.

The scheduler can be configured to save the missed events and to execute them when the application will be up again. The application server uses an internal database (it is usually a Java DB like Derby) to store the missed events.

This is a persistent scheduler.

Note: the application server will generate all missed events at application (re)start. This burst of events is configurable in frequency and delay. See you application server documentation for the details.

We have also the option to not persist the scheduling events which will be lost if application is not running.

In the not persistent case, the scheduler life cycle is the same as the application: it is created at application startup and then destroyed at application shutdown.

On the contrary, a persistent scheduler survives to the application restarts; it is simply sleeping when the application is not running.

How to choose?

If the scheduled functionality is business critical and we cannot afford to miss an event, the persistent scheduler is the way to go.

In all other cases, the not persistent scheduler is lighter (no DB is used) and easier to manage (less hurdle when updating the application because there is no a burst of scheduling events at application restart; the scheduler is always created new at application start ).

2. Will the application run in a cluster?

In a cluster, more than one instance of our application is running (one instance per cluster node) and all instances have their own copy of our scheduler.

But we need to have just one scheduler running among all cluster nodes otherwise we will have multiple copies of the same event.

Every application server has its own way to handle the “multiple scheduler instances” problem (for example see [link 2] for WebSphere) but, in general, it is required that the scheduler should be persistent when we are using a cluster.

3. Should the scheduling interval be programmable at production?

Another important question to be answered: should we able to change the scheduling after the application has been deployed?

If the scheduling parameters (its frequency) are fixed, the automatic scheduler is the best solution because very simple to code: just one annotation (or few XML lines if you prefer the old way).

On the contrary, if the scheduler should be somehow configurable, the best solution is the programmatic scheduler which allow us to define all scheduler parameters during the application startup, reading them from a property file, a DB or any configuration solution we are using.


  • the automatic scheduler schedule is defined at build time
  • the programmatic scheduler schedule is defined at application start time

Automatic scheduler

It’s very easy to define an automatic scheduler:

  1. Create a singleton EJB executed at startup
  2. Create a method which will be invoked at every scheduling event

Note: the complete code can be found in the article project [see link 3].

First step:

public class MyScheduler

The @javax.ejb.Startup annotation asks the EJB container to create the EJB (and so our scheduler) at application startup.

The @javax.ejb.Singleton annotation forces the EJB container to create just one instance.

Important: the scheduler is used by the application server (the EJB container); it should be never instantiated by the rest of the application code.

Then we need the method which will be invoked at scheduling events:

@Schedule(/** scheduling parameters */)
public void doSomeThing() {..}

The method should be public and return void.

The @javax.ejb.Schedule annotation defines:

  • the scheduling interval, in cron format [see link 4]
  • the name of the scheduler (you could have many schedulers in the application)
  • a persistent boolean flag which defines if the scheduler is persistent or not

For example:

    minute = "*/15",
    hour = "*",
    info = "15MinScheduler",
    persistent = false )

which defines a non persistent scheduler which runs every 15 minutes.

See AutomaticPersistentScheduler and AutomaticNonPersistentScheduler classes in the article project [link 3] for a complete example.

Note: there is also the @Schedules annotation [see link 1] which allows the define multiple @Schedule definitions.

It is useful when there are schedule requirements which cannot be expressed in a single cron definition.

Programmatic scheduler

The programmatic scheduler is more complex to build but it give us the complete freedom
to define the scheduler parameters.

We have more steps:

  1. Create a singleton EJB executed at startup
  2. Lookup the TimerService resource
  3. Create the scheduler at EJB initialization
  4. Create a @Timeout method

First step is the same as the automatic scheduler:

public class MyScheduler

Then (second step) we need to lookup the application server timer service but the injection helps us:

private TimerService timerService;

At application startup, the EJB container will inject a TimerService instance which allow us
to interact with the Timer service. For example, we can list (and even delete) all scheduler
defined for the application.

In our case, the Timer service will be used to create the new scheduler as follows (third step):

String minuteSchedule = "*/15";
String hourSchedule = "*";
ScheduleExpression schedule = new ScheduleExpression()

The javax.ejb.ScheduleExpression defines the cron [see link 4] schedule like the @Schedule annotation.

The very important difference between @Schedule and ScheduleExpression is that the first one is fixed at build time: to change the schedule parameters (for example, from every 15min to every 30min) we need to change the class code and build and deploy again the application.

In the latter case (SchedulerExpression), the schedule parameters (in the example above
the variables minuteSchedule and hourSchedule ) can be defined and changed at
application startup, reading the minuteSchedule and hourSchedule from, for example,
a property file or a connected DBMS.

TimerConfig timerConfig = new TimerConfig();

The javax.ejb.TimerConfig gives us the option to define the name of the scheduler (setInfo(String) ) and if it is persistent or not ( setPersistent(boolean) ) .

Using the ScheduleExpression and the TimerConfig instance, we can use the Timer service
to create the scheduler ( a calendar timer, to be more precise).

timerService.createCalendarTimer(schedule, timerConfig);

The createCalendarTime() method returns a javax.ejb.Timer instance which can be used to interrogate the timer like when the next future event will happen or even to destroy
the scheduler.

The last step is to define a method in the class which will be invoked at every scheduling event

public void doSomeThing() {..}

The method should be public and return void.

And we have our scheduler up and running.


Java EE standard give us many options to define a scheduler which runs our code in a periodical and repetitive way. There is no need for additional project dependencies.



  1. Oracle Java EE6 Tutorial on the Timer Service API
  2. IBM WebSphere 8.x Creating timers using the EJB timer service for enterprise beans
  3. Article project on GitHub
  4. Cron on Wikipedia