com.edustructures.sifworks.tools.mapping
Class FieldMapping

java.lang.Object
  com.edustructures.sifworks.tools.mapping.FieldMapping

public class FieldMapping
extends java.lang.Object

A FieldMapping defines how to map a local application field to an element or attribute of the SIF Data Object type encapsulated by the parent ObjectMapping. Each FieldMapping is associated with a Rule that is evaluated at runtime to carry out the actual mapping operation on a SIFDataObject instance. The way the rule behaves is up to its implementation.

A FieldMapping may have a default value. If set, the default value is assigned to the SIF element or attribute if the corresponding field value is null or undefined. This is useful if you wish to ensure that a specific SIF element/attribute always has a value regardless of whether or not there is a corresponding value in your application's database.

A Field Mapping that has a default value can also set another attribute that specifies the behavior of the Field Mapping if the application value being mapped is null.

The application-defined field name that is associated with a FieldMapping must be unique; that is, there cannot be more than one FieldMapping for the same application field. However, if you wish to map the same field to more than one SIF element or attribute, you can create an alias. An alias is a FieldMapping that has a unique field name but refers to another field. For example, if your application defines the field STUDENT_NUM and you wish to define two FieldMappings for that field, create an alias:

// Create the default mapping
FieldMapping fm = new FieldMapping("STUDENT_NUM","OtherId[@Type='06']");


// Create an alias (the field name must be unique)
FieldMapping zz = new FieldMapping("MYALIAS","OtherId[@Type='ZZ']");
zz.setAlias( "STUDENT_NUM" );

In the above example, the "STUDENT_NUM" mapping produces an <OtherId> element with its Type attribute set to '06'. The "MYALIAS" mapping produces a second <OtherId> element with its Type attribute set to 'ZZ'. Both elements will have the value of the application-defined STUDENT_NUM field. Note that if MYALIAS were an actual field name of your application, however, the value of the <OtherId Type='ZZ'> element would be equal to that field's value. When creating aliases be sure to choose a name that does not conflict with the real field names used by your application.

Version:

ADK 1.0

Field Summary

static byte	IFNULL_DEFAULT Specifies that if the field being mapped is NULL, this field mapping should use the default value, if set.
static byte	IFNULL_SUPPRESS Specifies that if the field being mapped is NULL, this field mapping should not generate a SIF Element, even if a default value is specified
static byte	IFNULL_UNSPECIFIED The field mapping behavior for null fields is unspecified.

Constructor Summary

FieldMapping()
Constructor

FieldMapping(java.lang.String name, OtherIdMapping rule)
Constructs a FieldMapping with an <OtherId> rule.

FieldMapping(java.lang.String name, OtherIdMapping rule, org.w3c.dom.Node node)
Constructs a FieldMapping with an <OtherId> rule.

FieldMapping(java.lang.String name, java.lang.String rule)
Constructs a FieldMapping with an XPath-like rule

FieldMapping(java.lang.String name, java.lang.String rule, org.w3c.dom.Node node)
Creates a new FieldMapping rule

Method Summary

