You are here: Popular Formats > XML (Extensible Markup Language) Reader/Writer > xfMap > Feature Mapping Rules > FME Feature Construction (defining mapping rules under the <feature-content-map> element)
FME Feature Construction
(defining mapping rules under the <feature-content-map> element)

A mapping rule R1 from the <feature-map> element that matches an element E might not be able to perform all the necessary mappings for E’s child elements. When this is the case, additional mapping rules that match E’s children should be specified under the <feature-content-map> element.

Recall that when an FME feature is under construction (i.e., at least one feature mapping rule is activated) then the feature-search-set can only include the mapping rules from the <feature-content-map> element. When activated, these mapping rules will work on the current feature that is under construction; they do not specify the construction of a new FME feature.

Consider the following input XML document, points2.xml:

points2.xml

<?xml version=”1.0”?>
<points>
	<point name=”myPoint” num=”0”>
		<color type=”red” value=”0.324”/>
		<color type=”green” value=”0.233”/>
		<color type=”blue” value=”0.596”/>
	</point>
	<point name=”myPoint” num=”1”>
		<color type=”red” value=”0.874”/>
		<color type=”green” value=”0.948”/>
		<color type=”blue” value=”0.554”/>
	</point>
</points>

A mapping rule R1, defined under the <feature-map> element, that matches the <point> element will have difficulty extracting information from all the <color> elements.

Recall that the extract expression does not currently support index access for the matched element’s children. All R1 is able to do now, is to extract data from the first <color> element.

An extract expression defined in a mapping rule matching the <point> element will be unable to reach the other <color> elements, since its expression string can only refer to the first <color> element. To overcome this limitation, we need to define mapping rules in the <feature-content-map> element that matches a <color> element.

Let R2 be a mapping rule under the <feature-content-map> element that matches a <color> element. When R2 activates it will suspend R1, and work with the same FME feature that R1 created. The following xfMap document, feature_content.xmp, does this exactly:

feature_content.xmp

<?xml version="1.0"?>
<!DOCTYPE xfMap SYSTEM "xfMap.dtd">

<xfMap>
	<feature-map>
		<!-- Call this mapping rule R1 -->
		<mapping match="point">
		</mapping>
	</feature-map>
	<feature-content-map>
		<!-- Call this mapping rule R2 -->
		<mapping match="color">
			<attributes>
				<attribute>
					<name> 
						<literal expr="color."/> 
						<extract expr="@type"/> 
					</name>
					<value> 
						<extract expr="@value"/> 
					</value>
				</attribute>
			</attributes>
		</mapping>
	</feature-content-map>
</xfMap>

When the points2.xml and feature_content.xmp documents are fed into the XML Reader, the FME features output are:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Feature Type: '
Attribute: color.blue' has value 0.596'
Attribute: color.green' has value 0.233'
Attribute: color.red' has value 0.324'
Attribute: xml_type' has value xml_no_geom'
Geometry Type: Unknown (0)
=============================================================
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Feature Type: '
Attribute: color.blue' has value 0.554'
Attribute: color.green' has value 0.948'
Attribute: color.red' has value 0.874'
Attribute: xml_type' has value xml_no_geom'
Geometry Type: Unknown (0)
=============================================================

Here is what happens:

Step

feature-search-set contents (after step)

state of mapping rule Rp (after step)

1.

The feature-search-set is initialized:

No feature mapping rules are executing, so the mapping rules defined in <feature-map> element in the feature_content.xmp document are added to the feature-search-set.

{R1}

R1: de-activated

R2: de-activated

2.

The XML Reader reads the start-tag of the <points> element:

No mapping rules in the feature-search-set matches the <points> element. The reader continues reading the contents of the <points> element.

{R1}

R1: de-activated

R2: de-activated

3.

The XML Reader reads the start-tag of a <point> element:

The mapping rule R1 in the feature-search-set matches the <point> element. R1 is activated. R1 is also in the state of execution because the <point> element is currently the context element.

Since at least one feature mapping rule is activated (i.e., R1), the contents of the feature-search-set will then default to contain the mapping rules under the <feature-content-map> element, in this case, it is just R2.

{R2}

R1: activated, executing

R2: de-activated

 

4.

The XML Reader reads the start-tag of a <color> element:

The mapping rule R2 in the feature-search-set matches the <color> element. R2 is activated. No brand new FME features is created because R2 was defined in the <feature-content-map> element. The <color> element is also the context element so that R1 is suspended, and R2 is now executing.

