Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The "other code" 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.

The Details

A class created using @Immutable has the following characteristics:

  • Properties automatically have private, final backing fields with getters.
  • Attempts to update the property will result in a ReadOnlyPropertyException.
  • A map-based constructor is provided which allows you to set properties by name.
  • A tuple-style constructor is provided which allows you to set properties in the same order as they are defined.
  • Default equals, hashCode and toString methods are provided based on the property values.
  • Date objects, Cloneable objects and arrays are defensively copied on the way in (constructor) and out (getters).
  • Arrays and cloneable objects use the clone method. For your own classes, it is up to you to define this method and use deep cloning if appropriate.
  • Collection objects and Map objects are wrapped by immutable wrapper classes (but not deeply cloned!).
  • Attempts to update them will result in an UnsupportedOperationException.
  • Fields that are enums or other @Immutable classes are allowed but for an otherwise possible mutable property type, an error is thrown.
  • 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 equals or hashCode methods. Use at your own risk!