Groovy 2.2.1

groovy.transform
[Java] Annotation Type Canonical

java.lang.Object
  groovy.transform.Canonical

@Retention(RetentionPolicy.SOURCE)
@Target({ElementType.TYPE})
@GroovyASTTransformationClass("org.codehaus.groovy.transform.CanonicalASTTransformation")
public @interface Canonical

Class annotation used to assist in the creation of mutable classes.

It allows you to write classes in this shortened form:

 @Canonical class Customer {
     String first, last
     int age
     Date since
     Collection favItems = ['Food']
     def object 
 }
 def d = new Date()
 def anyObject = new Object()
 def c1 = new Customer(first:'Tom', last:'Jones', age:21, since:d, favItems:['Books', 'Games'], object: anyObject)
 def c2 = new Customer('Tom', 'Jones', 21, d, ['Books', 'Games'], anyObject)
 assert c1 == c2
 
You don't need to provide all arguments in constructor calls. If using named parameters, any property names not referenced will be given their default value (as per Java's default unless an explicit initialization constant is provided when defining the property). If using a tuple constructor, parameters are supplied in the order in which the properties are defined. Supplied parameters fill the tuple from the left. Any parameters missing on the right are given their default value.
 def c3 = new Customer(last: 'Jones', age: 21)
 def c4 = new Customer('Tom', 'Jones')

 assert null == c3.since
 assert 0 == c4.age
 assert c3.favItems == ['Food'] && c4.favItems == ['Food']
 
The @Canonical annotation instructs the compiler to execute an AST transformation which adds positional constructors, equals, hashCode and a pretty print toString to your class. There are additional annotations if you only need some of the functionality: @EqualsAndHashCode, @ToString and @TupleConstructor. In addition, you can add one of the other annotations if you need to further customize the behavior of the AST transformation.

A class created in this way has the following characteristics:

If you want similar functionality to what this annotation provides but also require immutability, see the @Immutable annotation.

Limitations:

Authors:
Paulo Poiati
Paul King
See Also:
EqualsAndHashCode
ToString
TupleConstructor
Immutable
Since:
1.8.0


 
Optional Element Summary
java.lang.String excludes

List of field and/or property names to exclude.

java.lang.String includes

List of field and/or property names to include.

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

Element Detail

excludes

public String[] excludes
List of field and/or property names to exclude. Must not be used if 'includes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values. If the @Canonical behavior is customised by using it in conjunction with one of the more specific related annotations (i.e. @ToString, @EqualsAndHashCode or @TupleConstructor), then the value of this attribute can be overriden within the more specific annotation. @default {}


includes

public String[] includes
List of field and/or property names to include. Must not be used if 'excludes' is used. For convenience, a String with comma separated names can be used in addition to an array (using Groovy's literal list notation) of String values. If the @Canonical behavior is customised by using it in conjunction with one of the more specific related annotations (i.e. @ToString, @EqualsAndHashCode or @TupleConstructor), then the value of this attribute can be overriden within the more specific annotation. @default {}


 

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