FieldMapping	copy(ObjectMapping newParent) Creates a copy this ObjectMapping instance.
SIFSimpleType	evaluate(SIFXPathContext xpathContext, SIFVersion version, boolean returnDefault) Evaluates this rule against a SIFXpathContexts and returns the text value of the element or attribute that satisfied the query.
static FieldMapping	fromXML(ObjectMapping parent, org.w3c.dom.Element element) Creates a new FieldMapping instance and populates its properties from the given XML Element
java.lang.String	getAlias() Determines if this FieldMapping is an alias of another field mapping.
SIFDataType	getDataType() Returns the datatype that this FieldMapping represents.
java.lang.String	getDefaultValue() Gets the default value for this field when no corresponding element or attribute is found in the SIF Data Object.
SIFSimpleType	getDefaultValue(SIFTypeConverter converter, SIFFormatter formatter)
java.lang.String	getFieldName() Gets the name of the local application field that maps to the SIF Data Object element or attribute
MappingsFilter	getFilter() Gets optional filtering attributes.
java.lang.String	getKey() Returns the key to a Field Mapping.
org.w3c.dom.Node	getNode() Gets the optional DOM Node associated with this FieldMapping instance.
byte	getNullBehavior() Returns the behavior that this field mapping will follow when mapping a null value.
Rule	getRule() Gets the field mapping rule
java.lang.String	getValueSetID() Gets the ID of the ValueSet that should be used to translate the value of this field.
boolean	hasDefaultValue() Quickly determines whether this field mapping has a default value defined without going through the extra work of actually resolving the default value
void	setAlias(java.lang.String fieldName) Defines this FieldMapping to be an alias of another field mapping.
void	setDataType(SIFDataType dataType) Sets the name of the data type this field represents.
void	setDefaultValue(java.lang.String defValue) Sets a default value for this field when no corresponding element or attribute is found in the SIF Data Object.
void	setFieldName(java.lang.String name) Sets the name of the local application field that maps to the SIF Data Object element or attribute
void	setFilter(MappingsFilter filter) Sets optional filtering attributes.
void	setNode(org.w3c.dom.Node node) Sets the optional DOM Node associated with this FieldMapping instance.
void	setNullBehavior(byte behavior) Sets the behavior that the field mapping should follow when mapping a null value.
void	setRule(OtherIdMapping otherId) Sets this object's rule to an "<OtherId> rule"
void	setRule(OtherIdMapping otherId, org.w3c.dom.Node node) Sets an OtherId rule for this FieldMapping
void	setRule(java.lang.String definition) Sets this FieldMapping rule to an XPath-like query string
void	setValueSetID(java.lang.String id) Sets the ID of the ValueSet that should be used to translate the value of this field.
void	toXML(org.w3c.dom.Element element) Writes the values of this FieldMapping to the specified XML Element

Methods inherited from class java.lang.Object

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

Field Detail

IFNULL_UNSPECIFIED

public static final byte IFNULL_UNSPECIFIED

The field mapping behavior for null fields is unspecified. In this case, the behavior is identical to IFNULL_DEFAULT

See Also:

setNullBehavior(byte), Constant Field Values

IFNULL_DEFAULT

public static final byte IFNULL_DEFAULT

Specifies that if the field being mapped is NULL, this field mapping should use the default value, if set.

See Also:

setNullBehavior(byte), Constant Field Values

IFNULL_SUPPRESS

public static final byte IFNULL_SUPPRESS

Specifies that if the field being mapped is NULL, this field mapping should not generate a SIF Element, even if a default value is specified

See Also:

setNullBehavior(byte), Constant Field Values

Constructor Detail

FieldMapping

public FieldMapping()

Constructor

FieldMapping

public FieldMapping(java.lang.String name,
                    java.lang.String rule)

Constructs a FieldMapping with an XPath-like rule

Parameters:

name - The name of the local application field that maps to the SIF Data Object element or attribute described by this FieldMapping

rule - An XPath-like query string described by the SIFDTD.lookupByXPath method

FieldMapping

public FieldMapping(java.lang.String name,
                    java.lang.String rule,
                    org.w3c.dom.Node node)

Creates a new FieldMapping rule

Parameters:

name - The name of the field being mapped

rule - The XPath rule associated with this mapping

node - The optional DOM Node associated with this FieldMapping

FieldMapping

public FieldMapping(java.lang.String name,
                    OtherIdMapping rule)

Constructs a FieldMapping with an <OtherId> rule.

Parameters:

name - The name of the local application field that maps to the SIF Data Object element or attribute described by this FieldMapping

rule - An OtherIdMapping object that describes how to select a <OtherId> element during a mapping operation

FieldMapping

public FieldMapping(java.lang.String name,
                    OtherIdMapping rule,
                    org.w3c.dom.Node node)

Constructs a FieldMapping with an <OtherId> rule.

Parameters:

name - The name of the local application field that maps to the SIF Data Object element or attribute described by this FieldMapping

rule - An OtherIdMapping object that describes how to select a <OtherId> element during a mapping operation

node - The optional DOM Node that this FieldMapping stores its configuration to, or Null

Method Detail

getNode

public org.w3c.dom.Node getNode()

