Immutable Classes in Java

www.marcus-biel.com
MARCUS BIEL,Software Craftsman
Immutables in Java

The concept of Immutability has always been very important
across all programming languages.
Immutables in Java

Immutables in Java
For a Java developer however, Immutable classes,
or simply, "Immutables",

Immutables in Java
have become more important than ever with the release of Java 8.

Immutables in Java
Among many other cool things,
this version introduced the concept of
functional programming as well as the new java.time api.

Immutables in Java
Immutable classes play a key role
in both of these new features.

Immutables in Java
Because of this,
I’ve decided to provide you with
a detailed look at Immutables.

Copyright © 2016 Marcus Bielwww.marcus-biel.com
Outline
•What is an Immutable?
• Advantages & disadvantages
• How to create an Immutable
• When to use Immutables
I'll tell you exactly what an Immutable is,

Outline
• What is an Immutable?
•Advantages & disadvantages
its advantages and disadvantages,

Outline
•How to create an Immutable
and how to create an Immutable.

Outline
•When to use Immutables
I’ll finish by giving you concrete advice on
when to use Immutables in your daily work.

What is an Immutable?
•What is an Immutable?
So let’s start with the most important question –
what is an Immutable class?

In short,
an Immutable class is a class whose instances
cannot be modified.

The information contained in each immutable object
is provided when it is created -

and is frozen for its lifetime.
Once an Immutable object has been created,
it is read only, forever fixed, like a fossil.

USS Enterprise (NCC-1701)
ImmutableSpaceship enterprise = new ImmutableSpaceship("Enterprise");
enterprise.exploreGalaxy();
So if an object is immutable, how can we modify it?

USS Enterprise (NCC-1701)
ImmutableSpaceship enterprise = new ImmutableSpaceship("Enterprise");
enterprise.exploreGalaxy();
How can we change this unchangeable spaceship?
How can we explore strange new worlds and
“boldly go where no man has gone before”?

public ImmutableSpaceship exploreGalaxy() {
return new ImmutableSpaceship(name, Destination.OUTER_SPACE);
}
public final class ImmutableSpaceship {
private final String name;
private final Destination destination;
public ImmutableSpaceship(String name) {
this.name = name;
this.destination = Destination.NONE;
}
private ImmutableSpaceship(String name, Destination destination) {
this.name = name;
this.destination = destination;
}
[…]
}
As it turns out, we can’t. As I've said,
you cannot change an Immutable.
Instead, you can return a new
Object that does reflect the change.

}
this.name = name;
}
this.name = name;
}
[…]
}
In this case we’d return a new
ImmutableSpaceship object with
a new Destination value of “OUTER_SPACE”.

Outline
•Advantages & disadvantages
So far this seems useless.
Why should you bother with Immutables?
What kind of advantages will they bring you?

Advantages of Immutables
• Are stable & fault tolerant
First of all, Immutable classes greatly reduce the
effort needed to implement a stable
and fault tolerant system.

Advantages of Immutables
After object creation,
Immutables can be in only one state,
which seems very confining at first,
but it’s actually extremely beneficial. Let’s see why.

Immutables are stable & fault tolerant
Imagine we have to
implement a bank's accounting software.

As a result of the financial crisis,
the bank doesn't want its customers to be in debt.

In other words,
there is a business rule that
an account balance must never be negative.
Such a rule is called an invariant.

private void validate(long balance) {
if (balance < 0) {
throw new IllegalArgumentException("balance must not be negative:"+ balance);
}
}
To implement this rule,
we will add a validation method that gets called
whenever the balance is changed.

if (balance < 0) {
}
}
In case of an attempt to overdraw the account,

if (balance < 0) {
}
}
an IllegalArgumentException will be thrown.

As you probably can imagine,
the bank wants us to implement
a variety of functions for their clients,

for example
withdraw(), payDebt() and
transferMoney().

public final class ImmutableAccount {
private final long balance;
public ImmutableAccount(long balance) {
this.balance = balance;
}
public ImmutableAccount withdraw(long amount) {…}
public ImmutableAccount payDebt(long amount) {…}
public ImmutableAccount transferMoney(long amount) {…}
[…]
}
To enforce the rule that the account’s
balance must never be negative,
we have to call the validation method from all these methods.

}
[…]
}
This seems like a lot of duplicated code.
There must be a better way!

}
[…]
}
Pause here and think of an
alternative way to make sure
that none of these methods would
overdraw the account’s balance.

}
[…]
}
Okay, the truth is, I tricked you a bit.
We don't actually need to validate the balance in each method.

}
[…]
}
I said we need to validate the object whenever it is changing,
but an Immutable is not changing.

