FME Feature Construction

To construct an FME feature, a mapping rule, say R0, that is defined under the <feature-map> element must be activated. The feature is considered to be completely constructed when R0 de-activates (see the section titled Mapping Rule States (activation, execution, suspension, and de-activation) for the possible states of an xfMap mapping rule).

We’ll use the following input XML document, points1.xml, to illustrate how a feature mapping rule from the xfMap document, features.xmp, directs the XML Reader to construct FME features.

points1.xml

<?xml version="1.0"?>
<points>
	<point name="myPoint" num="0">
		<color>
			<red>0.324</red>
			<green>0.233</green>
			<blue>0.596</blue>
		</color>
		<location x="10.0" y="0.0"/>
	</point>
	<point name="myPoint" num="1">
		<color>
			<red>0.874</red>
			<green>0.948</green>
			<blue>0.554</blue>
		</color>
		<location x="5.0" y="5.0"/>
	</point>
</points>

The above XML document contains two <point> elements for which we want FME features to map into. To do this, we must define a feature mapping rule under the <feature-map> element that activates when a <point> element start-tag is read.

Note: Recall that a mapping rule R, from an active-search-set, is activated when the XML Reader reads the start-tag of an element E, in the input XML document stream, when R matches E.

The following xfMap document, features.xmp, contains a feature mapping rule Rp, defined in the <feature-map> element, that matches a <point> element.

features.xmp

<?xml version="1.0"?>
<!DOCTYPE xfMap SYSTEM "xfMap.dtd">
<xfMap>
	<feature-map>
		<!-- call this mapping rule Rp -->
		<mapping match="point">	 
		</mapping>
	</feature-map>					 
</xfMap>

When the above XML (points1.xml) and xfMap (features.xmp) documents are fed into the XML Reader two FME features are constructed. The following is a FME log for the constructed features:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Feature Type: '
Attribute: xml_type' has value xml_no_geom'
Geometry Type: Unknown (0)
=============================================================
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Feature Type: '
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 activated, so all mapping rules defined in the <feature-map> element are included in the feature-search-set.	{Rp}	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. No mapping rules are activated. The reader continues reading the contents of the <points> element.	{Rp}	de-activated
3.	The XML Reader reads the start-tag a <point> element: The mapping rule Rp in the feature-search-set matches the <point> element. Rp is activated. Rp is also in the state of execution because the <point> element is currently the context element. Since Rp was defined under the <feature-map> element, Rp directs the XML Reader to start the construction of a new FME feature. Now that a feature mapping rule is activated, the feature-search-set is modified to contain mapping rules from the <feature-content-map> element. (The features.xmp xfMap document has no <feature-content-map> element, the feature-search-set then becomes the empty set).	{}	activated, executing
4.	The XML Reader reads the start-tag of a <color> element. No mapping rules in the feature-search-set match the <color> element (the feature-search-set is empty).	{}	activated, suspended
5.	The XML Reader reads the start-tag of a <red> element. Again, no mapping rules are activated.	{}	activated, suspended
6.	The <red> element is end-tag is read. The <red> element did not cause the activation of any mapping rules, therefore no mapping rules are de-activated.	{}	activated, suspended
7.	5) and 6) are repeated for the <green> and <blue> elements.	{}	activated, suspended
8.	The <color> element end-tag is read. The <color> element did not cause the activation of any mapping rules, therefore no mapping rules are de-activated.	{}	activated, executing
9.	The XML Reader the start-tag of the <location> element. No feature mapping rules are activated (the feature-search-map is empty).	{}	activated, suspended
10.	The <location> element end-tag is read. The <location> element did not cause activation of any mapping rules, therefore no mapping rules are de-activated.	{}	activated, executing
11.	The <point> element end-tag is read. Rp is de-activated (see the mapping rule states section). The XML Reader considers the FME feature under construction to be complete when Rp de-activates. There are now no feature mapping rules activated so the feature-search-set now contains all the mapping rules that defined in the <feature-map> element (i.e, Rp).	{Rp}	de-activated
12.	Steps 3) through 11) are repeated for the second <point> element of the input stream. A blank FME feature is again output by the XML Reader.	...	...
13.	The <points> element end-tag is read. The XML Reader has finished reading the input XML document.	{}	de-activated

FME features constructed by the XML Reader always carry an xml_type attribute. This attribute is always initialized to xml_no_geom. Until now, the XML Reader has only constructed blank features: for the reader to construct other parts of an FME feature, a feature mapping rule should contain the following elements:

1. feature-type element: is an optional element that directs the XML Reader to set the feature type of an FME feature.
2. attributes element: is an optional element that directs the XML Reader to set one or more attributes for an FME feature.
3. geometry element: is an optional element that directs the XML Reader to construct the geometry of an FME.