net.sf.morph.transform.transformers
Class BaseTransformer

java.lang.Object
  net.sf.morph.transform.transformers.BaseTransformer

All Implemented Interfaces:

net.sf.composite.Component, DecoratedTransformer, ExplicitTransformer, Transformer

Direct Known Subclasses:

ArbitraryObjectMappingConverter, ArbitraryTypeMappingConverter, BaseCompositeTransformer, BaseReflectorTransformer, BeanUtilsConverter, BooleanToTextConverter, ConditionalCopier, ConstantConverter, ConverterDecorator, CopierDecorator, EvaluateExpressionConverter, IdentityConverter, ImmutableComponentArrayCopier, NOPCopier, NullConverter, NumberConverter, NumberToBooleanConverter, NumberToTextConverter, NumberToTimeConverter, ObjectToBooleanConverter, ObjectToClassConverter, ObjectToTextConverter, PrimitiveWrapperConverter, PropertyExpressionMappingCopier, SetExpressionCopier, TextConverter, TextToBooleanConverter, TextToClassConverter, TextToContainerCopier, TextToNumberConverter, TextToTimeConverter, TimeConverter, TimeToNumberConverter, TimeToTextConverter, TransformerDecorator, TransformerToDecoratedConverterAdapter

public abstract class BaseTransformer
extends java.lang.Object
implements Transformer, DecoratedTransformer

Convenient base class for transformers. This base class offers a number of convenient features, including those listed below.

• Automatically performs basic argument checking
• Automatically does basic logging
• Wraps exceptions in TransformationExceptions for you
• Exposes the convenient DecoratedTransformerinterface, while only requiring subclasses to implement the methods in Transformer.
• Provides protected methods that assist in the implementation of transformers which are in turn composed of other transformers.
• Optionally caches results of ExplicitTransformer.isTransformable(Class, Class) for better performance. This feature is turned on by default

Since:

Nov 26, 2004

Author:

Matt Sgarlata

Field Summary

protected java.lang.Class[]	destinationClasses Destination classes
protected org.apache.commons.logging.Log	log BaseTransformer log object
protected java.lang.Class[]	sourceClasses Source classes

Constructor Summary

protected

BaseTransformer() Create a new BaseTransformer.

Method Summary