validate(balance);
}
[…]
}
Instead, we validate the balance once in the constructor,
so that no invalid object can be constructed.

validate(balance);
}
[…]
}
Once validated,
an immutable object will stay valid for its entire lifetime.

validate(balance);
}
[…]
} WOW! This is really cool!
Methods like withdraw(), payDebt() and transferMoney()
will return a new object, which will again call
the constructor and validate the new balance.

validate(balance);
}
[…]
}
But wait, it gets even better!
An Immutable remains consistent –
even in the case of an exception.
Let me give you an example:

Imagine you go to the ATM -

- to get some cash.

You put in your bank card, you type in your PIN.

The bank takes the money …

out of your account.
But just before it gets into your hands,

there’s an issue with the ATM.
The money has already been taken out of your bank account,
but it isn’t coming out of the machine.

So now, you can kiss your money good bye.

Unless the account has been implemented as an
Immutable.

In this case, your balance will be in the same state
that it was before the failure occurred.
Let’s see what this looks like in code.

validate(balance);
}
public ImmutableAccount withdraw(long amount) {
long newBalance = newBalance(amount);
return new ImmutableAccount(newBalance);
}
private long newBalance(long amount) {
}
[…]
}
If we are trying to withdraw money from our
ImmutableAccount class,

validate(balance);
}
}
// exception during balance calculation
}
[…]
}
and an exception occurs,

validate(balance);
}
}
}
[…]
}
a new ImmutableAccount object will never be created and
the original bank account object will
stay unchanged and be saved.

validate(balance);
}
}
}
[…]
}
So as I’ve shown you,
an Immutable object can never get into an inconsistent state,
even in the case of an exception.

validate(balance);
}
}
}
[…]
}
This stability comes at no cost,
apart from the cost of the initial validation.

validate(balance);
}
}
}
[…]
}
It's based on the simple fact that
an Immutable cannot change after object creation.

validate(balance);
}
}
}
[…]
}
Ok, I hope you haven't fallen asleep yet.
There is so much more that Immutables have to offer,
so let’s go on.

Immutables can be shared freely
• Can be shared freely
Since Immutables don’t change,
they can be shared freely. Let’s see what this means.

Balance
AccountAccount
Holder HolderBalance
In this example,
two Mutable Account objects are
sharing the same Balance attribute.

AccountAccount
If the Account object on the right

AccountAccount
changes the balance,
this will also indirectly influence the Account object on the left.

AccountAccount
If, however, the balance attribute is immutable,

Holder
Account
Account
Holder
Balan
ce
Balance
when the Account object on the right tries to
change the balance object, it will not change,

Account
Balance Holder
Account
Holder Balance
but return a new object instead.
So there will be a second balance object now.

Account
Balance Holder
Account
Holder Balance
For the same reason - an Immutable does not need a
copy constructor when copying an object.

If you don’t understand what this means or
you’d like to learn more about
cloning and copy constructors,
check out my video “Shallow versus Deep Copy”.
http://www.marcus-biel.com/shallow-vs-deep-copy-video-tutorial/

Immutables can even be shared freely,
when using a lock free algorithm in
a multithreaded environment,
where multiple actions happen in parallel.

Many see this as the key benefit of Immutables.
However, it is a very advanced subject,
so I won't go into detail here,
but will probably show it at a later stage.

Immutables work well as Map keys and Set elements
• Work well as Map keys and Set elements
Finally, Immutable objects are also a perfect option
to use as Map keys and Set elements,
since Map keys and Set elements must never change.

Immutables work well as Map keys and Set elements
These are the main advantages of Immutables.
Let’s also look at their disadvantages.

Disadvantages of Immutables
• May lead to performance problems
The biggest disadvantage of Immutable classes is that
their use may lead to performance problems.
Let's see how.

Immutables may lead to performance problems
Object
Immutables require a new object

for every distinct state they represent.

Therefore, the use of Immutables often
increases the number of objects created.

Naturally, the more objects that are created,
the more system resources will be used.

However, this may not be a problem at all.
There are many more influencing factors
as we will see later on.

How to create an Immutable
So now that I’ve shown the value of an Immutable class.
How can we actually make one?

How to create an Immutable
To make a class immutable,
we have to follow a few rules:

1. Make all attributes private final
1. Make all attributes private final.
First of all,
we have to make all its attributes private and final

