A group is persistent if the group mapping rule that defines it has a <persist> element.
A persistent group that is not the last group in the g-stack will not be destroyed when its corresponding mapping rule de-activates.
Note: A group mapping rule defined under the <group-map> element may have a <persist> element, but this indication for the group to persist is always ignored by the XML Reader, this group, by construction, will always be the last one left in the g-stack (see Group Construction and Destruction).
When a persistent group is popped from the g-stack it can persist inside other g-stack groups. The <persist> element has an optional in attribute that specifies where it may persist. The valid values for this attribute are parent-group and base-group (where parent_group is the default value):
<persist in=”...”>
The parent-group of a persistent group is the group that will be at the top of the g-stack when the persistent group is popped. The base-group is the group that is at the base of the g-stack; it is the first group pushed into the stack; it is the group constructed from the activation of a group mapping rule that was defined under the <group-map> element.
FME features that are constructed by feature mapping rules will enter all the groups that are in the g-stack from the top until the bottom of the stack. If a group in the stack has persistent groups, then the features will first enter the persistent groups before entering into the group’s own attribute sets and pipelines.
The following example shows why persistent groups are sometimes needed.
group_persist.xml
<?xml version=”1.0”?> <group> <group-property name=”section”>C-23</group-property> <group-property name=”location”>Z-Edifice</group-property> <group-property name=”op-code”>580ld-3</group-property> <member id=”290”/> <member id=”350”/> <member id=”300”/> </group>
We want to map each <member> element into an FME feature, but we’ll also like to attach the information from each of the <group-property> elements to the member feature. The following xfMap document achieves this by the usage of persistent groups:
group_persist.xmp
<?xml version=”1.0”?> <!DOCTYPE xfMap SYSTEM ”xfMap.dtd”> <xfMap> <group-map> <!-- We create a group here for the sole purpose of having a group to persist on. The groups constructed in the group-content-map may persist in this group. Features that enter this group will be processed by this group’s ‘persistent groups attribute sets’. --> <mapping match=”group”/> </group-map> <group-content-map> <mapping match=”group-property”> <!-- The group is constructed and pushed into the g-stack when the group-property start-tag is read, when the end-tag is read, then the group is popped from the g-stack. The group is not destroyed, it will persist in its parent-group, in this case it is the group that is constructed in the group-map above. We make this group persist, since otherwise this group is destroyed when the group-property element end-tag is read so that this group attribute set will not be attached to any feature.--> <persist/> <apply-attribute-sets> <attribute-set> <attributes> <attribute> <name> <extract expr=”@name”/> </name> <value> <extract expr=”.”/> </value> </attribute> </attributes> </attribute-set> </apply-attribute-sets> </mapping> </group-content-map> <feature-map> <mapping match=”member”> <feature-type> <literal expr=”member-”/> <extract expr=”@id”/> </feature-type> </mapping> </feature-map> </xfMap>
The two documents above make the XML Reader output the following FME features:
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Feature Type: `member-290' Attribute: `location' has value `Z-Edifice' Attribute: `op-code' has value `580ld-3' Attribute: `section' has value `C-23' Attribute: `xml_type' has value `xml_no_geom' Geometry Type: Unknown (0) =========================================================================== +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Feature Type: `member-350' Attribute: `location' has value `Z-Edifice' Attribute: `op-code' has value `580ld-3' Attribute: `section' has value `C-23' Attribute: `xml_type' has value `xml_no_geom' Geometry Type: Unknown (0) =========================================================================== +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Feature Type: `member-300' Attribute: `location' has value `Z-Edifice' Attribute: `op-code' has value `580ld-3' Attribute: `section' has value `C-23' Attribute: `xml_type' has value `xml_no_geom' Geometry Type: Unknown (0) ===========================================================================
A group actually contains two places where it may adopt persistent groups. By default the group adopts a persistent group in its low-priority list, the <persist> element has an optional priority attribute that specifies if a persistent group should be adopted into a group’s low- or high-priority lists.
A group will always process FME features through its high-priority persistent groups before the low-priority ones. The valid values for the priority attribute are low and high, with low being the default value.
For example, the following group mapping rule defines a persistent group to persist in its parent group high-priority list:
<group-content-map> <mapping match=”manifold”> <persist in=”parent-group” priority=”high”/> ... </mapping> </group-content-map>