net.sf.morph.transform.copiers
Class ContainerCopier

java.lang.Object
  net.sf.morph.transform.transformers.BaseTransformer
      net.sf.morph.transform.transformers.BaseReflectorTransformer
          net.sf.morph.transform.copiers.ContainerCopier

All Implemented Interfaces:

net.sf.composite.Component, Converter, Copier, DecoratedConverter, DecoratedCopier, DecoratedTransformer, ExplicitTransformer, NodeCopier, Transformer

Direct Known Subclasses:

ArrayCopier, ContainerOfBeansCopier, MapCopier

public class ContainerCopier
extends BaseReflectorTransformer
implements DecoratedCopier, DecoratedConverter, NodeCopier

Copies information from any container object to any object that has either a GrowableContainerReflectoror a MutableIndexedContainerReflector. If the source object has a growable container reflector, information is added to the end of the destination when a copy is performed. If the source object does not have a growable container reflector (i.e. - it has a mutable indexed reflector), information copied from the source to the destination will overwrite the information in the destination.

By default, this means:

Destinations	Sources
java.util.List java.util.Set java.lang.Object[], int[], etc. (arrays)	java.util.Iterator java.util.Enumeration java.util.Collection java.lang.Object[], int[], etc. (arrays) java.util.Map (values are extracted) java.lang.Object (added to the end of the destination)

Since:

Nov 27, 2004

Author:

Matt Sgarlata

Field Summary

Fields inherited from class net.sf.morph.transform.transformers.BaseTransformer

destinationClasses, log, sourceClasses

Fields inherited from interface net.sf.morph.transform.Transformer

TRANSFORMATION_TYPE_CONVERT, TRANSFORMATION_TYPE_COPY

Fields inherited from interface net.sf.morph.transform.Transformer

TRANSFORMATION_TYPE_CONVERT, TRANSFORMATION_TYPE_COPY

Fields inherited from interface net.sf.morph.transform.Transformer

TRANSFORMATION_TYPE_CONVERT, TRANSFORMATION_TYPE_COPY

Fields inherited from interface net.sf.morph.transform.Transformer

TRANSFORMATION_TYPE_CONVERT, TRANSFORMATION_TYPE_COPY

Fields inherited from interface net.sf.morph.transform.Transformer

TRANSFORMATION_TYPE_CONVERT, TRANSFORMATION_TYPE_COPY

Constructor Summary

ContainerCopier()
Create a new ContainerCopier.

Method Summary

protected java.lang.Object	convertImpl(java.lang.Class destinationClass, java.lang.Object source, java.util.Locale locale) The implementation of the convert method, which may omit the invalid argument checks already performed by this base class.
protected void	copyImpl(java.lang.Object destination, java.lang.Object source, java.util.Locale locale, java.lang.Integer preferredTransformationType) Implementation of the copy method.
java.lang.Object	createReusableSource(java.lang.Class destinationClass, java.lang.Object source) NodeCopier.createReusableSource(Class, Object)
protected java.lang.Class	determineDestinationContainedType(java.lang.Object destination, java.lang.Class sourceValueClass) Deprecated. in favor of fully-specified method
protected java.lang.Class	determineDestinationContainedType(java.lang.Object destination, java.lang.Object sourceValue, java.lang.Class sourceValueClass, java.util.Locale locale) Determine the container element destination type.
java.util.Map	getContainedSourceToDestinationTypeMap() Get the mapping of source to destination container element types.
protected java.lang.Class[]	getDestinationClassesImpl() Transformer.getDestinationClasses() implementation template method.
Transformer	getNestedTransformer() NodeCopier.getNestedTransformer()
protected java.lang.Class[]	getSourceClassesImpl() Transformer.getSourceClasses() implementation template method.
boolean	isPreferGrow() Learn whether this ContainerCopier prefers to grow the destination when possible.
protected boolean	isWrappingRuntimeExceptions() Indicates whether runtime exceptions should be wrapped as TransformationExceptions.
protected java.lang.Object	nestedTransform(java.lang.Class destinationContainedType, java.lang.Object destinationValue, java.lang.Object sourceValue, java.util.Locale locale, java.lang.Integer preferredTransformationType) Do a nested transformation.
protected void	put(int index, java.lang.Object destination, java.lang.Object sourceValue, java.lang.Class sourceValueClass, java.util.Locale locale, java.lang.Integer preferredTransformationType) Adds an element to the destination object that is from the given index of the source object.
void	setContainedSourceToDestinationTypeMap(java.util.Map containedSourceToDestinationMapping) Set the mapping of source to destination container element types.
void	setNestedTransformer(Transformer transformer) NodeCopier.setNestedTransformer(Transformer)
void	setPreferGrow(boolean preferGrow) Set whether this ContainerCopier prefers to grow the destination when possible.