this.name = name;
}
this.name = name;
}
}
[…]
}
Let’s illustrate this by looking at the
ImmutableSpaceship class I introduced you to before.

this.name = name;
}
this.name = name;
}
}
[…]
}
We make the attributes private,
so that no reference can be accessed from outside.

this.name = name;
}
this.name = name;
}
}
[…]
}
While private variables cannot be
accessed from outside the class,
they can still be reassigned.

this.name = name;
}
this.name = name;
}
}
[…]
}
To prevent this we also have to make all variables final.

this.name = name;
}
this.name = name;
}
}
[…]
}
Setting all internal reference variables to final –
clearly communicates our intent to make an immutable class.

this.name = name;
}
this.name = name;
}
}
[…]
}
Should someone try to reassign a reference variable,
a compiler error will occur.

2. Don’t provide any methods that modify the object’s state
1. Make all attributes private and final.
2. Don’t provide any methods that modify the
object’s state.
Okay. Second,
we must not provide any methods
that modify the object’s state.

object’s state.
This I have already briefly discussed
at the beginning of this presentation,
but now we will look at it more closely.

}
this.name = name;
}
this.name = name;
}
[…]
}
For any change that you want to apply
to your Immutable object,
you have to provide a method that returns a new object.

}
this.name = name;
}
this.name = name;
}
[…]
}
Attributes that do not change, like “name” in this case,
can be copied from our current object.

}
this.name = name;
}
this.name = name;
}
[…]
}
Attributes that do change, like “destination” in this case,
have to be initialized with a new value instead.

3. Ensure that the class can’t be extended
object’s state.
3. Ensure that the class can’t be extended.
Let’s go on to the next rule.
To further protect our class from being changed,
we also have to prevent it from being extended.

object’s state.
Extending a class would allow you to override its methods.
This would allow you to directly change the
“unchangeable" object.

object’s state.
Let's look at a code example to better illustrate this:

public class RomulanSpaceship extends ImmutableSpaceship {
@Override
public RomulanSpaceship exploreGalaxy() {
this.destination = Destination.OUTER_SPACE;
return this;
}
[…]
}
private String name;
private Destination destination;
public RomulanSpaceship(String name) {
super(name);
}
So here we have a RomulanSpaceship
extending our ImmutableSpaceship.

@Override
public RomulanSpaceship exploreGalaxy() {
this.destination = Destination.NEUTRAL_ZONE;
return this;
}
public class RomulanSpaceship extends ImmutableSpaceship {
[…]
}
private String name;
private Destination destination;
public RomulanSpaceship(String name) {
super(name);
}
Its overridden exploreGalaxy() method
violates the rules of an Immutable,
as it directly changes the destination attribute.

ImmutableSpaceship immutableSpaceship = new RomulanSpaceship("Battlequeen");
As RomulanSpaceship extends ImmutableSpaceship

we can create an instance of a RomulanSpaceship,

and assign it to an ImmutableSpaceship
reference variable.

[…]
immutableSpaceship.exploreGalaxy(); // internally changes the "immutable" Spaceship
Much later in the code, in a different class and method,
we will call the exploreGalaxy() method
on our ImmutableSpaceship instance -

[…]
immutableSpaceship.exploreGalaxy(); // internally changes the "immutable" Spaceship
which, much to our concern,
will internally change the spaceship instance,
which we expected to be unchangeable.

this.name = name;
}
this.name = name;
}
}
[…]
} To prevent this, we just have to make our class final.
A final class can’t be extended,
so it won’t be possible to override any method either.

4. Ensure exclusive access to any mutable attributes
2. Don’t provide any methods that modify the object’s
state.
4. Ensure exclusive access to any mutable attributes.
And now to the final rule –
we have ensure exclusive access to any mutable attributes.

Here you can see a
representation of our spaceship object.
Name
Spaceship
DestinationName
Immutable

The attribute “name” is of type String,
which is an Immutable.
Name
Spaceship
DestinationName
Immutable

As I've already shown you,
you can freely share Immutable attributes -
Name
Spaceship
DestinationName
Immutable

Name
Spaceship
DestinationName
Immutable
Mutable
with other objects, as they cannot be changed.

Spaceship
DestinationName
Immutable
The Destination object, in this case,
we’ll assume, is Mutable.

Spaceship
DestinationName
Immutable
Mutable
Anyone who holds a reference to it -

Spaceship
DestinationName
Immutable
Mutable
can alter it.