protected java.lang.Object	clone()
java.lang.Object	convert(java.lang.Class destinationClass, java.lang.Object source) DecoratedConverter.convert(Class, Object)
java.lang.Object	convert(java.lang.Class destinationClass, java.lang.Object source, java.util.Locale locale)
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.
void	copy(java.lang.Object destination, java.lang.Object source) DecoratedCopier.copy(Object, Object)
void	copy(java.lang.Object destination, java.lang.Object source, java.util.Locale locale) Copier.copy(Object, Object, Locale)
protected void	copyImpl(java.lang.Object destination, java.lang.Object source, java.util.Locale locale, java.lang.Integer preferredTransformationType) Implementation of the copy method.
protected Reflector	createDefaultReflector() Create the default reflector instance to be used by this Transformer.
java.lang.Object	createNewInstance(java.lang.Class destinationClass, java.lang.Object source) NodeCopier.createNewInstance(Class, Object)
protected java.lang.Object	createNewInstanceImpl(java.lang.Class destinationClass, java.lang.Object source) Implement NodeCopier.createNewInstance(Class, Object)
protected java.lang.Object	createReusableSource(java.lang.Class destinationClass, java.lang.Object source) NodeCopier.createReusableSource(Class, Object)
boolean	equals(java.lang.Object object1, java.lang.Object object2) Locale-independent test between two objects for equality.
boolean	equals(java.lang.Object object1, java.lang.Object object2, java.util.Locale locale) Test objects for equality.
protected boolean	equalsUnidirectionalTest(java.lang.Object cannotBeNull, java.lang.Object canBeNull, java.util.Locale locale) Helper method for equality testing.
java.lang.Class[]	getDestinationClasses() Defines the types of objects that can be used as information sources by this transformer.
protected abstract java.lang.Class[]	getDestinationClassesImpl() Transformer.getDestinationClasses() implementation template method.
protected InstantiatingReflector	getInstantiatingReflector() Get the InstantiatingReflector employed by this Transformer.
protected java.util.Locale	getLocale() Retrieves the current Locale if none is specified in the method arguments for a converter or copier.
protected org.apache.commons.logging.Log	getLog() Get the commons-logging Log in use.
protected Transformer	getNestedTransformer() NodeCopier.getNestedTransformer()
Reflector	getReflector() Get the Reflector employed by this Transformer.
protected Reflector	getReflector(java.lang.Class reflectorType) Get the Reflector of the specified type employed by this Transformer.
java.lang.Class[]	getSourceClasses() Defines the types of objects that can be used as information sources by this transformer.
protected abstract java.lang.Class[]	getSourceClassesImpl() Transformer.getSourceClasses() implementation template method.
protected java.util.Map	getTransformableCallCache() Get the cache of calls to isTransformable(Class, Class)
java.lang.String	getTransformerName() Get the transformerName.
protected void	initialize() Initialize this Transformer
protected void	initializeImpl() Gives subclasses a chance to perform any computations needed to initialize the transformer.
protected boolean	isAutomaticallyHandlingNulls() Indicates whether null values will automatically be converted to null by this base class before even calling the subclass's convertImpl(Class, Object, Locale) method.
boolean	isCachingIsTransformableCalls() Learn whether this Transformer is caching calls to isTransformable(Class, Class)
boolean	isImpreciseTransformation(java.lang.Class destinationClass, java.lang.Class sourceClass) Learn whether the specified transformation yields an imprecise result.
protected boolean	isImpreciseTransformationImpl(java.lang.Class destinationClass, java.lang.Class sourceClass) Implementation of isImpreciseTransformation
protected boolean	isInitialized() Learn whether this Transformer has been initialized.
protected boolean	isPerformingLogging() Indicates if calls to the main transformation methods (convert, copy) will cause a log message to be recorded
boolean	isTransformable(java.lang.Class destinationType, java.lang.Class sourceType) Specifies which source classes are transformable to which destination classes.
protected boolean	isTransformableImpl(java.lang.Class destinationType, java.lang.Class sourceType) Default implementation for Transformer#isTransformable(Class, Class) that assumes that each source type can be converted into each destination type.
protected boolean	isWrappingRuntimeExceptions() Indicates whether runtime exceptions should be wrapped as TransformationExceptions.
void	setCachingIsTransformableCalls(boolean cachingIsTransformableCalls) Set whether this Transformer is caching calls to isTransformable(Class, Class)
protected void	setDestinationClasses(java.lang.Class[] destinationClasses) Configures the destinationClasses property of this transformer.
protected void	setInitialized(boolean initialized) Set whether this Transformer has been initialized.
protected void	setLog(org.apache.commons.logging.Log log) Set the commons-logging Log for this Transformer.
protected void	setNestedTransformer(Transformer nestedTransformer) NodeCopier.setNestedTransformer(Transformer)
void	setReflector(Reflector reflector) Set the Reflector to be used by this Transformer.
protected void	setSourceClasses(java.lang.Class[] sourceClasses) Configures the sourceClasses property of this transformer.
protected void	setTransformableCallCache(java.util.Map transformableCallCache) Get the cache of calls to isTransformable(Class, Class)
void	setTransformerName(java.lang.String transformerName) Set the transformerName.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

log

protected transient org.apache.commons.logging.Log log

BaseTransformer log object

sourceClasses

protected java.lang.Class[] sourceClasses

Source classes

destinationClasses

protected java.lang.Class[] destinationClasses

Destination classes

Constructor Detail

BaseTransformer

protected BaseTransformer()

Create a new BaseTransformer.

Method Detail

isTransformableImpl

protected boolean isTransformableImpl(java.lang.Class destinationType,
                                      java.lang.Class sourceType)
                               throws java.lang.Exception

Default implementation for Transformer#isTransformable(Class, Class) that assumes that each source type can be converted into each destination type.

Parameters:

destinationType - the destination type to test

sourceType - the source type to test

Returns:

whether the destination type is transformable to the source type

Throws:

TransformationException - if it could not be determined if sourceType is transformable into destinationType

java.lang.Exception

isTransformable

public final boolean isTransformable(java.lang.Class destinationType,
                                     java.lang.Class sourceType)
                              throws TransformationException

Specifies which source classes are transformable to which destination classes.

Specified by:

isTransformable in interface ExplicitTransformer

Parameters:

destinationType - the destination type to test

sourceType - the source type to test

Returns:

whether the destination type is transformable to the source type

Throws:

TransformationException - if it could not be determined if sourceType is transformable into destinationType

See Also:

ExplicitTransformer.isTransformable(java.lang.Class, java.lang.Class)

getSourceClassesImpl

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

Transformer.getSourceClasses() implementation template method.

Returns:

Class[]

Throws:

java.lang.Exception