Methods inherited from class net.sf.morph.transform.transformers.BaseReflectorTransformer

getBeanReflector, getContainerReflector, getGrowableContainerReflector, getIndexedContainerReflector, getMutableIndexedContainerReflector, hasReflector

Methods inherited from class net.sf.morph.transform.transformers.BaseTransformer

clone, convert, convert, copy, copy, createDefaultReflector, createNewInstance, createNewInstanceImpl, equals, equals, equalsUnidirectionalTest, getDestinationClasses, getInstantiatingReflector, getLocale, getLog, getReflector, getReflector, getSourceClasses, getTransformableCallCache, getTransformerName, initialize, initializeImpl, isAutomaticallyHandlingNulls, isCachingIsTransformableCalls, isImpreciseTransformation, isImpreciseTransformationImpl, isInitialized, isPerformingLogging, isTransformable, isTransformableImpl, setCachingIsTransformableCalls, setDestinationClasses, setInitialized, setLog, setReflector, setSourceClasses, setTransformableCallCache, setTransformerName, toString

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.sf.morph.transform.DecoratedCopier

copy

Methods inherited from interface net.sf.morph.transform.Copier

copy

Methods inherited from interface net.sf.morph.transform.Transformer

getDestinationClasses, getSourceClasses

Methods inherited from interface net.sf.morph.transform.Transformer

getDestinationClasses, getSourceClasses

Methods inherited from interface net.sf.morph.transform.ExplicitTransformer

isTransformable

Methods inherited from interface net.sf.morph.transform.DecoratedConverter

convert, equals, equals

Methods inherited from interface net.sf.morph.transform.Converter

convert

Methods inherited from interface net.sf.morph.transform.Transformer

getDestinationClasses, getSourceClasses

Methods inherited from interface net.sf.morph.transform.Transformer

getDestinationClasses, getSourceClasses

Methods inherited from interface net.sf.morph.transform.ExplicitTransformer

isTransformable

Methods inherited from interface net.sf.morph.transform.NodeCopier

createNewInstance

Methods inherited from interface net.sf.morph.transform.Copier

copy

Methods inherited from interface net.sf.morph.transform.Transformer

getDestinationClasses, getSourceClasses

Constructor Detail

ContainerCopier

public ContainerCopier()

Create a new ContainerCopier.

Method Detail

determineDestinationContainedType

protected java.lang.Class determineDestinationContainedType(java.lang.Object destination,
                                                            java.lang.Object sourceValue,
                                                            java.lang.Class sourceValueClass,
                                                            java.util.Locale locale)

Determine the container element destination type. By default delegates to determineDestinationContainedType(Object, Class).

Parameters:

destination - container

sourceValue - source value

sourceValueClass - source type, or type source value would be if not null

Returns:

destination element type

determineDestinationContainedType

protected java.lang.Class determineDestinationContainedType(java.lang.Object destination,
                                                            java.lang.Class sourceValueClass)

Deprecated. in favor of fully-specified method

Determine the container element destination type.

Parameters:

destination - container

sourceValueClass - source type

Returns:

destination element type

put

protected void put(int index,
                   java.lang.Object destination,
                   java.lang.Object sourceValue,
                   java.lang.Class sourceValueClass,
                   java.util.Locale locale,
                   java.lang.Integer preferredTransformationType)

Adds an element to the destination object that is from the given index of the source object.

Parameters:

index - the current index into the container that is being transformed

destination - the destination container to which values are being copied from the source container

sourceValue - the value the source object has at the current index

sourceValueClass - the type of sourceValue, or the type the sourceValue would be were it not null

locale - the locale in which the current transformation is taking place

preferredTransformationType - the preferred transformation type to perform when transforming the sourceValue for addition into the destination

nestedTransform

protected java.lang.Object nestedTransform(java.lang.Class destinationContainedType,
                                           java.lang.Object destinationValue,
                                           java.lang.Object sourceValue,
                                           java.util.Locale locale,
                                           java.lang.Integer preferredTransformationType)

Do a nested transformation.

Parameters:

destinationContainedType -

destinationValue -

sourceValue -

locale -

preferredTransformationType -

Returns:

result

