Use-Mappings Element (limiting the active-search-set)

The <use-mappings> element of an executing mapping rule changes the default contents of an active-search-set (see the Contents of an active-search-set (Default Contents)). It limits the contents of an active-search-set to the mapping rules listed under its <use> elements.

For example, if the following is a feature mapping rule:

<mapping match=”...”>
	...
	<use-mappings>
		<use name=”mr1”/>
		<use name=”mr2”/>
    </use-mappings>
</mapping>

Then, when the above feature mapping rule is executing, its feature-search-set (recall that the feature-search-set is the feature mapping rule’s active-search-set) will only contain the feature mapping rules mr1 and mr2.

Consider the following input XML document:

drawing.xml

<?xml version=”1.0”?>

<drawing>
	<figure>
		<color type=”background”>
			<component type=”red”>0.949</component>
			<component type=”green”>0.357</component>
			<component type=”blue”>0.283</component>
		</color>
		<color type=”foreground”>
			<component type=”red”>0.532</component>
			<component type=”green”>0.899</component>
			<component type=”blue”>0.521</component>
		</color>
	</figure>	
</drawing>

The following xfMap document maps the above <figure> element into an FME feature:

drawing.xmp

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

<xfMap>
	<feature-map>
		<mapping match=”figure”>
			<feature-type> <literal expr=”figure”/> </feature-type>
		</mapping>		
	</feature-map>

	<feature-content-map>
		<mapping match=”color”>
			<!-- The use-mappings element will limit the feature-search-set
				to contain only the mr_colors mapping rule.
				
				The value of the type attribute from the color element is
				passed as an argument to the mr_colors mapping rule.-->
			<use-mappings>
				<use name=”mr_colors”>
					<args>
						<arg> <extract expr=”@type”/> </arg>
					</args>
				</use>
			</use-mappings>
		</mapping>

		<mapping match=”component”>
			<-- The signature of this mapping rule has 1 named parameter
				called colorType, its value is passed as an argument from
				the mapping rule above. -->
			<signature name=”mr_colors”>
				<params>
					<param name=”colorType”/>
				</params>
			</signature>

			<attributes>
				<attribute>
					<name>
						<!-- Access the colorType parameter. -->
						<parmval expr=”colorType”/>
						<literal expr=”.”/>
						<extract expr=”@type”/>
					</name>
					<value> <extract expr=”.”/> </value>
				</attribute>
			</attributes>

			<-- NOTE: This mapping rule does not have a use-mappings element.
				When this mapping rule is executing the feature-search-set is
				set to its default contents. That is, all of the feature mapping
			rules defined under the feature-content-map -->
		</mapping>
	</feature-content-map>
</xfMap>

The FME feature created is:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Feature Type: `figure'
Attribute: `background.blue' has value `0.283'
Attribute: `background.green' has value `0.357'
Attribute: `background.red' has value `0.949'
Attribute: `foreground.blue' has value `0.521'
Attribute: `foreground.green' has value `0.899'
Attribute: `foreground.red' has value `0.532'
Attribute: `xml_type' has value `xml_no_geom'
Geometry Type: Unknown (0)
=======================================================================