XMLXPathReader

Home \| Table of Contents	XMLXPathReader
Prev	Readers	Next

We assume that you have already learned what is described in:

If you want to find the right Reader for your purposes, see Readers Comparison.

Short Summary

XMLXPathReader reads data from XML files.

Component	Data source	Input ports	Output ports	Each to all outputs¹⁾	Different to different outputs²⁾	Transformation	Transf. req.	Java	CTL
XMLXPathReader	XML file	0-1	1-n	no	yes	no	no	no	no

Legend

1) Component sends each data record to all connected output ports.

2) Component sends different data records to different output ports using return values of the transformation (DataGenerator and MultiLevelReader). See Return Values of Transformations for more information. XMLExtract and XMLXPathReader send data to ports as defined in their Mapping or Mapping URL attribute.

Abstract

XMLXPathReader reads data from XML files using DOM technology. It can also read data from compressed files, console, input port, and dictionary. This component is slower than XMLExtract, which can read XML files too.

Icon

Ports

Port type	Number	Required	Description	Metadata
Input	0	no	For port reading. See Reading from Input Port.	One field (`byte`, `cbyte`, `string`).
Output	0	yes	For correct data records	Any¹⁾
Output	1-n	2)	For correct data records	Any¹⁾ (each port can have different metadata)

Legend:

1): The metadata on each of the output ports does not need to be the same. Each of these metadata can use Autofilling Functions.

2): Other output ports are required if mapping requires that.

XMLXPathReader Attributes

Attribute	Req	Description	Possible values
Basic
File URL	yes	Attribute specifying what data source(s) will be read (XML file, console, input port, dictionary). See Supported File URL Formats for Readers.
Charset		Encoding of records that are read.	ISO-8859-1 (default) \| <other encodings>
Data policy		Determines what should be done when an error occurs. See Data Policy for more information.	Strict (default) \| Controlled \| Lenient
Mapping URL	1)	Name of external file, including path, defining mapping of XML structure to output ports. See XMLXPathReader Mapping Definition for more information.
Mapping	1)	Mapping of XML structure to output ports. See XMLXPathReader Mapping Definition for more information.
Advanced
XML features		Sequence of individual expressions of one of the following form: `nameM:=true` or `nameN:=false`, where each `nameM` is an XML feature that should be validated. These expressions are separated from each other by semicolon. See XML Features for more information.
Number of skipped mappings		Number of mappings to be skipped continuously throughout all source files. See Selecting Input Records.	0-N
Max number of mappings		Maximum number of records to be read continuously throughout all source files. See Selecting Input Records.	0-N

Legend:

1) One of these must be specified. If both are specified, Mapping URL has higher priority.

Advanced Description

Example 53.5. Mapping in XMLXPathReader

<Context xpath="/employees/employee" outPort="0">
    <Mapping nodeName="salary" cloudconnectField="basic_salary"/>
    <Mapping xpath="name/firstname" cloudconnectField="firstname"/>
    <Mapping xpath="name/surname" cloudconnectField="surname"/>
    <Context xpath="child" outPort="1" parentKey="empID" generatedKey="parentID"/>
    <Context xpath="benefits" outPort="2" parentKey="empID;jobID" generatedKey="empID;jobID" 
                              sequenceField="seqKey" sequenceId="Sequence0">
        <Context xpath="financial" outPort="3" parentKey="seqKey" generatedKey="seqKey"/>
    </Context>
    <Context xpath="project" outPort="4" parentKey="empID;jobID" generatedKey="empID;jobID">
        <Context xpath="customer" outPort="5" parentKey="projName;projManager;inProjectID;Start" 
                                  generatedKey="joinedKey"/>
    </Context>
</Context>

Note

Nested structure of <Context> tags is similar to the nested structure of XML elements in input XML files.

However, Mapping attribute does not need to copy all XML structure, it can start at the specified level inside the whole XML file.

XMLXPathReader Mapping Definition