convertImpl

protected java.lang.Object convertImpl(java.lang.Class destinationClass,
                                       java.lang.Object source,
                                       java.util.Locale locale)
                                throws java.lang.Exception

The implementation of the convert method, which may omit the invalid argument checks already performed by this base class. By default, this method creates a new instance of the destinationClass and copies information from the source to the destination. This implementation should be fine as-is for Copiers, but Converters will need to implement this method since they will not be implementing the copy method.

Overrides:

convertImpl in class BaseTransformer

locale - the locale in which the conversion should take place. for converters that are not locale-aware, the local argument can simply be ignored

Throws:

java.lang.Exception

copyImpl

protected void copyImpl(java.lang.Object destination,
                        java.lang.Object source,
                        java.util.Locale locale,
                        java.lang.Integer preferredTransformationType)
                 throws TransformationException

Implementation of the copy method. By default, this method throws UnsupportedOperationException.

Overrides:

copyImpl in class BaseTransformer

Throws:

TransformationException

createReusableSource

public java.lang.Object createReusableSource(java.lang.Class destinationClass,
                                             java.lang.Object source)

NodeCopier.createReusableSource(Class, Object)

Specified by:

createReusableSource in interface NodeCopier

Overrides:

createReusableSource in class BaseTransformer

Parameters:

destinationClass - the destination class to which this source object will be transformed

source - a source object that will undergo a transformation by this copier

Returns:

a reusable version of fthe source object

getDestinationClassesImpl

protected java.lang.Class[] getDestinationClassesImpl()
                                               throws java.lang.Exception

Transformer.getDestinationClasses() implementation template method.

Overrides:

getDestinationClassesImpl in class BaseReflectorTransformer

Returns:

Class[]

Throws:

java.lang.Exception

getSourceClassesImpl

protected java.lang.Class[] getSourceClassesImpl()
                                          throws java.lang.Exception

Transformer.getSourceClasses() implementation template method.

Overrides:

getSourceClassesImpl in class BaseReflectorTransformer

Returns:

Class[]

Throws:

java.lang.Exception

isWrappingRuntimeExceptions

protected boolean isWrappingRuntimeExceptions()

Indicates whether runtime exceptions should be wrapped as TransformationExceptions. By default, this method returns true.

Simple transformers in Morph that operate on JDK types like Numbers and Strings will usually set this value to true so that they throw TransformationExceptions if problems occur. More complex transformers that operate on graphs of objects are encouraged to set this value to false so that runtime exceptions are not wrapped. This way, problems accessing data will be expressed by the native API of a user's domain objects and avoid the need to catch Morph-specific exceptions (assuming the use of runtime exceptions in said domain objects).

Overrides:

isWrappingRuntimeExceptions in class BaseTransformer

Returns:

true

getNestedTransformer

public Transformer getNestedTransformer()

NodeCopier.getNestedTransformer()

Specified by:

getNestedTransformer in interface NodeCopier

Overrides:

getNestedTransformer in class BaseTransformer

Returns:

Transformer

setNestedTransformer

public void setNestedTransformer(Transformer transformer)

NodeCopier.setNestedTransformer(Transformer)

Specified by:

setNestedTransformer in interface NodeCopier

Overrides:

setNestedTransformer in class BaseTransformer

Parameters:

transformer - the transformer used to perform nested transformations

getContainedSourceToDestinationTypeMap

public java.util.Map getContainedSourceToDestinationTypeMap()

Get the mapping of source to destination container element types.

Returns:

Map

See Also:

net.sf.morph.util.TypeMap}

setContainedSourceToDestinationTypeMap

public void setContainedSourceToDestinationTypeMap(java.util.Map containedSourceToDestinationMapping)

Set the mapping of source to destination container element types.

Parameters:

containedSourceToDestinationMapping - Map

See Also:

net.sf.morph.util.TypeMap}

isPreferGrow

public boolean isPreferGrow()

Learn whether this ContainerCopier prefers to grow the destination when possible.

Returns:

boolean

Since:

Morph 1.1

setPreferGrow

public void setPreferGrow(boolean preferGrow)

Set whether this ContainerCopier prefers to grow the destination when possible. Backward-compatible default setting is true; when false grow vs. mutate will be determined at runtime by the capabilities of the configured reflector with regard to the copy destination; preferredTransformationType will also be observed.

Parameters:

preferGrow - the boolean to set

Since:

Morph 1.1

See Also:

copyImpl(Object, Object, Locale, Integer)