XMLAppender

Input features containing the main XML document.

Input features containing the XML fragments.

This is the output for the main XML document with the appended fragments.

Multiple main documents are allowed only if the Group By parameter is used, otherwise duplicate main documents are output via this port. The main documents are considered a duplicate of each other when the values of their composite Group By key equal.

Fragments with no corresponding Group By main XML document are output via this port.

Use this parameter to organize multiple main documents and fragments into groups. Multiple main XML documents are allowed when their composite Group By key differ. Unused documents and fragments, those without corresponding keys, are routed to the UnusedDocument and UnusedFragment ports, respectively.

Note: How parallel processing works with FME: see About Parallel Processing for detailed information.

This parameter determines whether or not the transformer should perform the work across parallel processes. If it is enabled, a process will be launched for each group specified by the Group By parameter.

Parallel Processing Levels

For example, on a quad-core machine, minimal parallelism will result in two simultaneous FME processes. Extreme parallelism on an 8-core machine would result in 16 simultaneous processes.

You can experiment with this feature and view the information in the Windows Task Manager and the Workbench Log window.

No: This is the default behavior. Processing will only occur in this transformer once all input is present.

By Group: This transformer will process input groups in order. Changes of the value of the Group By parameter on the input stream will trigger batch processing on the currently accumulating group. This will improve overall speed if groups are large/complex, but could cause undesired behavior if input groups are not truly ordered. Specifically, on a two input-port transformer, "in order" means that an entire group must reach both ports before the next group reaches either port, for the transformer to work as expected. This may take careful consideration in a workspace, and should not be confused with both port's input streams being ordered individually, but not synchronously.

Considerations for Using Input is Ordered By

Using Ordered input can provide performance gains in some scenarios, however, it is not always preferable, or even possible. Consider the following when using it, with both one- and two-input transformers.

Single Datasets/Feature Types: Are generally the optimal candidates for Ordered processing. If you know that the dataset is correctly ordered by the Group By attribute, using Input is Ordered By can improve performance, depending on the size and complexity of the data.

If the input is coming from a database, using ORDER BY in a SQL statement to have the database pre-order the data can be an extremely effective way to improve performance. Consider using a Database Readers with a SQL statement, or the SQLCreator transformer.

Multiple Datasets/Feature Types: Since all features matching a Group By value need to arrive before any features (of any feature type or dataset) belonging to the next group, using Ordering with multiple feature types is more complicated than processing a single feature type.

Multiple feature types and features from multiple datasets will not generally naturally occur in the correct order.

One approach is to send all features through a Sorter, sorting on the expected Group By attribute. The Sorter is a feature-holding transformer, collecting all input features, performing the sort, and then releasing them all. They can then be sent through an appropriate filter (TestFilter, AttributeFilter, GeometryFilter, or others), which are not feature-holding, and will release the features one at a time to the transformer using Input is Ordered By, now in the expected order.

The processing overhead of sorting and filtering may negate the performance gains you will get from using Input is Ordered By. In this case, using Group By without using Input is Ordered By may be the equivalent and simpler approach.

In all cases when using Input is Ordered By, if you are not sure that the incoming features are properly ordered, they should be sorted (if a single feature type), or sorted and then filtered (for more than one feature or geometry type).

As with many scenarios, testing different approaches in your workspace with your data is the only definitive way to identify performance gains.

Selecting from the list enables that selection's corresponding parameter:

• Attribute with XML Document: Choose the attribute containing the main XML document.
• XML Document Filename: Browse to the XML file.

This parameter controls how the fragments are inserted into the document in relation to a selected or matched element. The possible values for the parameter are:

• Preceding Children
• Succeeding Children
• Preceding Siblings
• Succeeding Siblings

The values are to be understood in relation to the selected or matched element, which is specified by the Append Path In Document parameter.

The default value for this parameter is Succeeding Children.

This parameter specifies a single element, or a path to a single element, in the document. Each element in the path is separated by a forward slash, ‘/’. A wildcard, ‘*’, may also be used as the prefix or local-name of the element (for example, ‘*:e’, ‘p:*’, or just ‘*’, which translates to ‘*:*’).

The parameter’s default value is the empty string. This will match or select the root element.

Consider the following XML document:

<data>

<metadata>…</metadata>

<initialize>…</initialize>

<!--Insert XML fragments here -->

<finalize>…</finalize>

</data>

To insert fragments after the <initialize> element we can either:

1) Specify Append Path In Document as "data/initialize", and

2) Set Append Fragments As to Succeeding Siblings

or:

1) Specify Append Path In Document as "data/finalize", and

2) Set Append Fragments As to Preceding Siblings

Selecting from the list enables that selection's corresponding parameter:

• Attribute with XML Fragment: Choose the attribute containing the XML Fragment.
• XML Fragment Filename: Browse to the XML file.

Selecting from the list enables that selection's corresponding parameter:

• Attribute with XML Output: Choose the attribute to hold the appended results.
• XML Output File: Specifies the file to contain the appended results.

This parameter is used to select the encoding for the appended results.

The parameter specifies if the XML output should be pretty-printed with indentation.

This parameter specifies the size of a single indentation.

By default, the tab character is used for pretty printing, use this parameter to replace the tabs with spaces.

By default, the text within a tag is left untouched. If this parameter is set to Yes, the text will be pretty printed. If a tag contains both a text value element and another nested tag element, the second of either the text value or nested tag will not be pretty printed. The example below shows a block of XML code on the left along with its pretty printed output on the right.