Gets the optional DOM Node associated with this FieldMapping instance. The DOM Node is usually set by the parent ObjectMapping instance when a FieldMapping is populated from a DOM Document.

Returns:

The DOM Node associated with this this FieldMapping instance

setNode

public void setNode(org.w3c.dom.Node node)

Sets the optional DOM Node associated with this FieldMapping instance. The DOM Node is usually set by the parent ObjectMapping instance when a FieldMapping is populated from a DOM Document.

Parameters:

node - The DOMNode associated with this FieldMapping instance

fromXML

public static FieldMapping fromXML(ObjectMapping parent,
                                   org.w3c.dom.Element element)
                            throws ADKConfigException

Creates a new FieldMapping instance and populates its properties from the given XML Element

Parameters:

parent -

element -

Returns:

a new FieldMapping instance

Throws:

ADKConfigException - If the FieldMapping cannot read expected values from the DOM Node

toXML

public void toXML(org.w3c.dom.Element element)

Writes the values of this FieldMapping to the specified XML Element

Parameters:

element - The XML Element to write values to

copy

public FieldMapping copy(ObjectMapping newParent)
                  throws ADKMappingException

Creates a copy this ObjectMapping instance.

Parameters:

newParent - The parent that this FieldMapping is associated with

Returns:

A "deep copy" of this object

Throws:

ADKMappingException

setFieldName

public void setFieldName(java.lang.String name)

Sets the name of the local application field that maps to the SIF Data Object element or attribute

Parameters:

name - A field name. (This value will be used as the key in the HashMap populated by the Mappings.map methods.)

getFieldName

public java.lang.String getFieldName()

Gets the name of the local application field that maps to the SIF Data Object element or attribute

Returns:

The local application field name. (This value will be used as the key in HashMaps populated by the Mappings.map methods)

getKey

public java.lang.String getKey()

Returns the key to a Field Mapping. The Key of a field mapping consists of it's alias or field name and any filters that are defined

Returns:

A string representing the key of this object

setValueSetID

public void setValueSetID(java.lang.String id)

Sets the ID of the ValueSet that should be used to translate the value of this field.

Note: The Mappings classes do not automatically perform translations if this attribute is defined. Rather, it is provided so that agents can associate a ValueSet with a field in the Mappings configuration file, and have a means of looking up that association at runtime.

Parameters:

id - The ID of a ValueSet defined in the Mappings (e.g. "EthnicityCodes"). If set to NULL or "", the ValueSet is removed

Since:

ADK 1.5

See Also:

getValueSetID()

getValueSetID

public java.lang.String getValueSetID()

Gets the ID of the ValueSet that should be used to translate the value of this field.

Note: The Mappings classes do not automatically perform translations if this attribute is defined. Rather, it is provided so that agents can associate a ValueSet with a field in the Mappings configuration file, and have a means of looking up that association at runtime.

Returns:

The value passed to the setValueSetID method

Since:

ADK 1.5

See Also:

setValueSetID(java.lang.String)

setDefaultValue

public void setDefaultValue(java.lang.String defValue)

Sets a default value for this field when no corresponding element or attribute is found in the SIF Data Object. The Mapping.map methods will create an entry in the HashMap with this default value.

Parameters:

defValue - A default string value for this field

getDefaultValue

public java.lang.String getDefaultValue()

Gets the default value for this field when no corresponding element or attribute is found in the SIF Data Object. The Mapping.map methods will create an entry in the HashMap with this default value.

Returns:

The default string value for this field

hasDefaultValue

public boolean hasDefaultValue()

Quickly determines whether this field mapping has a default value defined without going through the extra work of actually resolving the default value

Returns:

True if this field mapping has a default value defined

getDefaultValue

public SIFSimpleType getDefaultValue(SIFTypeConverter converter,
                                     SIFFormatter formatter)
                              throws ADKMappingException

Parameters:

converter -

formatter -

Returns:

The strongly-typed datatype

Throws:

ADKMappingException - If the default value specified cannot be converted to the proper data type

setAlias

public void setAlias(java.lang.String fieldName)