Immutable
Mutable
This will effectively alter our "Immutable" object.

Mutable
In other words, it would not be immutable.

Mutable
So to protect our Immutable object -

Mutable
Spaceship
DestinationName
Immutable
we have to isolate the mutable destination attribute from
the outside and prevent anyone from getting hold of it.

Spaceship
DestinationName
Immutable
Destination
Mutable
To achieve this, we never obtain or
return a direct reference to a destination object.
Instead we create a deep copy and work with that instead.

Spaceship
DestinationName
Immutable
DestinationDestination
Mutable
As long as the mutable destination object
is never directly shared,

Spaceship
DestinationName
Immutable
Mutable
a change inside an external object will not
have any effect on our immutable object.

Spaceship
DestinationName
Immutable
Mutable
Okay, talk is cheap, show me the code.

public ImmutableSpaceship newDestination(Destination newDestination) {
return new ImmutableSpaceship(this.name, newDestination);
}
public Destination currentDestination() {
return destination;
}
this.name = name;
this.destination = new Destination("NONE");
}
this.name = name;
}
[…]
}
To ensure exclusive access to
our mutable destination attribute,

}
return destination;
}
this.name = name;
}
this.name = name;
}
[…]
}
we have to check all public methods and
constructors for any
incoming or outgoing Destination references.

}
return destination;
}
this.name = name;
}
this.name = name;
}
[…]
}
Let’s do this now.

}
return destination;
}
this.name = name;
}
this.name = name;
}
[…]
}
The public constructor does not
receive any Destination reference.

}
return destination;
}
this.name = name;
}
this.name = name;
}
[…]
}
The Destination object it creates is safe,
as it cannot be accessed from outside.
So the public constructor is good as it is.

}
return destination;
}
this.name = name;
}
this.name = name;
}
[…]
}
The public currentDestination()
method returns a reference -

}
return destination;
}
this.name = name;
}
this.name = name;
}
[…]
}
to our internal Destination object, so this must be fixed.

}
return new Destination(destination);
}
this.name = name;
}
this.name = name;
}
[…]
}
Now, instead of returning the real
reference we create a deep copy
of our Destination object and return
a reference to the copy instead.

}
}
this.name = name;
}
this.name = name;
}
[…]
}
Finally,
the public newDestination() method receives -

}
}
this.name = name;
}
this.name = name;
}
[…]
}
a Destination reference -

}
}
this.name = name;
}
this.name = name;
}
[…]
}
and forwards this reference to our private constructor.

}
}
this.name = name;
}
this.name = name;
}
[…]
}
Now the private constructor directly stores the
mutable Destination reference it receives.

}
}
this.name = name;
}
this.name = name;
}
[…]
}
So, by following the execution path,
we found that it is directly stored in the private constructor.

}
}
this.name = name;
}
this.name = name;
}
[…]
}
This must not be allowed.

}
}
this.name = name;
}
this.name = name;
this.destination = new Destination(destination);
}
[…]
}
To stop it immediately,
we store a reference to a deep copy
of the external Destination object.

When to use Immutables
•When to use Immutables
Okay. So I've shown you what an Immutable is,
I've told you about its advantages and disadvantages,
and finally, I have demonstrated
how to create an Immutable class.

There is just one last thing I would like
to tell you –
When should YOU actually use an
Immutable class in your code?

The question of whether you should
design a specific class as an Immutable
depends mainly on whether the
performance of the overall system is
sufficient or not.

This again depends on the nature of the
system and all aspects related to it.
For example: What kind of specific
problem are you trying to solve?

On what kind of hardware is your
program running? Is it a desktop or
web application? It also depends on
the internal structure of your code.

For example: Of how many packages,
classes and methods does your code
consist of? As you can see, there is no
simple answer to this very complex
question.

Each case must be looked at
individually.
As a general recommendation however,
I advise you to follow this approach:
Focus on designing a system that uses
immutables to the greatest possible
extent.

Facilitate their use by designing simple
classes with few attributes and
methods.
Immutables may become a burden
when they are too complex.
Simplicity is key.

In this endeavor, Clean Code and
Immutables are a well matched pair,
reinforcing each other.

In the majority of cases,
this approach will lead to a system that
exceeds all requirements.

If however, testing reveals that
you have not achieved satisfactory
performance, relax the immutability
rules gradually.

As much as necessary,
but as little as possible.

Immutable Classes in Java

More Related Content

Viewers also liked

Similar to Immutable Classes in Java

Recently uploaded

Immutable Classes in Java