com.neurosys.etl.common

Class ExistingEntityMergeTransformer<T>

java.lang.Object

com.neurosys.etl.common.ExistingEntityMergeTransformer<T>

Type Parameters:

T -

All Implemented Interfaces:

org.apache.commons.collections.Transformer

Direct Known Subclasses:

ExistingEntityLookup

public class ExistingEntityMergeTransformer<T>
extends Object
implements org.apache.commons.collections.Transformer

Various settings provided by this class; merge existing entity fields into primary one.
Useful when an entity has related entities that need to exist/persist.

Author:

Arjun Dhar

See Also:

copy(Object, Object, Stack), copySpecificTypes(Object, Object, Stack), isMutable(Object, Object, String), isMutablePrimitive(Object, String, Object)

Field Summary

Fields

Modifier and Type	Field and Description
protected Map<Object,org.apache.commons.collections.Transformer>	customMergeActions Map fieldName (String) or value type (Class) to a Transformer that accepts an Array of {Parent existing entity, fieldName as String, new transient object for field} and returns the final Object. The mapper can also result in null (No transformer) in which case it implies to ignore any copy/merge actions. If the transformer throws a ContinueProcessingException then the calling code can assume that the transformer has decided to relenquish control and let the caller deal with the data-type in a default way.
protected Collection<String>	fieldNamesToMerge The values for field names mentioned in this Collection will be merged into the new Entity, i.e.
protected boolean	ignoreNullsForPrimitiveTypes If true and a field is a primitive type, it will prevent updating the resultant object from un-wanted null values from a partial input object.
protected Map<Class,List<String>>	immutableFieldNames The field name(s) [map of exact Type to identity fields for entity or related entity exact type], used to uniquely identify the looked up entity; note these fields will also not be overridden during any merge process in default implementation.
protected boolean	mergeFieldMode If true, will merge the fields from the source (override in case of conflict) with the existing field values else all the values for the entity will be afresh.
protected Collection<Class<?>>	typesRequireDeepCopy While copying from new Entity to existing one, if it matches any of the types here it will scan the object recursively to dig out properties and sent back in the original persisted object if that already exists.

Constructor Summary

Constructors

Constructor and Description
ExistingEntityMergeTransformer()
ExistingEntityMergeTransformer(ExistingEntityMergeTransformer t)

Method Summary

