@Documented
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
@GroovyASTTransformationClass("org.codehaus.groovy.transform.AutoCloneASTTransformation")
public @interface AutoClone

Class annotation used to assist in the creation of Cloneable classes. The @AutoClone annotation instructs the compiler to execute an AST transformation which adds a public clone() method and adds Cloneable to the list of interfaces which the class implements.

Because the JVM doesn't have a one-size fits all cloning strategy, several customizations exist for the cloning implementation. By default, the clone() method will call super.clone() before calling clone() on each Cloneable property of the class.

Example usage:

 import groovy.transform.AutoClone
 @AutoClone
 class Person {
   String first, last
   List favItems
   Date since
 }
 

 class Person implements Cloneable {
   ...
   public Person clone() throws CloneNotSupportedException {
     Person result = (Person) super.clone()
     result.favItems = favItems instanceof Cloneable ? (List) favItems.clone() : favItems
     result.since = (Date) since.clone()
     return result
   }
   ...
 }
 

 def p = new Person(first:'John', last:'Smith', favItems:['ipod', 'shiraz'], since:new Date())
 def p2 = p.clone()

 assert p instanceof Cloneable
 assert p.favItems instanceof Cloneable
 assert p.since instanceof Cloneable
 assert !(p.first instanceof Cloneable)

 assert !p.is(p2)
 assert !p.favItems.is(p2.favItems)
 assert !p.since.is(p2.since)
 assert p.first.is(p2.first)
 

If your classes require deep cloning, it is up to you to provide the appropriate deep cloning logic in the respective clone() method for your class.

If one of your properties contains an object that doesn't support cloning or attempts deep copying of a data structure containing an object that doesn't support cloning, then a CloneNotSupportedException may occur at runtime.

Another popular cloning strategy is known as the copy constructor pattern. If any of your fields are final and Cloneable you should set style=COPY_CONSTRUCTOR which will then use the copy constructor pattern. Here is an example making use of the copy constructor pattern:

 import groovy.transform.AutoClone
 import static groovy.transform.AutoCloneStyle.*
 @AutoClone(style=COPY_CONSTRUCTOR)
 class Person {
   final String first, last
   final Date birthday
 }
 @AutoClone(style=COPY_CONSTRUCTOR)
 class Customer extends Person {
   final int numPurchases
   final List favItems
 }
 

 class Person implements Cloneable {
   ...
   protected Person(Person other) throws CloneNotSupportedException {
     first = other.first
     last = other.last
     birthday = (Date) other.birthday.clone()
   }
   public Person clone() throws CloneNotSupportedException {
     return new Person(this)
   }
   ...
 }
 class Customer extends Person {
   ...
   protected Customer(Customer other) throws CloneNotSupportedException {
     super(other)
     numPurchases = other.numPurchases
     favItems = other.favItems instanceof Cloneable ? (List) other.favItems.clone() : other.favItems
   }
   public Customer clone() throws CloneNotSupportedException {
     return new Customer(this)
   }
   ...
 }
 

As a variation of the last two styles, if you set style=SIMPLE then the no-arg constructor will be called followed by setting the individual properties (and/or fields) calling clone() if the property/field implements Cloneable. Here is an example:

 import groovy.transform.AutoClone
 import static groovy.transform.AutoCloneStyle.*
 @AutoClone(style=SIMPLE)
 class Person {
   final String first, last
   final Date birthday
 }
 @AutoClone(style=SIMPLE)
 class Customer {
   final List favItems
 }
 

 class Person implements Cloneable {
   ...
   public Person clone() throws CloneNotSupportedException {
     def result = new Person()
     copyOrCloneMembers(result)
     return result
   }
   protected void copyOrCloneMembers(Person other) {
     other.first = first
     other.last = last
     other.birthday = (Date) birthday.clone()
   }
   ...
 }
 class Customer extends Person {
   ...
   public Customer clone() throws CloneNotSupportedException {
     def result = new Customer()
     copyOrCloneMembers(result)
     return result
   }
   protected void copyOrCloneMembers(Customer other) {
     super.copyOrCloneMembers(other)
     other.favItems = favItems instanceof Cloneable ? (List) favItems.clone() : favItems
   }
   ...
 }
 

As a final example, if your class already implements the Serializable or Externalizable interface, you can choose the following cloning style:

 @AutoClone(style=SERIALIZATION)
 class Person implements Serializable {
   String first, last
   Date birthday
 }
 

 class Person implements Cloneable, Serializable {
   ...
   Person clone() throws CloneNotSupportedException {
     def baos = new ByteArrayOutputStream()
     baos.withObjectOutputStream{ it.writeObject(this) }
     def bais = new ByteArrayInputStream(baos.toByteArray())
     bais.withObjectInputStream(getClass().classLoader){ (Person) it.readObject() }
   }
   ...
 }
 

Further references on cloning:

• http://www.codeguru.com/java/tij/tij0128.shtml
• http://www.artima.com/objectsandjava/webuscript/ClonCollInner1.html
• http://courses.dce.harvard.edu/~cscie160/JDCTipsCloning
• http://www.agiledeveloper.com/articles/cloning072002.htm

See Also:

AutoCloneStyle

ExternalizeMethods

Since:

1.8.0