Every Mapping definition (both the contents of the file specified in the Mapping URL attribute and the Mapping attribute) consists of <Context> tags which contain also some attributes and allow mapping of element names to CloudConnect fields.
Each <Context> tag can surround a serie of nested <Mapping> tags. These allow to rename XML elements to CloudConnect fields.
Each of these <Context> and <Mapping> tags contains some XMLXPathReader Context Tag Attributes and XMLXPathReader Mapping Tag Attributes, respectively.
XMLXPathReader Context Tags and Mapping Tags
- Empty Context Tag (Without a Child)
  <Context xpath="xpathexpression" XMLXPathReader Context Tag Attributes />
- Non-Empty Context Tag (Parent with a Child)
  <Context xpath="xpathexpression" XMLXPathReader Context Tag Attributes >
  (nested Context and Mapping elements (only children, parents with one or more children, etc.)
  </Context>
- Empty Mapping Tag (Renaming Tag)
  - xpath is used:
    <Mapping xpath="xpathexpression" XMLXPathReader Mapping Tag Attributes />
  - nodeName is used:
    <Mapping nodeName="elementname" XMLXPathReader Mapping Tag Attributes />

XMLXPathReader Context Tag and Mapping Tag Attributes

1) XMLXPathReader Context Tag Attributes

xpath
Required
The xpath expression can be any XPath query.
Example: xpath="/tagA/.../tagJ"
outPort
Optional
Number of output port to which data is sent. If not defined, no data from this level of Mapping is sent out using such level of Mapping.
Example: outPort="2"
parentKey
Both parentKey and generatedKey must be specified.
Sequence of metadata fields on the next parent level separated by semicolon, colon, or pipe. Number and data types of all these fields must be the same in the generatedKey attribute or all values are concatenated to create a unique string value. In such a case, key has only one field.
Example: parentKey="first_name;last_name"
Equal values of these attributes assure that such records can be joined in the future.
generatedKey
Both parentKey and generatedKey must be specified.
Sequence of metadata fields on the specified level separated by semicolon, colon, or pipe. Number and data types of all these fields must be the same in the parentKey attribute or all values are concatenated to create a unique string value. In such a case, key has only one field.
Example: generatedKey="f_name;l_name"
Equal values of these attributes assure that such records can be joined in the future.
sequenceId
When a pair of parentKey and generatedKey does not insure unique identification of records, a sequence can be defined and used.
Id of the sequence.
Example: sequenceId="Sequence0"
sequenceField
When a pair of parentKey and generatedKey does not insure unique identification of records, a sequence can be defined and used.
A metadata field on the specified level in which the sequence values are written. Can serve as parentKey for the next nested level.
Example: sequenceField="sequenceKey"

namespacePaths

Optional

Default namespaces that should be used for the xpath attribute specified in the <Context> tag.

Pattern: namespacePaths='prefix1="URI1";...;prefixN="URIN"'

Example: namespacePaths='n1="http://www.w3.org/TR/html4/";n2="http://ops.com/"'.

	Note
	Remember that if the input XML file contains a default namespace, this `namespacePaths` must be specified in the corresponding place of the Mapping attribute. In addition, `namespacePaths` is inherited from the `<Context>` element and used by the `<Mapping>` elements.

2) XMLXPathReader Mapping Tag Attributes

xpath
Either xpath or nodeName must be specified in <Mapping> tag.
XPath query.
Example: xpath="tagA/.../salary"
nodeName
Either xpath or nodeName must be specified in <Mapping> tag. Using nodeName is faster than using xpath.
XML node that should be mapped to CloudConnect field.
Example: nodeName="salary"
cloudconnectField
Required
CloudConnect field to which XML node should be mapped.
Name of the field in the corresponding level.
Example: cloudconnectFields="SALARY"
trim
Optional
Specifies whether leading and trailing white spaces should be removed. By default, it removes both leading and trailing white spaces.
Example: trim="false" (white spaces will not be removed)

namespacePaths.

Optional

Default namespaces that should be used for the xpath attribute specified in the <Mapping> tag.

Pattern: namespacePaths='prefix1="URI1";...;prefixN="URIN"'

Example: namespacePaths='n1="http://www.w3.org/TR/html4/";n2="http://ops.com/"'.

	Note
	Remember that if the input XML file contains a default namespace, this `namespacePaths` must be specified in the corresponding place of the Mapping attribute. In addition, `namespacePaths` is inherited from the `<Context>` element and used by the `<Mapping>` elements.