Cloner (jMonkeyEngine3)

java.lang.Object
- com.jme3.util.clone.Cloner

```
public class Cloner
extends java.lang.Object
```
A deep clone utility that provides similar object-graph-preserving qualities to typical serialization schemes. An internal registry of cloned objects is kept to be used by other objects in the deep clone process that implement JmeCloneable.
By default, objects that do not implement JmeCloneable will be treated like normal Java Cloneable objects. If the object does not implement the JmeCloneable or the regular JDK Cloneable interfaces AND has no special handling defined then an IllegalArgumentException will be thrown.

Enhanced object cloning is done in a two step process. First, the object is cloned using the normal Java clone() method and stored in the clone registry. After that, if it implements JmeCloneable then its cloneFields() method is called to deep clone any of the fields. This two step process has a few benefits. First, it means that objects can easily have a regular shallow clone implementation just like any normal Java objects. Second, the deep cloning of fields happens after creation which means that the clone is available to future field cloning to resolve circular references.

Similar to Java serialization, the handling of specific object types can be customized. This allows certain objects to be cloned gracefully even if they aren't normally Cloneable. This can also be used as a sort of filter to keep certain types of objects from being cloned. (For example, adding the IdentityCloneFunction for Mesh.class would cause all mesh instances to be shared with the original object graph.)

By default, the Cloner registers several default clone functions as follows:
- java.util.ArrayList: ListCloneFunction
- java.util.LinkedList: ListCloneFunction
- java.util.concurrent.CopyOnWriteArrayList: ListCloneFunction
- java.util.Vector: ListCloneFunction
- java.util.Stack: ListCloneFunction
- com.jme3.util.SafeArrayList: ListCloneFunction
Usage:
```
  // Example 1: using an instantiated, reusable cloner.
  Cloner cloner = new Cloner();
  Foo fooClone = cloner.clone(foo);
  cloner.clearIndex(); // prepare it for reuse
  Foo fooClone2 = cloner.clone(foo);

  // Example 2: using the utility method that self-instantiates a temporary cloner.
  Foo fooClone = Cloner.deepClone(foo);

  
```

Constructor Summary

Constructors
Constructor and Description

Cloner()
Creates a new cloner with only default clone functions and an empty object index.

Constructors
Constructor and Description
`Cloner()` Creates a new cloner with only default clone functions and an empty object index.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected <T> T`	`arrayClone(T object)` Clones a primitive array by coping it and clones an object array by coping it and then running each of its values through Cloner.clone().
`void`	`clearIndex()` Clears the object index allowing the cloner to be reused for a brand new cloning operation.
`<T> T`	`clone(T object)` Deeps clones the specified object, reusing previous clones when possible.
`<T> T`	`clone(T object, boolean useFunctions)` Deeps clones the specified object, reusing previous clones when possible.
`static <T> T`	`deepClone(T object)` Convenience utility function that creates a new Cloner, uses it to deep clone the object, and then returns the result.
`<T> CloneFunction<T>`	`getCloneFunction(java.lang.Class<T> type)` Returns a previously registered clone function for the specified type or null if there is no custom clone function for the type.
`boolean`	`isCloned(java.lang.Object o)` Returns true if the specified object has already been cloned by this cloner during this session.
`<T> T`	`javaClone(T object)` Performs a raw shallow Java clone using reflection.
`<T> void`	`setClonedValue(T original, T clone)` Forces an object to be added to the indexing cache such that attempts to clone the 'original' will always result in the 'clone' being returned.
`<T> void`	`setCloneFunction(java.lang.Class<T> type, CloneFunction<T> function)` Sets a custom CloneFunction for implementations of the specified Java type.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Cloner
```
public Cloner()
```
    Creates a new cloner with only default clone functions and an empty object index.
- Method Detail
  - deepClone
```
public static <T> T deepClone(T object)
```
    Convenience utility function that creates a new Cloner, uses it to deep clone the object, and then returns the result.
  - clone
```
public <T> T clone(T object)
```
    Deeps clones the specified object, reusing previous clones when possible.
    Object cloning priority works as follows:
    - If the object has already been cloned then its clone is returned.
    - If there is a custom CloneFunction then it is called to clone the object.
    - If the object implements Cloneable then its clone() method is called, arrays are deep cloned with entries passing through clone().
    - If the object implements JmeCloneable then its cloneFields() method is called on the clone.
    - Else an IllegalArgumentException is thrown.
    Note: objects returned by this method may not have yet had their cloneField() method called.
  - clone
```
public <T> T clone(T object,
                   boolean useFunctions)
```
    Deeps clones the specified object, reusing previous clones when possible.
    Object cloning priority works as follows:
    - If the object has already been cloned then its clone is returned.
    - If useFunctions is true and there is a custom CloneFunction then it is called to clone the object.
    - If the object implements Cloneable then its clone() method is called, arrays are deep cloned with entries passing through clone().
    - If the object implements JmeCloneable then its cloneFields() method is called on the clone.
    - Else an IllegalArgumentException is thrown.
    The ability to selectively use clone functions is useful when being called from a clone function.
    Note: objects returned by this method may not have yet had their cloneField() method called.
  - setCloneFunction
```
public <T> void setCloneFunction(java.lang.Class<T> type,
                                 CloneFunction<T> function)
```
    Sets a custom CloneFunction for implementations of the specified Java type. Some inheritance checks are made but no disambiguation is performed.
    Note: in the general case, it is better to register against specific classes and not super-classes or super-interfaces unless you know specifically that they are cloneable.
    
    By default ListCloneFunction is registered for ArrayList, LinkedList, CopyOnWriteArrayList, Vector, Stack, and JME's SafeArrayList.
  - getCloneFunction
```
public <T> CloneFunction<T> getCloneFunction(java.lang.Class<T> type)
```
    Returns a previously registered clone function for the specified type or null if there is no custom clone function for the type.
  - setClonedValue
```
public <T> void setClonedValue(T original,
                               T clone)
```
    Forces an object to be added to the indexing cache such that attempts to clone the 'original' will always result in the 'clone' being returned. This can be used to stub out specific values from being cloned or to force global shared instances to be used even if the object is cloneable normally.
  - isCloned
```
public boolean isCloned(java.lang.Object o)
```
    Returns true if the specified object has already been cloned by this cloner during this session. Cloned objects are cached for later use and it's sometimes convenient to know if some objects have already been cloned.
  - clearIndex
```
public void clearIndex()
```
    Clears the object index allowing the cloner to be reused for a brand new cloning operation.
  - javaClone
```
public <T> T javaClone(T object)
                throws java.lang.CloneNotSupportedException
```
    Performs a raw shallow Java clone using reflection. This call does NOT check against the clone index and so will return new objects every time it is called. That's because these are shallow clones and have not (and may not ever, depending on the caller) get resolved.
    This method is provided as a convenient way for CloneFunctions to call clone() and objects without necessarily knowing their real type.
    
    Throws:
    
    java.lang.CloneNotSupportedException
  - arrayClone
```
protected <T> T arrayClone(T object)
```
    Clones a primitive array by coping it and clones an object array by coping it and then running each of its values through Cloner.clone().

Class Cloner

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Cloner

Method Detail

deepClone

clone

clone

setCloneFunction

getCloneFunction

setClonedValue

isCloned

clearIndex

javaClone

arrayClone