KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > tc > util > DeepCloneable


1 /**
2  * All content copyright (c) 2003-2006 Terracotta, Inc., except as may otherwise be noted in a separate copyright notice. All rights reserved.
3  */
4 package com.tc.util;
5
6 /**
7  * An object that can be 'deep' cloned &mdash; <em>i.e.</em>, any references to mutable objects are themselves
8  * cloned, rather than shared.
9  * </p>
10  * <p>
11  * Proper implementation of this method is as follows:
12  * <ul>
13  * <li>If your object should never be deep-cloned, simply don't implement this interface. The {@link DeepCloner}will
14  * refuse to deep-clone it, returning an exception to anybody who tries to deep-clone it (or any object graph that
15  * contains a reference to it somewhere).</li>
16  * <li>If your object is immutable (<em>and</em> you know all objects it points to are immutable), simply
17  * <code>return this</code> from your {@link #deepClone(DeepCloner)}method. This is valid because immutable objects
18  * never need to be cloned: the clone would be indistinguishable from the original in all circumstances. (If not, your
19  * object isn't really immutable.</li>
20  * <li>If your object isn't immutable, your {@link #deepClone(DeepCloner)}method should typically do something like
21  * <code>return new Foo(this, cloner)</code> &mdash; that is, create a constructor that takes in an object of the same
22  * type, plus a {@link DeepCloner}, like <code>private Foo(Foo source, DeepCloner cloner)</code>.</li>
23  * <li>This constructor should copy over references to any immutable objects (<em>e.g.</em>, primitive types,
24  * {@link String}s,{@link Date}s, and any user-defined immutable types), and assign a deep-cloned copy to the others
25  * via the {@link DeepCloner#subClone}method &mdash; something like <code>this.bar = cloner.subClone(source.bar)</code>.
26  * </li>
27  * <li>You <strong>MUST NOT</code> call {@link DeepCloner#deepClone}from your 'deep-cloning constructor' directly.
28  * See the documentation for {@link DeepCloner}for details; basically, this breaks object graphs badly that have any
29  * objects with indegree greater than 1 (<em>i.e.</em>, objects to which more than one other object holds a
30  * reference). <strong>THIS IS THE ONE MISTAKE YOU CAN MAKE HERE THAT THE {@link DeepCloner}CANNOT CATCH FOR YOU. YOU
31  * HAVE BEEN WARNED.</li>
32  * </ul>
33  */
34 public interface DeepCloneable {
35
36   /**
37    * Because you cannot create a {@link DeepCloner}yourself, you can't call this method directly. You must either use
38    * {@link DeepCloner#subClone(DeepCloneable)}, or call this from a {@link #deepClone(DeepCloner)}method itself.
39    */
40   Object JavaDoc deepClone(DeepCloner cloner);
41
42 }
Popular Tags