com.univocity.api.config.builders
Interface EntityMapping


public interface EntityMapping

The EntityMapping provides builder-style configuration options for defining mappings between fields of two data entities, or between values produced by expressions to a destination data entity.

Instances of this interface are obtained from a DataStoreMapping instance, using either DataStoreMapping.map(String, String) or DataStoreMapping.map(String).

Author:
uniVocity Software Pty Ltd - dev@univocity.com
See Also:
RowReader, DataStoreMapping, FieldMappingSetup, IdentifierMappingSetup, ReferenceMappingSetup, PersistenceSetup

Method Summary
 void addInputRowReader(RowReader rowReader)
          Adds a RowReader to be executed against the input data of this entity mapping.
 void addInputRowReaders(String... readerNames)
          Associates one or more RowReaders, registered in the DataIntegrationEngine, with the input data of this entity mapping.
 void addOutputRowReader(RowReader rowReader)
          Adds a RowReader to be executed against the output data of this entity mapping, before it is persisted.
 void addOutputRowReaders(String... readerNames)
          Associates one or more RowReaders registered, in the DataIntegrationEngine, with the output data of this entity mapping.
 void addPersistedRowReader(RowReader rowReader)
          Adds a RowReader to be executed against the data persisted after the execution of this entity mapping.
 void addPersistedRowReaders(String... readerNames)
          Associates one or more RowReaders, registered in the DataIntegrationEngine, to be executed against the data persisted after the execution of this entity mapping.
 void autodetectMappings()
          Executes a process for automatic detection of mappings based on the field names of the mapped entities.
 void autodetectMappings(NameMatcher nameMatcher)
          Executes a process for automatic detection of mappings based on the field names of the mapped entities.
 IdentifierMappingSetup identity()
          Configures the mapping of one or more fields in the source entity to the destination fields used as identifiers.
 boolean isEnabled()
          Tests if this entity mapping is enabled, in which case it can be executed in a DataIntegrationEngine cycle.
 boolean isInputSharingEnabled()
          Identifies whether data read from the source entity in this mapping can be shared and reused by the previous or the next entity mapping.
 PersistenceSetup persistence()
          Configures the persistence settings used by this EntityMapping
 ReferenceMappingSetup reference()
          Configures the mapping of one or more fields in the source entity that are used to construct a reference to a destination entity.
 void removeInputRowReader(RowReader rowReader)
          Removes a RowReader from the input data of this entity mapping.
 void removeInputRowReaders(String... readerNames)
          Removes one or more RowReaders, registered in the DataIntegrationEngine, from the input data of this entity mapping.
 void removeOutputRowReader(RowReader rowReader)
          Removes a RowReader from the data sent to the destination entity in this mapping.
 void removeOutputRowReaders(String... readerNames)
          Removes one or more RowReaders, registered in the DataIntegrationEngine, from the data sent to the destination entity in this mapping.
 void removePersistedRowReader(RowReader rowReader)
          Removes a RowReader from the data persisted after the execution of this entity mapping.
 void removePersistedRowReaders(String... readerNames)
          Removes one or more RowReaders, registered in the DataIntegrationEngine, from the data persisted after the execution of this entity mapping.
 void setEnabled(boolean enabled)
          Defines whether this entity mapping is enabled, in which case it can be executed in a DataIntegrationEngine cycle.
 void setInputSharingEnabled(boolean enabled)
          Defines whether data read from the source entity in this mapping can be shared and reused by the previous or the next entity mapping.
 void transformFields(String functionName, String... sourceFieldNames)
          Associates a function to a given list of source field names or expressions.
 FieldMappingSetup value()
          Configures the mapping of one or more fields from the source entity to the destination.
 

Method Detail

value

FieldMappingSetup value()
Configures the mapping of one or more fields from the source entity to the destination.

Returns:
the field mapping builder that exposes the appropriate configuration options required to map one or more fields between two data entities.

identity

IdentifierMappingSetup identity()
Configures the mapping of one or more fields in the source entity to the destination fields used as identifiers.

Returns:
the identity mapping builder that exposes the appropriate configuration options required to map one or more fields used as identifiers.

reference

ReferenceMappingSetup reference()
Configures the mapping of one or more fields in the source entity that are used to construct a reference to a destination entity. The source fields will be used for querying uniVocity's metadata to restore values associated with the identifier of an entity. For example:
 //Maps fields "nbr" and "seq" from the source entity "WGT" to a destination entity "weight"

 EntityMapping weightMapping = mapping.map("WGT", "weight");
 weightMapping.identity().associate("nbr", "seq").toGeneratedId("gid");
 ...
 