Modifier and Type	Method and Description
protected <X> void	copy(X storedEntity, X lookedUpEntity, Stack parents) Copy from lookedUpEintity into storedEntity.
protected <X> boolean	copySpecificTypes(X storedEntity, X lookedUpEntity, Stack parents) Override and provide custom handling of Specific Types
static Class	getClosestParent(Collection<Class> classes, Class child) Given a collection of classes, determine which is the closest parent of the provided class.
protected org.apache.commons.collections.Transformer	getCustomMergeAction(String fieldName, Class type) Look for any Custom Merge actions defined.
Map<Object,org.apache.commons.collections.Transformer>	getCustomMergeActions() Map fieldName (String) or value type (Class) to a Transformer that accepts an Array of {existing stored entity, new transient object} and returns the final Object. The mapper can also result in null (No transformer) in which case it implies to ignore any copy/merge actions.
Collection<String>	getFieldNamesToMerge() The values for field names mentioned in this Collection will be merged into the new Entity, i.e.
Map<Class,List<String>>	getIdentityFieldNames() Deprecated.
protected List<String>	getIdFieldsForClass(Class c) Deprecated.
Map<Class,List<String>>	getImmutableFieldNames() The field name(s) [map of exact Type to identity fields for entity or related entity exact type], used to uniquely identify the looked up entity; note these fields will also not be overridden during any merge process in default implementation.
protected List<String>	getImmutableFieldsForClass(Class c) Get list of all fields for class that we do not want to override
Collection<Class<?>>	getTypesRequireDeepCopy() While copying from new Entity to existing one, if it matches any of the types here it will scan the object recursively to dig out properties and sent back in the original persisted object if that already exists.
boolean	isIgnoreNullsForPrimitiveTypes() If true and a field is a primitive type, it will prevent updating the resultant object from un-wanted null values from a partial input object.
boolean	isMergeFieldMode() If true, will merge the fields from the Excel (override in case of conflict) with the existing field values else all the values for the entity will be afresh.
protected <X> boolean	isMutable(X storedEntity, X lookedUpEntity, String fieldName) To modify or not modify the field in storedEntity.
protected <X> boolean	isMutablePrimitive(X storedEntity, String fieldName, Object value) To modify or not modify a primitive field in storedEntity.
static boolean	isValidOrPrimitiveFieldType(Class<?> type)
protected T	mergeFields(T storedEntity, T lookedUpEntity) Records from the new Source sheet maybe merged with existing values in store (current) If mergeFieldMode is true, it will keep original values (where the looked-up one is null) and only override with the ones supplied by the looked-up one else except for the Identifier fields, other fields will all be overwritten.
protected boolean	requiredDeepCopy(Object value)
void	setCustomMergeActions(Map<Object,org.apache.commons.collections.Transformer> customMergeActions) Map fieldName (String) or value type (Class) to a Transformer that accepts an Array of {existing stored entity, new transient object} and returns the final Object. The mapper can also result in null (No transformer) in which case it implies to ignore any copy/merge actions.
void	setFieldNamesToMerge(Collection<String> fieldNamesToMerge) The values for field names mentioned in this Collection will be merged into the new Entity, i.e.
void	setIdentityFieldNames(Map<Class,List<String>> identityFieldNames) Deprecated.
void	setIgnoreNullsForPrimitiveTypes(boolean ignoreNullsForPrimitiveTypes) If true and a field is a primitive type, it will prevent updating the resultant object from un-wanted null values from a partial input object.
void	setImmutableFieldNames(Map<Class,List<String>> immutableFieldNames) The field name(s) [map of exact Type to identity fields for entity or related entity exact type], used to uniquely identify the looked up entity; note these fields will also not be overridden during any merge process in default implementation.
void	setMergeFieldMode(boolean mergeFieldMode) If true, will merge the fields from the Excel (override in case of conflict) with the existing field values else all the values for the entity will be afresh.
void	setTypesRequireDeepCopy(Collection<Class<?>> typesRequireDeepCopy) While copying from new Entity to existing one, if it matches any of the types here it will scan the object recursively to dig out properties and sent back in the original persisted object if that already exists.
Object	transform(Object in)
protected Object	treatNewEntity(Object newObject, Stack parents) During the process of Merge/Copy if a new Object is being set it may need to be additionally treated. Like persist on database etc before its set in the main Entity.

Methods inherited from class java.lang.Object

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

Field Detail

mergeFieldMode

protected boolean mergeFieldMode

If true, will merge the fields from the source (override in case of conflict) with the existing field values else all the values for the entity will be afresh. TODO: Add Unit Test

Default value:

false

ignoreNullsForPrimitiveTypes

protected boolean ignoreNullsForPrimitiveTypes

If true and a field is a primitive type, it will prevent updating the resultant object from un-wanted null values from a partial input object.

See Also:

immutableFieldNames, isMutablePrimitive(Object, String, Object)

Default value:

false

typesRequireDeepCopy

protected Collection<Class<?>> typesRequireDeepCopy

While copying from new Entity to existing one, if it matches any of the types here it will scan the object recursively to dig out properties and sent back in the original persisted object if that already exists.

fieldNamesToMerge

protected Collection<String> fieldNamesToMerge

The values for field names mentioned in this Collection will be merged into the new Entity, i.e. these fields will not be over-written.
Useful if mergeFieldMode is false and we want to ensure certain fields are not overwritten by a new entity.
These fields are those that are usually are not supplied as data, in the new entity and exist in the stored entity. It is intuitive to imagine that we would want to retain field data that already exists and not be wiped out by an ETL process (insulate them from being overwritten in the stored entity).

