com.univocity.api.config.builders.ReferenceMappingSetup Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of univocity-api Show documentation
uniVocity Data Integration's Public API
The newest version!
/*******************************************************************************
 * Copyright (c) 2014 uniVocity Software Pty Ltd. All rights reserved.
 * This file is subject to the terms and conditions defined in file
 * 'LICENSE.txt', which is part of this source code package.
 ******************************************************************************/
package com.univocity.api.config.builders;

/**
 * The ReferenceMappingSetup is the base configuration used to define which fields should be read from a source entity in an {@link EntityMapping}
 * 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 "wgt_nbr" and "wgt_seq" from the source entity "WGT_DET" to obtain the identifier associated with "weight".
 * //After getting the correct identifier of "weight", copy it to "weight_ref"
 *
 * EntityMapping weightDetails = mapping.map("WGT_DET", "weight_details");
 * weightDetails.reference().using("wgt_nbr", "wgt_seq").referTo("WGT", "weight").on("weight_ref");
 * ...
 * 

 *
 * Using the above mapping, uniVocity will execute a query against its metadata requesting any values associated with wgt_nbr and wgt_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_ref field of weight_details
 *
 * @see EntityMapping
 * @see IdentifierMappingSetup
 *
 * @author uniVocity Software Pty Ltd - [email protected]
 *
 */
public interface ReferenceMappingSetup {
	/**
	 * Associates one or more fields from the source entity in an {@link EntityMapping} with a reference in the destination entity.
	 *
	 * @param sourceFields the field names in the source entity to be associated with a reference to an entity in the destination.
	 * 		   Expressions are allowed within curly braces (i.e. "{expression}")
	 * @return the next step of this configuration: define what source entity has an identifier mapped with the given fields, and
	 *         what entity in the destination had its identifier associated with these fields (using {@link IdentifierMappingSetup}).
	 */
	public ReferencedEntity using(String... sourceFields);
}