When the above mapping is executed, values read from nbr and seq will be associated with the generated identifier gid:
 Source entity (WGT)    Destination entity (weight)
     nbr | seq                    gid
     ----+----                  -------
     001 | 1                       1
     001 | 2                       2
     002 | 1                       3
 

With this information on the metadata, a reference mapping can be defined as:
 //Uses fields "nbr" and "seq" from the source entity "WGT" to obtain the identifier associated with "weight".
 //After getting the correct identifier of "weight", copy it to "weight_id"

 EntityMapping weightDetails = mapping.map("WGT", "weight_details");
 weightDetails.reference().using("nbr", "seq").referTo("WGT", "weight").on("weight_id");
 ...
 

Using the above mapping, uniVocity will execute a query against its metadata requesting for any values associated with nbr and seq, where the source entity is WGT and the destination entity is weight. The returned identifiers for weight will then be associated with the weight_id field in weight_details.

Returns:
the reference mapping builder that exposes the appropriate configuration options required to map one or more fields to references to other entities in the destination data store.

persistence

PersistenceSetup persistence()
Configures the persistence settings used by this EntityMapping

Returns:
the persistence settings builder that exposes the available configuration options for this entity mapping.

addInputRowReader

void addInputRowReader(RowReader rowReader)
Adds a RowReader to be executed against the input data of this entity mapping.

Parameters:
rowReader - the callback object that will intercept and possibly manipulate the rows extracted from the source entity before its data is mapped to the destination.

addInputRowReaders

void addInputRowReaders(String... readerNames)
Associates one or more RowReaders, registered in the DataIntegrationEngine, with the input data of this entity mapping.

Parameters:
readerNames - the names of the callback objects that will intercept and possibly manipulate the rows extracted from the source entity before its data is mapped to the destination.

addOutputRowReader

void addOutputRowReader(RowReader rowReader)
Adds a RowReader to be executed against the output data of this entity mapping, before it is persisted.

Parameters:
rowReader - the callback object that will intercept and possibly manipulate the rows extracted from the source entity and mapped to the destination, before they are persisted

addOutputRowReaders

void addOutputRowReaders(String... readerNames)
Associates one or more RowReaders registered, in the DataIntegrationEngine, with the output data of this entity mapping.

Parameters:
readerNames - the names of the callback objects that will intercept and possibly manipulate the rows extracted from the source entity and mapped to the destination, before they are persisted

addPersistedRowReader

void addPersistedRowReader(RowReader rowReader)
Adds a RowReader to be executed against the data persisted after the execution of this entity mapping. Values generated after insertion, if any, will be available to the RowReader.

Parameters:
rowReader - the callback object that will manipulate rows extracted from the source entity, mapped and persisted into the destination

addPersistedRowReaders

void addPersistedRowReaders(String... readerNames)
Associates one or more RowReaders, registered in the DataIntegrationEngine, to be executed against the data persisted after the execution of this entity mapping. Values generated after insertion, if any, will be available to the RowReader.

Parameters:
readerNames - the names of the callback objects that will manipulate rows extracted from the source entity, mapped and persisted into the destination

removeInputRowReader

void removeInputRowReader(RowReader rowReader)
Removes a RowReader from the input data of this entity mapping.

Parameters:
rowReader - the RowReader instance to remove from this mapping's input

removeInputRowReaders

void removeInputRowReaders(String... readerNames)
Removes one or more RowReaders, registered in the DataIntegrationEngine, from the input data of this entity mapping.

Parameters:
readerNames - the names of the RowReaders to remove from this mapping's input

removeOutputRowReader

void removeOutputRowReader(RowReader rowReader)
Removes a RowReader from the data sent to the destination entity in this mapping.

Parameters:
rowReader - the RowReader instance to remove from this mapping's output

removeOutputRowReaders

void removeOutputRowReaders(String... readerNames)
Removes one or more RowReaders, registered in the DataIntegrationEngine, from the data sent to the destination entity in this mapping.

Parameters:
readerNames - the names of the RowReaders to remove from this mapping's output

removePersistedRowReader

void removePersistedRowReader(RowReader rowReader)
Removes a RowReader from the data persisted after the execution of this entity mapping.

Parameters:
rowReader - the RowReader instance to remove from this mapping's persisted data

removePersistedRowReaders

void removePersistedRowReaders(String... readerNames)
Removes one or more RowReaders, registered in the DataIntegrationEngine, from the data persisted after the execution of this entity mapping.