Defines this FieldMapping to be an alias of another field mapping. During the mapping process, the FieldMapping will be applied if the referenced field exists in the Map provided to the Mappings.map method. Aliases are required when an application wishes to map a single application field to more than one element or attribute in the SIF Data Object.

To use aliases, create a FieldMapping where the field name is a unique name and the alias is the name of an existing field. For example, to map an application-defined field named "STUDENT_NUM" to more than one element/attribute in the SIF Data Object, // Create the default mapping
FieldMapping fm = new FieldMapping("STUDENT_NUM","OtherId[@Type='06']");


// Create an alias; the field name must be unique
FieldMapping fm2 = new FieldMapping("STUDENT_NUM_B","OtherId[@Type='ZZ']=STUDENTID:$(STUDENTNUM)");


Parameters:

fieldName - The name of the field for which this entry is an alias

getAlias

public java.lang.String getAlias()

Determines if this FieldMapping is an alias of another field mapping.

Returns:

The name of the field for which this entry is an alias, or null if this FieldMapping is not an alias.

See Also:

setAlias(java.lang.String)

evaluate

public SIFSimpleType evaluate(SIFXPathContext xpathContext,
                              SIFVersion version,
                              boolean returnDefault)
                       throws ADKSchemaException

Evaluates this rule against a SIFXpathContexts and returns the text value of the element or attribute that satisfied the query.

Parameters:

xpathContext - The SIFXpathContext the rule is evaluated against

version - The SIFVersion to use when lookup up the value

returnDefault - True if the default value should be returned when there is no value

Returns:

The value of the element or attribute that satisfied the query, or null if no match found. If the returnDefault parameter is set to true, the default value will be returned, if specified

Throws:

ADKSchemaException - is thrown if the rule associated with this object is invalid or the default value cannot be parsed

setRule

public void setRule(java.lang.String definition)

Sets this FieldMapping rule to an XPath-like query string

Parameters:

definition - An XPath-like query string described by the SIFDTD.lookupByXPath method

setRule

public void setRule(OtherIdMapping otherId)

Sets this object's rule to an "<OtherId> rule"

Parameters:

otherId - An OtherIdMapping object that describes how to select a <OtherId> element during a mapping operation

setRule

public void setRule(OtherIdMapping otherId,
                    org.w3c.dom.Node node)

Sets an OtherId rule for this FieldMapping

Parameters:

otherId - The OtherIdMapping instance to use for this field mapping

node - The DOM Node associated with the OtherId mapping

getRule

public Rule getRule()

Gets the field mapping rule

Returns:

A Rule instance

setFilter

public void setFilter(MappingsFilter filter)

Sets optional filtering attributes. This field mapping rule will only be applied if the filters match the values passed to the Mappings.map method at runtime.

Parameters:

filter - A MappingsFilter instance (null to clear the current filter attributes)

Since:

ADK 1.5

See Also:

getFilter()

getFilter

public MappingsFilter getFilter()

Gets optional filtering attributes.

Returns:

A MappingsFilter instance or null if none defined for this field rule

Since:

ADK 1.5

See Also:

setFilter(com.edustructures.sifworks.tools.mapping.MappingsFilter)

setNullBehavior

public void setNullBehavior(byte behavior)

Sets the behavior that the field mapping should follow when mapping a null value. The value set should be one of the the IFNULL_XXX constants defined in this class. The default behavior for null values if this value is not set is to use the default value, if present.

Parameters:

behavior - One of the the IFNULL_XXX constants defined in this class

getNullBehavior

public byte getNullBehavior()

Returns the behavior that this field mapping will follow when mapping a null value.

Returns:

One of the the IFNULL_XXX constants defined in this class

setDataType

public void setDataType(SIFDataType dataType)

Sets the name of the data type this field represents.

This datatype is used if the datatype cannot be derived from the field mapping. If this value is null, this instance will use the STRING data type.

Parameters:

dataType -

getDataType

public SIFDataType getDataType()

Returns the datatype that this FieldMapping represents.

If the datatype attribute is not set on the <field> mapping, a default of SIFDataType.STRING is assumed. This value is primarily used for assigning default values to field mappings.

Returns:

The Datatype associated with this FieldMapping