Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h2>The @Immutable Annotation</h2>

<p>Immutable objects are ones which don't change after initial creation. Such objects are frequently desirable because they are simple and can be safely shared even in multi-threading contexts. This makes them great for functional and concurrent scenarios. The rules for creating such objects are well-known:</p>
<ul>
	<li>No mutators (methods that modify internal state)</li>
	<li>Class must be final</li>
	<li>Fields must be private and final</li>
	<li>Defensive copying of mutable components</li>
	<li>equals, hashCode and toString must be implemented in terms of the fields if you want to compare your objects or use them as keys in e.g. maps</li>
</ul>

<p>Writing classes that follow these rules is not hard but does involve a fair bit of boiler plate code and is prone to error. Here is what such a class might look like in Java:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
// Java
public final class Punter {
    private final String first;
    private final String last;

public Punter(String first, String last) {
        this.first = first;
        this.last = last;
    }

public String getFirst() {
        return first;
    }

public String getLast() {
        return last;
    }

@Override
    public int hashCode() {
        final int prime = 31;
        int result = 1;
        result = prime * result + ((first == null)
            ? 0 : first.hashCode());
        result = prime * result + ((last == null)
            ? 0 : last.hashCode());
        return result;
    }

@Override
    public boolean equals(Object obj) {
        if (this == obj)
            return true;
        if (obj == null)
            return false;
        if (getClass() != obj.getClass())
            return false;
        Punter other = (Punter) obj;
        if (first == null) {
            if (other.first != null)
                return false;
        } else if (!first.equals(other.first))
            return false;
        if (last == null) {
            if (other.last != null)
                return false;
        } else if (!last.equals(other.last))
            return false;
        return true;
    }

@Override
    public String toString() {
        return "Punter(first:" + first
            + ", last:" + last + ")";
    }

}
</pre></td></tr></table>

<p>Groovy makes it easier to create such classes using the @Immutable annotation. You only need this:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
@Immutable final class Punter {
    String first, last
}
</pre></td></tr></table>

<p>The &quot;other code&quot; shown above is added at compile time. All of the methods you see above will be there (and you can use them from Java of course). You just don't need to develop and maintain them.</p>

<h3>The Details</h3>

<p>A class created using @Immutable has the following characteristics:</p>
<ul>
	<li>Properties automatically have private, final backing fields with getters.</li>
	<li>Attempts to update the property will result in a <code>ReadOnlyPropertyException</code>.</li>
	<li>A map-based constructor is provided which allows you to set properties by name.</li>
	<li>A tuple-style constructor is provided which allows you to set properties in the same order as they are defined.</li>
	<li>Default <code>equals</code>, <code>hashCode</code> and <code>toString</code> methods are provided based on the property values.</li>
	<li><code>Date</code> objects, <code>Cloneable</code> objects and arrays are defensively copied on the way in (constructor) and out (getters).</li>
	<li>Arrays and cloneable objects use the <code>clone</code> method. For your own classes, it is up to you to define this method and use deep cloning if appropriate.</li>
	<li><code>Collection</code> objects and <code>Map</code> objects are wrapped by immutable wrapper classes (but not deeply cloned!).</li>
	<li>Attempts to update them will result in an <code>UnsupportedOperationException</code>.</li>
	<li>Fields that are enums or other <code>@Immutable</code> classes are allowed but for an otherwise possible mutable property type, an error is thrown.</li>
	<li>You don't have to follow Groovy's normal property conventions, e.g. you can create an explicit private field and then you can write explicit get and set methods. Such an approach, isn't currently prohibited (to give you some wiggle room to get around these conventions) but any fields created in this way are deemed not to be part of the significant state of the object and aren't factored into the <code>equals</code> or <code>hashCode</code> methods. Use at your own risk!</li>
</ul>