Overview | Package | Class | Deprecated | Index | Help
| Groovy 1.7.0
| FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT

## groovy.lang
Annotation Type Immutable

    java.lang.Object
      groovy.lang.Immutable

    @Retention(RetentionPolicy.RUNTIME)
    @Target({ElementType.TYPE})
    @GroovyASTTransformationClass("org.codehaus.groovy.transform.ImmutableASTTransformation")
    @interface Immutable

Class annotation used for making a class immutable.

It allows you to write code snippets like this:

     @Immutable class Customer {
         String first, last
         int age
         Date since
         Collection favItems
     }
     def d = new Date()
     def c1 = new Customer(first:'Tom', last:'Jones', age:21, since:d, favItems:['Books', 'Games'])
     def c2 = new Customer('Tom', 'Jones', 21, d, ['Books', 'Games'])
     assert c1 == c2

A class created in this way has the following characteristics:

- The class is automatically made final if not already final.
- 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. Though not normally required, you may write your own implementations of these methods. For `equals` and `hashCode`, if you do write your own method, it is up to you to obey the general contract for `equals` methods and supply a corresponding matching `hashCode` method. If you do provide one of these methods explicitly, the default implementation will be made available in a private "underscore" variant which you can call. E.g., you could provide a (not very elegant) multi-line formatted `toString` method for `Customer` above as follows:

           String toString() {
              _toString().replaceAll(/\(/, '(\n\t').replaceAll(/\)/, '\n)').replaceAll(/, /, '\n\t')
          }

  If an "underscore" version of the respective method already exists, then no default implementation is provided.
- `Date`s, `Cloneable`s 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`s and `Map`s 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!

Such classes are particularly useful for functional and concurrent styles of programming and for use as key values within maps.

Limitations:

- As outlined above, 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.
- As outlined above, `Collection`s and `Map`s are wrapped by immutable wrapper classes (but not deeply cloned!).
- Currently `BigInteger` and {#code BigDecimal} are deemed immutable but see: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6348370
- `java.awt.Color` is treated as immutable but is not final so while not normally used with child classes, it isn't strictly immutable. Use at your own risk.
- `java.util.Date` is treated as immutable but is not final so it isn't strictly immutable. Use at your own risk.

author:
  Paul King

Method Summary

Methods inherited from class Object
wait, wait, wait, hashCode, getClass, equals, toString, notify, notifyAll

Copyright © 2003-2009 The Codehaus. All rights reserved.