Setters are also included, so its not necessary that the field has to be a proper defined one. A setter that updates another field can also be called, so consider all setters.

Format of each String is: <simple ClassName>.<fieldName>

immutableFieldNames

protected Map<Class,List<String>> immutableFieldNames

The field name(s) [map of exact Type to identity fields for entity or related entity exact type], used to uniquely identify the looked up entity; note these fields will also not be overridden during any merge process in default implementation.

Setters are also included, so its not necessary that the field has to be a proper defined one. A setter that updates another field can also be called, so consider all setters.

See Also:

ignoreNullsForPrimitiveTypes, isMutable(Object, Object, String)

customMergeActions

protected Map<Object,org.apache.commons.collections.Transformer> customMergeActions

Map fieldName (String) or value type (Class) to a Transformer that accepts an Array of {Parent existing entity, fieldName as String, new transient object for field} and returns the final Object.
The mapper can also result in null (No transformer) in which case it implies to ignore any copy/merge actions.
If the transformer throws a ContinueProcessingException then the calling code can assume that the transformer has decided to relenquish control and let the caller deal with the data-type in a default way. This is to handle custom cases (specially for Collections where a certain type in the collection may not agree to be being merged by the converter).

Constructor Detail

ExistingEntityMergeTransformer

public ExistingEntityMergeTransformer()

ExistingEntityMergeTransformer

public ExistingEntityMergeTransformer(ExistingEntityMergeTransformer t)

Method Detail

isValidOrPrimitiveFieldType

public static boolean isValidOrPrimitiveFieldType(Class<?> type)

requiredDeepCopy

protected boolean requiredDeepCopy(Object value)

copySpecificTypes

protected <X> boolean copySpecificTypes(X storedEntity,
                                        X lookedUpEntity,
                                        Stack parents)
                                 throws IllegalAccessException,
                                        InvocationTargetException,
                                        NoSuchMethodException

Override and provide custom handling of Specific Types

Parameters:

storedEntity -

lookedUpEntity -

parents - as a Stack of parents; 0th being root entity and last being immediate parent. Parents are useful as we recurse down and need a reference to a parent entity

Returns:

boolean ; true is the type was handled and requires no further processing.

Throws:

IllegalAccessException

InvocationTargetException

NoSuchMethodException

treatNewEntity

protected Object treatNewEntity(Object newObject,
                                Stack parents)

During the process of Merge/Copy if a new Object is being set it may need to be additionally treated.
Like persist on database etc before its set in the main Entity.

Parameters:

newObject - as Object to be treated that is replacing a null value in the Existing entity

parents - as a Stack of parents; 0th being root entity and last being immediate parent. Parents are useful as we recurse down and need a reference to a parent entity

Returns:

Object as treated object

getCustomMergeAction

protected org.apache.commons.collections.Transformer getCustomMergeAction(String fieldName,
                                                                          Class type)

Look for any Custom Merge actions defined.

Parameters:

fieldName - as String

oldValue - as object, old value persisted (fetched from lookup)

value - as object

Returns:

Transformer that accepts an Array of {Parent existing entity, fieldName as String, new transient object for field} and returns the final Object.
If the transformer throws a ContinueProcessingException then the calling code can assume that the transformer has decided to relenquish control and let the caller deal with the data-type in a default way. This is to handle custom cases (specially for Collections where a certain type in the collection may not agree to be being merged by the converter).

copy

protected <X> void copy(X storedEntity,
                        X lookedUpEntity,
                        Stack parents)
                 throws IllegalAccessException,
                        InvocationTargetException,
                        NoSuchMethodException

Copy from lookedUpEintity into storedEntity. it will try and do a best for merge. Additionally if the copy process requires a deep-Copy it will perform that.

Parameters:

storedEntity - as persisted/existing entity

