|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT | ||||||||
@Retention(value=RUNTIME) @Target(value=TYPE) public @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:
ReadOnlyPropertyException.
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.
Dates, Cloneables 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.
Collections and Maps are wrapped by immutable wrapper classes (but not deeply cloned!).
Attempts to update them will result in an UnsupportedOperationException.
@Immutable classes are allowed but for an
otherwise possible mutable property type, an error is thrown.
equals or hashCode methods.
Use at your own risk!
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.
Collections and Maps are wrapped by immutable wrapper classes (but not deeply cloned!).
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.
|
Copyright © 2003-2009 The Codehaus. All rights reserved. | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT | ||||||||