getDestinationClassesImpl

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

Transformer.getDestinationClasses() implementation template method.

Returns:

Class[]

Throws:

java.lang.Exception

getSourceClasses

public final java.lang.Class[] getSourceClasses()
                                         throws TransformationException

Defines the types of objects that can be used as information sources by this transformer. This can be thought of as the valid "output" types for the transformer.

Specified by:

getSourceClasses in interface Transformer

Returns:

the types of objects that can be used as information sources by this transformer

Throws:

TransformationException

See Also:

Transformer.getSourceClasses()

getDestinationClasses

public final java.lang.Class[] getDestinationClasses()
                                              throws TransformationException

Defines the types of objects that can be used as information sources by this transformer. This method can be thought of as specifying the valid "output" types for this transformer.

Specified by:

getDestinationClasses in interface Transformer

Returns:

the types of objects that can be used as information sources by this transformer

Throws:

TransformationException

See Also:

Transformer.getDestinationClasses()

setSourceClasses

protected void setSourceClasses(java.lang.Class[] sourceClasses)

Configures the sourceClasses property of this transformer. Note that this method should be called before the transformer is used. Otherwise, if another thread is in the middle of transforming an object graph and this method is called, the behavior of the transformer can change partway through the transformation.

Parameters:

sourceClasses - the new sourceClasses for this transformer

setDestinationClasses

protected void setDestinationClasses(java.lang.Class[] destinationClasses)

Configures the destinationClasses property of this transformer. Note that this method should be called before the transformer is used. Otherwise, if another thread is in the middle of transforming an object graph and this method is called, the behavior of the transformer can change partway through the transformation.

Parameters:

destinationClasses - the new destinationClasses for this transformer

initializeImpl

protected void initializeImpl()
                       throws java.lang.Exception

Gives subclasses a chance to perform any computations needed to initialize the transformer.

Throws:

java.lang.Exception

initialize

protected final void initialize()
                         throws TransformationException

Initialize this Transformer

Throws:

TransformationException

getLocale

protected java.util.Locale getLocale()

Retrieves the current Locale if none is specified in the method arguments for a converter or copier. Attempts to load the Locale using Spring's org.springframework.context.i18n.LocaleContextHolder, if Spring is on the classpath. Otherwise, returns the default Locale by calling Locale.getDefault().

Returns:

the current Locale

convert

public final java.lang.Object convert(java.lang.Class destinationClass,
                                      java.lang.Object source)
                               throws TransformationException

DecoratedConverter.convert(Class, Object)

Parameters:

destinationClass -

source -

Returns:

Throws:

TransformationException

convert

public final java.lang.Object convert(java.lang.Class destinationClass,
                                      java.lang.Object source,
                                      java.util.Locale locale)

Parameters:

destinationClass -

source -

locale -

Returns:

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.

Parameters:

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

createReusableSource

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

NodeCopier.createReusableSource(Class, Object)

Parameters:

destinationClass -

source -

Returns:

equals

public boolean equals(java.lang.Object object1,
                      java.lang.Object object2,
                      java.util.Locale locale)

Test objects for equality.

Parameters:

object1 -

object2 -

locale -

Returns:

true if object1 is considered equal to object2.

equals

public final boolean equals(java.lang.Object object1,
                            java.lang.Object object2)
                     throws TransformationException

Locale-independent test between two objects for equality.

Parameters:

object1 -

object2 -

Returns:

true if object1 is considered equal to object2.

Throws:

TransformationException

equalsUnidirectionalTest

protected boolean equalsUnidirectionalTest(java.lang.Object cannotBeNull,
                                           java.lang.Object canBeNull,
                                           java.util.Locale locale)

Helper method for equality testing.

Parameters:

cannotBeNull -

canBeNull -

locale -

Returns:

true if object1 is considered equal to object2.

copy

public final void copy(java.lang.Object destination,
                       java.lang.Object source)
                throws TransformationException

DecoratedCopier.copy(Object, Object)

Parameters:

destination -

source -

Throws:

TransformationException

copy

public final void copy(java.lang.Object destination,
                       java.lang.Object source,
                       java.util.Locale locale)
                throws TransformationException

Copier.copy(Object, Object, Locale)

Parameters:

destination -

source -

locale -

Throws:

TransformationException

copyImpl

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

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

Throws:

java.lang.Exception

createNewInstanceImpl

protected java.lang.Object createNewInstanceImpl(java.lang.Class destinationClass,
                                                 java.lang.Object source)
                                          throws java.lang.Exception