lookedUpEntity - (fresh transient entity), that by intent is to be merged into storedEntity

Throws:

IllegalAccessException

InvocationTargetException

NoSuchMethodException

isMutable

protected <X> boolean isMutable(X storedEntity,
                                X lookedUpEntity,
                                String fieldName)

To modify or not modify the field in storedEntity.

Parameters:

storedEntity - as persisted/existing entity

lookedUpEntity - as new entity that by intent is to be merged into storedEntity

fieldName - as String

Returns:

true if we can overwrite a field in the storedEntity

isMutablePrimitive

protected <X> boolean isMutablePrimitive(X storedEntity,
                                         String fieldName,
                                         Object value)

To modify or not modify a primitive field in storedEntity.

For non-primitive types see requiredDeepCopy(Object).
For fields that we do not want overridden (immutable) under any circumstances, see immutableFieldNames.

Parameters:

storedEntity - as persisted/existing entity

fieldName - as String

Returns:

true if we can overwrite a field in the storedEntity

See Also:

customMergeActions, requiredDeepCopy(Object), immutableFieldNames

Default value:

If value is not null or ignoreNullsForPrimitiveTypes if false, then it is mutable.

mergeFields

protected T mergeFields(T storedEntity,
                        T lookedUpEntity)
                 throws Exception

Records from the new Source sheet maybe merged with existing values in store (current)
If mergeFieldMode is true, it will keep original values (where the looked-up one is null) and only override with the ones supplied by the looked-up one else except for the Identifier fields, other fields will all be overwritten.

In either case, the identifier fields should be preserved.

Note on type of parameter and return type:
The default implementation, tries to the result is of type storedEntity to ensure there is no issue in persisting it back; except if the storedEntity is itself null
This implies that storedEntity should be same type or a super type of lookedUpEntity. If its a super type, then the uncommon fields will be dropped in the merging process and will result in loss of data

Parameters:

storedEntity - as T

lookedUpEntity - (fresh transient entity) as T

Returns:

T TODO: Add Unit test case

Throws:

Exception

transform

public Object transform(Object in)

Specified by:

transform in interface org.apache.commons.collections.Transformer

getClosestParent

public static Class getClosestParent(Collection<Class> classes,
                                     Class child)

Given a collection of classes, determine which is the closest parent of the provided class.
If nothing is found then return null. If there are multiple classes from which we inherit the first matching one will be considered.

Parameters:

classes -

Returns:

Class @nullable true

getIdFieldsForClass

@Deprecated
protected List<String> getIdFieldsForClass(Class c)

Deprecated.

See Also:

getImmutableFieldsForClass(Class)

getImmutableFieldsForClass

protected List<String> getImmutableFieldsForClass(Class c)

Get list of all fields for class that we do not want to override

Parameters:

c - as Class

Returns:

List of field names (setters are included, so its not necessary that the field has to be a proper defined one)

isMergeFieldMode

public boolean isMergeFieldMode()

If true, will merge the fields from the Excel (override in case of conflict) with the existing field values else all the values for the entity will be afresh.

Default value:

false

setMergeFieldMode

public void setMergeFieldMode(boolean mergeFieldMode)

If true, will merge the fields from the Excel (override in case of conflict) with the existing field values else all the values for the entity will be afresh.

Default value:

false

getIdentityFieldNames

@Deprecated
public Map<Class,List<String>> getIdentityFieldNames()

Deprecated.

See Also:

getImmutableFieldNames()

setIdentityFieldNames

@Deprecated
public void setIdentityFieldNames(Map<Class,List<String>> identityFieldNames)

Deprecated.

See Also:

setImmutableFieldNames(Map)

getImmutableFieldNames

public Map<Class,List<String>> getImmutableFieldNames()

The field name(s) [map of exact Type to identity fields for entity or related entity exact type], used to uniquely identify the looked up entity; note these fields will also not be overridden during any merge process in default implementation.