Parameters:
readerNames - the names of the RowReaders to remove from this mapping's persisted data

autodetectMappings

void autodetectMappings()
Executes a process for automatic detection of mappings based on the field names of the mapped entities. Fields that are already mapped will not be used in the process.

Fields with similar names will be automatically associated. Underscores and spaces are ignored, for example: field1 will be associated with FIELD 1 or FIELD_1. If the field in either source or destination is an identifier, the mapping will be created using IdentifierMappingSetup, otherwise a regular field copy will be created using FieldMappingSetup.


autodetectMappings

void autodetectMappings(NameMatcher nameMatcher)
Executes a process for automatic detection of mappings based on the field names of the mapped entities. Fields that are already mapped will not be used in the process.

A NameMatcher will be executed to match the names of each field in both entities. If the field in either source or destination is an identifier, the mapping will be created using IdentifierMappingSetup, otherwise a regular field copy will be created using FieldMappingSetup.

Parameters:
nameMatcher - a matcher for field names. If null the default matching algorithm will be used.

isEnabled

boolean isEnabled()
Tests if this entity mapping is enabled, in which case it can be executed in a DataIntegrationEngine cycle.

Returns:
true if this entity mapping is enabled and can be executed by a DataIntegrationEngine, otherwise false

setEnabled

void setEnabled(boolean enabled)
Defines whether this entity mapping is enabled, in which case it can be executed in a DataIntegrationEngine cycle.

Parameters:
enabled - a flag identifying whether this entity mapping can be executed by a DataIntegrationEngine.

isInputSharingEnabled

boolean isInputSharingEnabled()
Identifies whether data read from the source entity in this mapping can be shared and reused by the previous or the next entity mapping. Irrespective of any configuration, the input will only be shared if the source entity in the next entity mapping uses the same source entity, and this method returns true in both mappings.

Input sharing has performance implications and can also affect how the data mapping process is organized. For example, consider the following mappings:


 //Maps fields "nbr" and "seq" from the source entity "WGT" to a destination entity "weight"
 EntityMapping weightMapping = mapping.map("WGT", "weight");
 weightMapping.identity().associate("nbr", "seq").toGeneratedId("id");
 ...

 //Maps field "msre_desc" from the source entity "WGT" to a destination entity "weight_details"
 EntityMapping weightDetailsMapping = mapping.map("WGT", "weight_details");
 weightDetailsMapping.value().copy("msre_desc").to("description");
 ...
 

In the mappings configured above, both weight and weight_details read data from WGT. If input sharing is enabled in both mappings, then the DataIntegrationEngine will:

If either of the mappings in the example are configured to NOT share their inputs, then the DataIntegrationEngine will read all rows from the input twice:

Defaults to true

Returns:
true if the data read from the source entity in this mapping can be shared and reused by the previous or the next entity mapping, otherwise false

setInputSharingEnabled

void setInputSharingEnabled(boolean enabled)
Defines whether data read from the source entity in this mapping can be shared and reused by the previous or the next entity mapping. Irrespective of any configuration, the input will only be shared if the source entity in the next entity mapping uses the same source entity, and this method returns true in both mappings.

Input sharing has performance implications and can also affect how the data mapping process is organized. For example, consider the following mappings:


 //Maps fields "nbr" and "seq" from the source entity "WGT" to a destination entity "weight"
 EntityMapping weightMapping = mapping.map("WGT", "weight");
 weightMapping.identity().associate("nbr", "seq").toGeneratedId("id");
 ...

 //Maps field "msre_desc" from the source entity "WGT" to a destination entity "weight_details"
 EntityMapping weightDetailsMapping = mapping.map("WGT", "weight_details");
 weightDetailsMapping.value().copy("msre_desc").to("description");
 ...
 

In the mappings configured above, both weight and weight_details read data from WGT. If input sharing is enabled in both mappings, then the DataIntegrationEngine will:

If either of the mappings in the example are configured to NOT share their inputs, then the DataIntegrationEngine will read all rows from the input twice:

Parameters:
enabled - a flag indicating whether data read from the source entity in this mapping can be shared and reused by the previous or the next entity mapping

transformFields

void transformFields(String functionName,
                     String... sourceFieldNames)
Associates a function to a given list of source field names or expressions. When reading from the source entity, the function will be executed and its result will be send to the destination fields. The given function will be executed after other function sequences already applied to these fields.

Parameters:
functionName - the name of the function to associate to fields of the source entity.
sourceFieldNames - field names/expressions against which the given function should be applied to.


Copyright © 2015 uniVocity Software Pty Ltd. All rights reserved.