Implement NodeCopier.createNewInstance(Class, Object)

Parameters:

destinationClass -

source -

Returns:

Object

Throws:

java.lang.Exception

createNewInstance

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

NodeCopier.createNewInstance(Class, Object)

Parameters:

destinationClass -

source -

Returns:

Object

isImpreciseTransformationImpl

protected boolean isImpreciseTransformationImpl(java.lang.Class destinationClass,
                                                java.lang.Class sourceClass)

Implementation of isImpreciseTransformation

Parameters:

destinationClass -

sourceClass -

Returns:

boolean

isImpreciseTransformation

public final boolean isImpreciseTransformation(java.lang.Class destinationClass,
                                               java.lang.Class sourceClass)

Learn whether the specified transformation yields an imprecise result.

Parameters:

destinationClass -

sourceClass -

Returns:

boolean

Since:

Morph 1.1

isPerformingLogging

protected boolean isPerformingLogging()

Indicates if calls to the main transformation methods (convert, copy) will cause a log message to be recorded

Returns:

boolean

isAutomaticallyHandlingNulls

protected boolean isAutomaticallyHandlingNulls()

Indicates whether null values will automatically be converted to null by this base class before even calling the subclass's convertImpl(Class, Object, Locale) method. Subclasses which depend on this behavior (which is all subclasses, by default) should include null as one of their source and destination classes so that the actual behavior of the transformer is consistent with the values that are returned by the isTransformable(Class, Class) method. The conversions will happen automatically even if the source and destination classes don't contain null, but for the sake of consistency the nulls should be included.

Returns:

whether null values will automatically be converted to null by this base class before even calling the subclass's convertImpl(Class, Object, Locale) method

Since:

Morph 1.1

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).

Returns:

true

Since:

Morph 1.1

getNestedTransformer

protected Transformer getNestedTransformer()

NodeCopier.getNestedTransformer()

Returns:

Transformer

setNestedTransformer

protected void setNestedTransformer(Transformer nestedTransformer)

NodeCopier.setNestedTransformer(Transformer)

Parameters:

nestedTransformer -

isInitialized

protected boolean isInitialized()

Learn whether this Transformer has been initialized.

Returns:

boolean

setInitialized

protected void setInitialized(boolean initialized)

Set whether this Transformer has been initialized.

Parameters:

initialized -

isCachingIsTransformableCalls

public boolean isCachingIsTransformableCalls()

Learn whether this Transformer is caching calls to isTransformable(Class, Class)

Returns:

boolean

setCachingIsTransformableCalls

public void setCachingIsTransformableCalls(boolean cachingIsTransformableCalls)

Set whether this Transformer is caching calls to isTransformable(Class, Class)

Parameters:

cachingIsTransformableCalls -

getTransformableCallCache

protected java.util.Map getTransformableCallCache()

Get the cache of calls to isTransformable(Class, Class)

Returns:

Map

setTransformableCallCache

protected void setTransformableCallCache(java.util.Map transformableCallCache)

Get the cache of calls to isTransformable(Class, Class)

Parameters:

transformableCallCache - Map

getLog

protected org.apache.commons.logging.Log getLog()

Get the commons-logging Log in use.

Returns:

Log

setLog

protected void setLog(org.apache.commons.logging.Log log)

Set the commons-logging Log for this Transformer.

Parameters:

log -

getInstantiatingReflector

protected InstantiatingReflector getInstantiatingReflector()

Get the InstantiatingReflector employed by this Transformer.

Returns:

InstantiatingReflector

getReflector

protected Reflector getReflector(java.lang.Class reflectorType)

Get the Reflector of the specified type employed by this Transformer.

Parameters:

reflectorType -

Returns:

Reflector of type reflectorType

getReflector

public Reflector getReflector()

Get the Reflector employed by this Transformer.

Returns:

Reflector

setReflector

public void setReflector(Reflector reflector)

Set the Reflector to be used by this Transformer.

Parameters:

reflector -

createDefaultReflector

protected Reflector createDefaultReflector()

Create the default reflector instance to be used by this Transformer.

Returns:

Reflector

clone

protected java.lang.Object clone()
                          throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException

See Also:

Object.clone()

getTransformerName

public java.lang.String getTransformerName()

Get the transformerName.

Returns:

String

Since:

Morph 1.1

setTransformerName

public void setTransformerName(java.lang.String transformerName)

Set the transformerName.

Parameters:

transformerName - the String to set

Since:

Morph 1.1

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

Since:

Morph 1.1