Setters are also included, so its not necessary that the field has to be a proper defined one. A setter that updates another field can also be called, so consider all setters.

See Also:

ignoreNullsForPrimitiveTypes, isMutable(Object, Object, String)

setImmutableFieldNames

public void setImmutableFieldNames(Map<Class,List<String>> immutableFieldNames)

The field name(s) [map of exact Type to identity fields for entity or related entity exact type], used to uniquely identify the looked up entity; note these fields will also not be overridden during any merge process in default implementation.

Setters are also included, so its not necessary that the field has to be a proper defined one. A setter that updates another field can also be called, so consider all setters.

See Also:

ignoreNullsForPrimitiveTypes, isMutable(Object, Object, String)

isIgnoreNullsForPrimitiveTypes

public boolean isIgnoreNullsForPrimitiveTypes()

If true and a field is a primitive type, it will prevent updating the resultant object from un-wanted null values from a partial input object.

See Also:

immutableFieldNames, isMutablePrimitive(Object, String, Object)

Default value:

false

setIgnoreNullsForPrimitiveTypes

public void setIgnoreNullsForPrimitiveTypes(boolean ignoreNullsForPrimitiveTypes)

If true and a field is a primitive type, it will prevent updating the resultant object from un-wanted null values from a partial input object.

See Also:

immutableFieldNames, isMutablePrimitive(Object, String, Object)

Default value:

false

getTypesRequireDeepCopy

public Collection<Class<?>> getTypesRequireDeepCopy()

While copying from new Entity to existing one, if it matches any of the types here it will scan the object recursively to dig out properties and sent back in the original persisted object if that already exists.

setTypesRequireDeepCopy

public void setTypesRequireDeepCopy(Collection<Class<?>> typesRequireDeepCopy)

While copying from new Entity to existing one, if it matches any of the types here it will scan the object recursively to dig out properties and sent back in the original persisted object if that already exists.

getFieldNamesToMerge

public Collection<String> getFieldNamesToMerge()

The values for field names mentioned in this Collection will be merged into the new Entity, i.e. these fields will not be over-written.
Useful if mergeFieldMode is false and we want to ensure certain fields are not overwritten by a new entity.
These fields are those that are usually are not supplied as data, in the new entity and exist in the stored entity. It is intuitive to imagine that we would want to retain field data that already exists and not be wiped out by an ETL process (insulate them from being overwritten in the stored entity).

Setters are also included, so its not necessary that the field has to be a proper defined one. A setter that updates another field can also be called, so consider all setters.

Format of each String is: <simple ClassName>.<fieldName>

setFieldNamesToMerge

public void setFieldNamesToMerge(Collection<String> fieldNamesToMerge)

The values for field names mentioned in this Collection will be merged into the new Entity, i.e. these fields will not be over-written.
Useful if mergeFieldMode is false and we want to ensure certain fields are not overwritten by a new entity.
These fields are those that are usually are not supplied as data, in the new entity and exist in the stored entity. It is intuitive to imagine that we would want to retain field data that already exists and not be wiped out by an ETL process (insulate them from being overwritten in the stored entity).

Setters are also included, so its not necessary that the field has to be a proper defined one. A setter that updates another field can also be called, so consider all setters.

Format of each String is: <simple ClassName>.<fieldName>

getCustomMergeActions

public Map<Object,org.apache.commons.collections.Transformer> getCustomMergeActions()

Map fieldName (String) or value type (Class) to a Transformer that accepts an Array of {existing stored entity, new transient object} and returns the final Object.
The mapper can also result in null (No transformer) in which case it implies to ignore any copy/merge actions.

setCustomMergeActions

public void setCustomMergeActions(Map<Object,org.apache.commons.collections.Transformer> customMergeActions)

Map fieldName (String) or value type (Class) to a Transformer that accepts an Array of {existing stored entity, new transient object} and returns the final Object.
The mapper can also result in null (No transformer) in which case it implies to ignore any copy/merge actions.