The feature mapping rule R2 has an <attributes> element, R2 provides these attributes to the FME feature that is being constructed.

{R2}

 

R1: activated, suspended

R2: activated, executing

 

5.

The <color> element end-tag is read. This <color> element initially triggered the activation of R2, so R2 is de-activated (see the section titled mapping rule states).

The feature-search-set does not change, since there is least one activated feature mapping rule, that is R1.

{R2}

 

R1: activated, executing

R2: de-activated

6.

Step 4) and 5) are repeated for the next two <color> elements.

{R2}

...

7.

The <point> element end-tag is read.

R1 is de-activated. The XML Reader considers the FME feature under construction to be complete when R1 de-activates, this is because R1 is a feature mapping rule defined in the <feature-map> element.

No feature mapping rules are activated, so the mapping rules defined in <feature-map> element in the feature_content.xmp document becomes the feature-search-set.

{R1}

R1: de-activated

R2: de-activated

 

8.

Steps 3) through 7) are repeated for the second <point> element.

...

...

9.

The <points> element end-tag is read. The XML Reader has finished reading the input XML document.

{}

R1: de-activated

R2: de-activated

Consider another example:

points3.xml

<?xml version="1.0"?>

<points>
	<point name="myPoint" num="0">
		<outline>
			<color type="red" value="1.0"/>
			<color type="green" value="1.0"/>
			<color type="blue" value="1.0"/>
		</outline>
		<fill>
			<color component="red">0.324</color>
			<color component="green">0.233</color>
			<color component="blue">0.596</color>
		</fill>
		<location x="10.0" y="0.0"/>
	</point>
	<point name="myPoint" num="1">
		<outline>
			<color type="red" value="0.5"/>
			<color type="green" value="0.5"/>
			<color type="blue" value="0.5"/>
		</outline>
		<fill>
			<color component="red">0.874</color>
			<color component="green">0.948</color>
			<color component="blue">0.554</color>
		</fill>
		<location x="5.0" y="5.0"/>
	</point>
</points>

feature_content2.xmp

<?xml version="1.0">
<!DOCTYPE xfMap SYSTEM "xfMap.dtd">

<xfMap>
	<feature-map>
		<mapping match="point">
			<feature-type>
				<extract expr="@name"/> 
				<literal expr="_"/>
				<extract expr="@num"/>
			</feature-type>
			<attributes>
				<attribute>
					<name> <literal expr="location.x"/> </name>
					<value> <extract expr="location[@x]"/> </value>
				</attribute>
				<attribute>
					<name> <literal expr="location.y"/> </name>
					<value> <extract expr="location[@y]"/> </value>
				</attribute>
			</attributes>
		</mapping>
	</feature-map>
	
	<feature-content-map>
		<mapping match="outline/color">
			<attributes>
				<attribute>
					<name> 
						<literal expr="outline_color."/> 
						<extract expr="@type"/>
					</name>
					<value> <extract expr="@value"/> </value>
				</attribute>
			</attributes>
		</mapping>
		<mapping match="fill/color">
			<attributes>
				<attribute>
					<name>
						<literal expr="fill_color."/>
						<extract expr="@component"/>
					</name>
					<value> <extract expr="."/> </value>
				</attribute>
			</attributes>
		</mapping>
	</feature-content-map>
</xfMap>

When the points3.xml, feature_content2.xmp documents are input into the XML Reader, the following FME features are output:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Feature Type: myPoint_0'
Attribute: fill_color.blue' has value 0.596'
Attribute: fill_color.green' has value 0.233'
Attribute: fill_color.red' has value 0.324'
Attribute: location.x ' has value 10.0'
Attribute: location.y ' has value 0.0'
Attribute: outline_color.blue' has value 1.0'
Attribute: outline_color.green' has value 1.0'
Attribute: outline_color.red' has value 1.0'
Attribute: xml_type' has value xml_no_geom'
Geometry Type: Unknown (0)
=============================================================
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Feature Type: myPoint_1'
Attribute: fill_color.blue' has value 0.554"'
Attribute: fill_color.green' has value 0.948'
Attribute: fill_color.red' has value 0.874'
Attribute: location.x ' has value 5.0'
Attribute: location.y ' has value 5.0'
Attribute: outline_color.blue' has value 0.5'
Attribute: outline_color.green' has value 0.5'
Attribute: outline_color.red' has value 0.5'
Attribute: xml_type' has value xml_no_geom'
Geometry Type: Unknown (0)
=============================================================