BasicCloner (Jadira Framework Parent 7.0.0.CR1 API)

java.lang.Object
- org.jadira.reflection.cloning.BasicCloner

All Implemented Interfaces:

CloneDriver, CloneImplementor, Cloner
```
public class BasicCloner
extends Object
implements Cloner, CloneDriver, CloneImplementor
```
This class is for performing deep clones.
Inspired by the Rits Deep Cloning API, this library uses Unsafe to provide maximum performance and a variety of extensibility and annotation configuration strategies. Most users will interact with the cloning library via this class and the Cloner interface. This is the most functional Cloner implementation built in to Jadira Cloning. The alternative, MinimalCloner is recommended for situations where only basic deep-cloning functionality is required and maximum throughput desirable.
BasicCloner is a fully configurable cloning implementation.
The class features two pluggable CloneStrategy, with implementations available in the library. UnsafeCloneStrategy makes use of sun.misc.Unsafe and delivers fast performance, particularly when using Server VMs with Java 6 and later. However, it requires sun.misc.Unsafe to be available. VMs providing this class include Oracle and IBM's JVMs. A fully functional Unsafe implementation is not available on Android. For platforms where UnsafeCloneStrategy is not suitable, PortableCloneStrategy should be used instead. In general this delivers good, but lower performance, giving about half the cloning throughput. Functionality however it is identical. If you use the PortableCloneStrategy, Objenesis must be included on the classpath.
There are a variety of ways to customise cloning. This class can be configured with CloneImplementors which can be implemented to override the normal cloning behaviour for particular classes. Using these, must be enabled by setting useCloneImplementors if required to be used.
Specific classes can be indicated as being immutable and/or non-cloneable - these classes do not need to be copied during the clone. Cloning of immutables can be disabled or enabled using setCloneImmutable(boolean), whilst non-cloneable classes may never be cloned.
Setting cloneTransientFields to false will prevent the cloning of transient fields which will be set to their null (or default primitive) values instead of being cloned.
BasicCloner can detect classes that implement Cloneable and invoke their clone() method. To enable this function, set useCloneable.
Finally, the operation of the class can be customised using annotations. Cloneable annotation can be used to customise the treatment of particular classes being cloned. @Cloner can be used to specify a particular method within a class to be used to fulfil the clone for that specific class. NonCloneable indicates that a class should not be cloned. Finally Transient annotation can be used on any class field to indicate that the field is transient. In the case of this last annotation, use {cloneTransientAnnotatedFields to enable or disable the capability (by default these fields are not cloned).
Immutable or Immutable provide an alternative mechanism for indicating that a class is immutable.
If the Mutability Detector library is on the classpath this will automatically be used to determine immutability for all classes being cloned. If a class is identified as IMMUTABLE or EFFECTIVELY_IMMUTABLE by Mutability Detector it will be treated as immutable.

See Also:

A most optimised implementation of Cloner that only provides basic deep cloning functionality but no configurability.

Constructor Summary

Constructors
Constructor and Description
`BasicCloner()` Create a new instance with `UnsafeCloneStrategy`, unless it is not available in which case `PortableCloneStrategy` will be used.
`BasicCloner(CloneStrategy cloneStrategy)` Creates a new instance with the given `CloneStrategy`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`canClone(Class<?> clazz)` True if this implementor can clone the given class
`<T> T`	`clone(T obj)` Clones the supplied object
`<T> T`	`clone(T obj, CloneDriver context, IdentityHashMap<Object,Object> referencesToReuse, long stackDepth)` Performs a clone.
`CloneImplementor`	`getAnnotationImplementor(Class<?> clazz)` Retrieves the registered implementor for the given class
`CloneImplementor`	`getBuiltInImplementor(Class<?> clazz)` Gets the built in implementor for the given class
`MethodHandle`	`getCloneMethod(Class<?> clazz)` Returns the clone() method for the indicated class
`Set<Class<?>>`	`getImmutableClasses()` A list of classes that should be treated as immutable.
`CloneImplementor`	`getImplementor(Class<?> clazz)` Retrieves the registered implementor for the given class
`Set<Class<?>>`	`getNonCloneableClasses()` A list of classes that should not be cloned.
`void`	`initialiseFor(Class<?> classes)` This method is included simply so that cold starts can be avoided.
`boolean`	`isCloneImmutable()` If false, indicates that classes known to be immutable should be not cloned.
`boolean`	`isCloneSyntheticFields()` Indicates whether synthetic fields should be cloned
`boolean`	`isCloneTransientAnnotatedFields()` If false, indicates that fields annotated by the `Transient` annotation should not be cloned, instead being replaced with null.
`boolean`	`isCloneTransientFields()` If false, indicates that fields modified by the transient keyword should not be cloned, instead being replaced with null.
`boolean`	`isImmutableInstance(Object instance)` Indicates whether the given object instance should be treated as immutable
`boolean`	`isTrackReferences()` Indicates whether to track references
`boolean`	`isTrackReferencesForFlatClasses()` Indicates whether to also track references for flat classes when tracking references.
`boolean`	`isUseCloneable()` If true, then any class that implements `Cloneable` will be cloned using the `Object.clone()` method.
`boolean`	`isUseCloneImplementors()` Indicates whether custom clone implementors are enabled
`<T> T`	`newInstance(Class<T> c)` Create a new, uninitialised instance of the given class (if supported).
`void`	`putAnnotationImplementor(Class<?> clazz, CloneImplementor implementor)` Put the registered implementor for the given class
`void`	`putCloneMethod(Class<?> clazz, MethodHandle handle)` Put the clone() method for the indicated class
`void`	`putImmutableInstance(Object instance)` Stores an object instance to be treated as immutable
`void`	`setCloneImmutable(boolean cloneImmutable)` If true, immutable classes should be cloned.
`void`	`setCloneSyntheticFields(boolean cloneSyntheticFields)` If true, synthetic fields should be cloned
`void`	`setCloneTransientAnnotatedFields(boolean cloneTransientAnnotatedFields)` If true, fields annotated with @Transient should be cloned
`void`	`setCloneTransientFields(boolean cloneTransientFields)` If true, fields marked with the transient keyword should be cloned
`void`	`setImmutableClasses(Set<Class<?>> immutableClasses)` Indicates classes which are immutable.
`void`	`setImplementors(Map<Class<?>,CloneImplementor> implementors)` Sets CloneImplementors to be used.
`void`	`setNonCloneableClasses(Set<Class<?>> nonCloneableClasses)` Indicates classes that are not Cloneable.
`void`	`setTrackReferences(boolean trackReferences)` If false, do not track references so that objects are reused if they appear twice
`void`	`setTrackReferencesForFlatClasses(boolean trackReferencesForFlatClasses)` If false, do not track references for flat classes when tracking references
`void`	`setUseCloneable(boolean useCloneable)` If true, the clone() method of classes implementing `Cloneable` will be delegated to where appropriate
`void`	`setUseCloneImplementors(boolean useCloneImplementors)` If true, cloning may be delegates to clone implementors for specific tasks.

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

- Constructor Detail
  - BasicCloner
```
public BasicCloner()
```
    Create a new instance with UnsafeCloneStrategy, unless it is not available in which case PortableCloneStrategy will be used.
  - BasicCloner
```
public BasicCloner(CloneStrategy cloneStrategy)
```
    Creates a new instance with the given CloneStrategy
    
    Parameters:
    
    cloneStrategy - CloneStrategy to be used
- Method Detail
  - clone
```
public <T> T clone(T obj)
```
    Description copied from interface: Cloner
    
    Clones the supplied object
    
    Specified by:
    
    clone in interface Cloner
    
    Type Parameters:
    
    T - The class of the object to be cloned
    
    Parameters:
    
    obj - The object
    
    Returns:
    
    A clone of the object
  - newInstance
```
public <T> T newInstance(Class<T> c)
```
    Description copied from interface: CloneImplementor
    
    Create a new, uninitialised instance of the given class (if supported). Depending on strategy, this may or may not initialise instance fields, and may or may not invoke constructors.
    
    Specified by:
    
    newInstance in interface CloneImplementor
    
    Type Parameters:
    
    T - The type of the instance to be constructed
    
    Parameters:
    
    c - Type to create instance of
    
    Returns:
    
    The new instance
  - canClone
```
public boolean canClone(Class<?> clazz)
```
    Description copied from interface: CloneImplementor
    
    True if this implementor can clone the given class
    
    Specified by:
    
    canClone in interface CloneImplementor
    
    Parameters:
    
    clazz - The class
    
    Returns:
    
    True if cloneable, false otherwise
  - clone
```
public <T> T clone(T obj,
                   CloneDriver context,
                   IdentityHashMap<Object,Object> referencesToReuse,
                   long stackDepth)
```
    Description copied from interface: CloneImplementor
    
    Performs a clone.
    
    Specified by:
    
    clone in interface CloneImplementor
    
    Type Parameters:
    
    T - The type of the object to be cloned
    
    Parameters:
    
    obj - Object to clone
    
    context - The CloneDriver that initiated the request
    
    referencesToReuse - Any references for objects already cloned to ensure reference identity is preserved
    
    stackDepth - The number of objects already cloned in the current data structure
    
    Returns:
    
    The cloned object
  - getBuiltInImplementor
```
public CloneImplementor getBuiltInImplementor(Class<?> clazz)
```
    Description copied from interface: CloneDriver
    
    Gets the built in implementor for the given class
    
    Specified by:
    
    getBuiltInImplementor in interface CloneDriver
    
    Parameters:
    
    clazz - The class
    
    Returns:
    
    A CloneImplementor
  - getImplementor
```
public CloneImplementor getImplementor(Class<?> clazz)
```
    Description copied from interface: CloneDriver
    
    Retrieves the registered implementor for the given class
    
    Specified by:
    
    getImplementor in interface CloneDriver
    
    Parameters:
    
    clazz - The class
    
    Returns:
    
    A CloneImplementor
  - getAnnotationImplementor
```
public CloneImplementor getAnnotationImplementor(Class<?> clazz)
```
    Description copied from interface: CloneDriver
    
    Retrieves the registered implementor for the given class
    
    Specified by:
    
    getAnnotationImplementor in interface CloneDriver
    
    Parameters:
    
    clazz - The class
    
    Returns:
    
    A CloneImplementor
  - setImplementors
```
public void setImplementors(Map<Class<?>,CloneImplementor> implementors)
```
    Sets CloneImplementors to be used.
    
    Parameters:
    
    implementors - The implementors
  - getImmutableClasses
```
public Set<Class<?>> getImmutableClasses()
```
    Description copied from interface: CloneDriver
    
    A list of classes that should be treated as immutable.
    
    Specified by:
    
    getImmutableClasses in interface CloneDriver
    
    Returns:
    
    immutableClasses The immutable classes
  - setImmutableClasses
```
public void setImmutableClasses(Set<Class<?>> immutableClasses)
```
    Indicates classes which are immutable.
    
    Parameters:
    
    immutableClasses - Classes which should be treated as immutable
  - getNonCloneableClasses
```
public Set<Class<?>> getNonCloneableClasses()
```
    Description copied from interface: CloneDriver
    
    A list of classes that should not be cloned.
    
    Specified by:
    
    getNonCloneableClasses in interface CloneDriver
    
    Returns:
    
    immutableClasses The classes which should be be cloned
  - setNonCloneableClasses
```
public void setNonCloneableClasses(Set<Class<?>> nonCloneableClasses)
```
    Indicates classes that are not Cloneable.
    
    Parameters:
    
    nonCloneableClasses - Set of non-cloneable classes
  - isUseCloneable
```
public boolean isUseCloneable()
```
    Description copied from interface: CloneDriver
    
    If true, then any class that implements Cloneable will be cloned using the Object.clone() method.
    
    Specified by:
    
    isUseCloneable in interface CloneDriver
    
    Returns:
    
    Default value is false
  - setUseCloneable
```
public void setUseCloneable(boolean useCloneable)
```
    If true, the clone() method of classes implementing Cloneable will be delegated to where appropriate
    
    Parameters:
    
    useCloneable - True if the cloneable method should be used
  - getCloneMethod
```
public MethodHandle getCloneMethod(Class<?> clazz)
```
    Description copied from interface: CloneDriver
    
    Returns the clone() method for the indicated class
    
    Specified by:
    
    getCloneMethod in interface CloneDriver
    
    Parameters:
    
    clazz - The class to obtain the method for
    
    Returns:
    
    The related MethodHandle
  - isCloneTransientFields
```
public boolean isCloneTransientFields()
```
    Description copied from interface: CloneDriver
    
    If false, indicates that fields modified by the transient keyword should not be cloned, instead being replaced with null.
    
    Specified by:
    
    isCloneTransientFields in interface CloneDriver
    
    Returns:
    
    Default value is true
  - setCloneTransientFields
```
public void setCloneTransientFields(boolean cloneTransientFields)
```
    If true, fields marked with the transient keyword should be cloned
    
    Parameters:
    
    cloneTransientFields - true if fields decorated with transient keyword should be cloned
  - isCloneTransientAnnotatedFields
```
public boolean isCloneTransientAnnotatedFields()
```
    Description copied from interface: CloneDriver
    
    If false, indicates that fields annotated by the Transient annotation should not be cloned, instead being replaced with null.
    
    Specified by:
    
    isCloneTransientAnnotatedFields in interface CloneDriver
    
    Returns:
    
    Default value is false
  - setCloneTransientAnnotatedFields
```
public void setCloneTransientAnnotatedFields(boolean cloneTransientAnnotatedFields)
```
    If true, fields annotated with @Transient should be cloned
    
    Parameters:
    
    cloneTransientAnnotatedFields - True if fields annotated with @Transient should be cloned
  - isCloneImmutable
```
public boolean isCloneImmutable()
```
    Description copied from interface: CloneDriver
    
    If false, indicates that classes known to be immutable should be not cloned. Immutables are identified by the @Immutable annotation; are one of a select set of known JDK immutable classes; or are detected as immutable by the Mutability Detector tool (if it was found on the classpath).
    
    Specified by:
    
    isCloneImmutable in interface CloneDriver
    
    Returns:
    
    Default value is false
  - setCloneImmutable
```
public void setCloneImmutable(boolean cloneImmutable)
```
    If true, immutable classes should be cloned.
    
    Parameters:
    
    cloneImmutable - True if immutable classes should be cloned.
  - initialiseFor
```
public void initialiseFor(Class<?> classes)
```
    Description copied from interface: Cloner
    
    This method is included simply so that cold starts can be avoided. The method performs any initialisation needed in order to be able to subsequently process the class. If it is not called ahead of time the initialisation will be performed as part of the cloning operation. You only need to use this method in situations where a cold start is unacceptable
    
    Specified by:
    
    initialiseFor in interface Cloner
    
    Parameters:
    
    classes - Classes to perform initialisation for.
  - isUseCloneImplementors
```
public boolean isUseCloneImplementors()
```
    Description copied from interface: CloneDriver
    
    Indicates whether custom clone implementors are enabled
    
    Specified by:
    
    isUseCloneImplementors in interface CloneDriver
    
    Returns:
    
    Default value is true
  - setUseCloneImplementors
```
public void setUseCloneImplementors(boolean useCloneImplementors)
```
    If true, cloning may be delegates to clone implementors for specific tasks.
    
    Parameters:
    
    useCloneImplementors - True if CloneImplementors may be delegated to
  - isCloneSyntheticFields
```
public boolean isCloneSyntheticFields()
```
    Description copied from interface: CloneDriver
    
    Indicates whether synthetic fields should be cloned
    
    Specified by:
    
    isCloneSyntheticFields in interface CloneDriver
    
    Returns:
    
    cloneSyntheticFields Default is false
  - setCloneSyntheticFields
```
public void setCloneSyntheticFields(boolean cloneSyntheticFields)
```
    If true, synthetic fields should be cloned
    
    Parameters:
    
    cloneSyntheticFields - True if synthetic fields should be cloned
  - putAnnotationImplementor
```
public void putAnnotationImplementor(Class<?> clazz,
                                     CloneImplementor implementor)
```
    Description copied from interface: CloneDriver
    
    Put the registered implementor for the given class
    
    Specified by:
    
    putAnnotationImplementor in interface CloneDriver
    
    Parameters:
    
    clazz - The class
    
    implementor - Implementor to register
  - putCloneMethod
```
public void putCloneMethod(Class<?> clazz,
                           MethodHandle handle)
```
    Description copied from interface: CloneDriver
    
    Put the clone() method for the indicated class
    
    Specified by:
    
    putCloneMethod in interface CloneDriver
    
    Parameters:
    
    clazz - The class to obtain the method for
    
    handle - The related MethodHandle
  - isImmutableInstance
```
public boolean isImmutableInstance(Object instance)
```
    Description copied from interface: CloneDriver
    
    Indicates whether the given object instance should be treated as immutable
    
    Specified by:
    
    isImmutableInstance in interface CloneDriver
    
    Parameters:
    
    instance - The instance to check for whether it is registered as immutable
    
    Returns:
    
    True if the object is registered as immutable
  - putImmutableInstance
```
public void putImmutableInstance(Object instance)
```
    Description copied from interface: CloneDriver
    
    Stores an object instance to be treated as immutable
    
    Specified by:
    
    putImmutableInstance in interface CloneDriver
    
    Parameters:
    
    instance - Object to be considered immutable
  - isTrackReferences
```
public boolean isTrackReferences()
```
    Description copied from interface: CloneDriver
    
    Indicates whether to track references
    
    Specified by:
    
    isTrackReferences in interface CloneDriver
    
    Returns:
    
    trackReferences Default is true
  - setTrackReferences
```
public void setTrackReferences(boolean trackReferences)
```
    If false, do not track references so that objects are reused if they appear twice
    
    Parameters:
    
    trackReferences - True if references should be tracked
  - isTrackReferencesForFlatClasses
```
public boolean isTrackReferencesForFlatClasses()
```
    Description copied from interface: CloneDriver
    
    Indicates whether to also track references for flat classes when tracking references.
    
    Specified by:
    
    isTrackReferencesForFlatClasses in interface CloneDriver
    
    Returns:
    
    trackReferences Default is false
  - setTrackReferencesForFlatClasses
```
public void setTrackReferencesForFlatClasses(boolean trackReferencesForFlatClasses)
```
    If false, do not track references for flat classes when tracking references
    
    Parameters:
    
    trackReferencesForFlatClasses - False if references should not be tracked for flat classes

Class BasicCloner

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

BasicCloner

BasicCloner

Method Detail

clone

newInstance

canClone

clone

getBuiltInImplementor

getImplementor

getAnnotationImplementor

setImplementors

getImmutableClasses

setImmutableClasses

getNonCloneableClasses

setNonCloneableClasses

isUseCloneable

setUseCloneable

getCloneMethod

isCloneTransientFields

setCloneTransientFields

isCloneTransientAnnotatedFields

setCloneTransientAnnotatedFields

isCloneImmutable

setCloneImmutable

initialiseFor

isUseCloneImplementors

setUseCloneImplementors

isCloneSyntheticFields

setCloneSyntheticFields

putAnnotationImplementor

putCloneMethod

isImmutableInstance

putImmutableInstance

isTrackReferences

setTrackReferences

isTrackReferencesForFlatClasses

setTrackReferencesForFlatClasses