ComposantsComponents

ComposantsComponents › XML

tExtractXMLField

tExtractXMLField

XML Traitement › ChampsProcessing › Fields

Lit le document XML contenu dans une colonne du flux (String ou Document) et en extrait des champs par XPath : chaque élément trouvé par la requête de boucle donne une ligne de sortie, dont les colonnes sont remplies par des requêtes relatives à cet élément. Les colonnes sans requête reprennent la colonne d'entrée de même nom. C'est le tFileInputXML (mode Dom4j) appliqué à une colonne : pour un XML reçu d'un service, d'une base ou d'un tWriteXMLField. Reads the XML document held in a column of the flow (String or Document) and extracts fields from it by XPath: each element found by the loop query gives an output row, whose columns are filled by queries relative to this element. The columns without a query take the input column of the same name. It is the tFileInputXML (Dom4j mode) applied to a column: for an XML received from a service, a database or a tWriteXMLField.

EntréeInput

Main un flux, avec la colonne XMLone flow, with the XML column

SortiesOutputs

Main obligatoire : une ligne par élément de la boucle.required: one row per loop element. Reject facultatif, masqué si Arrêter en cas d'erreur est coché.optional, hidden if Die on error is checked.

Déclencheurs en sortieOutput triggers

On Component Ok On Component Error Run if

UtilisationUsage

Découper une réponse XMLSplitting an XML response

row1 (Response) row2 (Main) tRESTClient_1 tExtractXMLField_1 tLogRow_1

La colonne body (Document) de la réponse du tRESTClient devient une ligne par élément répété. The body column (Document) of the tRESTClient response becomes one row per repeated element.

Écarter les lignes en erreurSetting aside the rows in error

row1 (Main) row2 (Main) row3 (Reject) tFixedFlowInput_1 tExtractXMLField_1 tLogRow_1 tLogRow_2

Un XML mal formé ou une valeur qui ne se convertit pas sortent sur le lien Reject, avec le message d'erreur. A malformed XML or a value that does not convert leave on the Reject link, with the error message.

  1. Déposez le tExtractXMLField depuis la famille XML (ou Traitement › Champs) de la palette et reliez-lui le flux qui porte le XML. Drop the tExtractXMLField from the XML (or Processing › Fields) family of the palette and connect the flow that carries the XML to it.
  2. Choisissez la colonne dans Champ XML et écrivez la Requête XPath boucle, absolue : "/order/line". Choose the column in XML field and write the Loop XPath query, absolute: "/order/line".
  3. Décrivez les colonnes de sortie dans le Schéma ; la table Mapping reçoit une ligne par colonne. Écrivez la requête de chacune, relative à l'élément de la boucle, ou laissez-la vide pour reprendre la colonne d'entrée de même nom. Describe the output columns in the Schema; the Mapping table gets one row per column. Write the query of each one, relative to the loop element, or leave it empty to take the input column of the same name.

Paramètres simplesBasic settings

Les libellés sont ceux de l'onglet Composant ; le nom technique, en gris, est celui du paramètre dans le fichier du job. Les requêtes sont des expressions Java : "/order/line", "@sku". Labels are those of the Component tab; the technical name, in grey, is the parameter name in the job file. Queries are Java expressions: "/order/line", "@sku".

ParamètreSetting DéfautDefault VisibleShown Description
Type de propriétéProperty TypePROPERTY Built-in ToujoursAlways Built-in : réglages saisis dans le composant. Référentiel : la boucle, les requêtes et la limite viennent d'une métadonnée Fichier XML d'entrée. Built-In: settings typed in the component. Repository: the loop, the queries and the limit come from an input XML file metadata.
SchémaSchemaSCHEMA — ToujoursAlways Les colonnes de sortie. Le type de chaque colonne décide de la conversion de la valeur trouvée ; sa valeur par défaut remplace un nœud absent (voir les valeurs absentes). The output columns. The type of each column decides how the value found is converted; its default value replaces a missing node (see the missing values).
Champ XMLXML fieldXMLFIELD — ToujoursAlways La colonne d'entrée qui contient le document, de type String ou Document. Une valeur null ne donne aucune ligne, ni en sortie ni en rejet. The input column that holds the document, of type String or Document. A null value gives no row, neither in output nor in reject.
Requête XPath boucleLoop XPath queryLOOP_QUERY "/bills/bill/line" ToujoursAlways Les éléments répétés, chacun donnant une ligne, par un chemin absolu depuis la racine. Rien de trouvé : aucune ligne pour ce document, sans erreur. The repeated elements, each giving a row, through an absolute path from the root. Nothing found: no row for this document, without an error.
MappingMAPPING une ligne par colonneone row per column ToujoursAlways Colonne : la colonne du schéma. Requête XPath : relative à l'élément de la boucle ("label", "@sku", "../@id", fonctions XPath 1.0) ; plusieurs nœuds trouvés, le premier est pris ; vide, la colonne reprend la colonne d'entrée de même nom. Obtenir les nœuds : la colonne reçoit l'élément trouvé en XML, balises comprises, au lieu de son texte (voir l'exemple). Column: the schema column. XPath query: relative to the loop element ("label", "@sku", "../@id", XPath 1.0 functions); several nodes found, the first one is taken; empty, the column takes the input column of the same name. Get Nodes: the column gets the element found as XML, tags included, instead of its text (see the example).
LimiteLimitLIMIT videempty ToujoursAlways Nombre maximal de lignes ; vide : toutes. Le compte vaut pour tout le flux, pas pour chaque document (voir les pièges). Maximum number of rows; empty: all of them. The count applies to the whole flow, not to each document (see the pitfalls).
Arrêter en cas d'erreurDie on errorDIE_ON_ERROR NonNo ToujoursAlways Cochée, la première erreur (XML mal formé, valeur qui ne se convertit pas) arrête le job. Décochée, la ligne en erreur part sur le lien Reject s'il existe ; sinon le message est écrit sur la sortie d'erreur et la ligne est perdue (voir les exemples). Checked, the first error (malformed XML, value that does not convert) stops the job. Unchecked, the row in error leaves on the Reject link if there is one; otherwise the message is written to the error output and the row is lost (see the examples).

Paramètre avancéAdvanced setting

ParamètreSetting DéfautDefault VisibleShown Description
Ignorer les espaces de nomsIgnore the namespacesIGNORE_NS NonNo ToujoursAlways Recopie le document sans ses espaces de noms ni ses préfixes avant la lecture : les requêtes s'écrivent sans préfixe (voir les exemples). Copies the document without its namespaces and prefixes before reading it: the queries are written without prefix (see the examples).

Variable globale et lien RejectGlobal variable and Reject link

NB_LINE (Integer, disponible après l'exécution du composant) : nombre d'éléments trouvés par la boucle, tous documents confondus, rejetés compris. Un document illisible ne compte pas. NB_LINE (Integer, available after the component has run): number of elements found by the loop, all documents together, rejected ones included. An unreadable document does not count.

((Integer) globalMap.get("tExtractXMLField_1_NB_LINE"))

Le schéma du lien Reject reprend les colonnes de sortie, plus errorXMLField (le document en erreur), errorCode (jamais rempli) et errorMessage (le message, suivi de - Line: et du nombre de lignes déjà traitées par le composant, à partir de 0). Pour un XML mal formé, seules les colonnes reprises de l'entrée sont remplies ; pour une conversion, les colonnes extraites avant celle en erreur. The schema of the Reject link takes the output columns, plus errorXMLField (the document in error), errorCode (never filled) and errorMessage (the message, followed by - Line: and the number of rows already handled by the component, from 0). For a malformed XML, only the columns taken from the input are filled; for a conversion, the columns extracted before the one in error.

ExemplesExamples

Un tFixedFlowInput envoie des lignes id (Integer), xml (String) au tExtractXMLField_1, dont la sortie est affichée par un tLogRow. Un tJava relié par On Subjob Ok affiche NB_LINE. Les sorties sont copiées depuis des exécutions des jobs dans Talaxie (Java 21). Les deux documents des exemples : A tFixedFlowInput sends rows id (Integer), xml (String) to tExtractXMLField_1, whose output is printed by a tLogRow. A tJava connected with On Subjob Ok prints NB_LINE. The outputs are copied from runs of the jobs in Talaxie (Java 21). The two documents of the examples:

id 1 : <order id="A1"><customer>Ada</customer>
         <line sku="P-10" qty="2"><label>Pen</label><price>1.50</price></line>
         <line sku="P-20" qty="1"><label>Ink</label><price>4.20</price></line></order>
id 2 : <order id="A2"><customer>Grace</customer>
         <line sku="P-30" qty="5"><label>Paper</label><price>3.00</price></line></order>

(Sur une seule ligne chacun dans le job ; coupés ici pour la lecture.) (On a single line each in the job; cut here for reading.)

Une ligne par élément lineOne row per line element

row1 (Main) row2 (Main) tFixedFlowInput_1 tExtractXMLField_1 tLogRow_1

Champ XML xml, Requête XPath boucle "/order/line". Mapping : XML field xml, Loop XPath query "/order/line". Mapping:

ColonneColumn Type Requête XPathXPath query
idInteger(vide)(empty)
order_idString"../@id"
customerString"../customer"
skuString"@sku"
qtyInteger"@qty"
labelString"label"
priceBigDecimal"price"
.--+--------+--------+----+---+-----+-----.
|                tLogRow_1                |
|=-+--------+--------+----+---+-----+----=|
|id|order_id|customer|sku |qty|label|price|
|=-+--------+--------+----+---+-----+----=|
|1 |A1      |Ada     |P-10|2  |Pen  |1.50 |
|1 |A1      |Ada     |P-20|1  |Ink  |4.20 |
|2 |A2      |Grace   |P-30|5  |Paper|3.00 |
'--+--------+--------+----+---+-----+-----'

tExtractXMLField_1_NB_LINE: 3

Deux lignes d'entrée, trois lignes de sortie. id, sans requête, est recopié de l'entrée ; ../ remonte à l'élément order. Two input rows, three output rows. id, without a query, is copied from the input; ../ goes up to the order element.

Nœuds et fonctionsNodes and functions

Premier document, colonnes String : sku ← "@sku" ; line_xml ← "." et label ← "label", avec Obtenir les nœuds ; nb_lines ← "count(../line)" ; total ← "sum(../line/price)". tLogRow en mode simple : First document, String columns: sku ← "@sku"; line_xml ← "." and label ← "label", with Get Nodes; nb_lines ← "count(../line)"; total ← "sum(../line/price)". tLogRow in basic mode:

P-10|<line sku="P-10" qty="2"><label>Pen</label><price>1.50</price></line>|<label>Pen</label>|2.0|5.7
P-20|<line sku="P-20" qty="1"><label>Ink</label><price>4.20</price></line>|<label>Ink</label>|2.0|5.7

Une fonction numérique XPath rend un nombre décimal : count() donne 2.0, ce qui ne passe pas dans une colonne Integer (voir les erreurs). An XPath number function returns a decimal number: count() gives 2.0, which does not fit in an Integer column (see the errors).

Valeurs absentes, vides, nullesMissing, empty, nil values

Document <order xmlns:xsi="…XMLSchema-instance"><line sku="P-10"><qty>3</qty><label></label><stock>7</stock></line><line><qty xsi:nil="true"/><label>Ink</label></line></order>. Colonnes sku, label, note (String), qty (Integer), stock (Integer, non nullable). Un tJavaRow affiche les valeurs entre crochets : Document <order xmlns:xsi="…XMLSchema-instance"><line sku="P-10"><qty>3</qty><label></label><stock>7</stock></line><line><qty xsi:nil="true"/><label>Ink</label></line></order>. Columns sku, label, note (String), qty (Integer), stock (Integer, not nullable). A tJavaRow prints the values in brackets:

sku=[P-10] qty=[3] label=[] note=[null] stock=[7]
sku=[null] qty=[null] label=[Ink] note=[null] stock=[0]

Nœud absent : null (ou la valeur par défaut de la colonne) ; élément vide : "" en String ; xsi:nil="true" : null. Une colonne non nullable reçoit la valeur Java par défaut de son type, ici 0. Missing node: null (or the default value of the column); empty element: "" as String; xsi:nil="true": null. A non-nullable column gets the Java default value of its type, here 0.

Lignes en erreur et lien RejectRows in error and Reject link

row1 (Main) row2 (Main) row3 (Reject) tFixedFlowInput_1 tExtractXMLField_1 tLogRow_1 tLogRow_2

Mapping du premier exemple. Quatre lignes : 1, le document A2 ; 2, un document dont qty vaut two ; 3, un XML mal formé (<order id="A4"><line sku="P-50"></order>) ; 4, null. Le tLogRow_2 du Reject est en mode simple ; il écrit au fil des lignes, le tLogRow_1 en tableau à la fin : Mapping of the first example. Four rows: 1, the A2 document; 2, a document whose qty is two; 3, a malformed XML (<order id="A4"><line sku="P-50"></order>); 4, null. The tLogRow_2 of the Reject is in basic mode; it prints as the rows come, the tLogRow_1 as a table at the end:

2|A3|Alan|P-40||||<order id="A3"><customer>Alan</customer><line sku="P-40" qty="two"><label>Glue</label><price>2.10</price></line></order>||For input string: "two" - Line: 1
3|||||||<order id="A4"><line sku="P-50"></order>||Error on line 1 of document  : Le type d'élément "line" doit se terminer par la balise de fin correspondante "</line>". - Line: 2
.--+--------+--------+----+---+-----+-----.
|                tLogRow_1                |
|=-+--------+--------+----+---+-----+----=|
|id|order_id|customer|sku |qty|label|price|
|=-+--------+--------+----+---+-----+----=|
|1 |A2      |Grace   |P-30|5  |Paper|3.00 |
'--+--------+--------+----+---+-----+-----'

tExtractXMLField_1_NB_LINE: 2

La ligne 4 (null) ne donne rien. Le message d'un XML mal formé vient de l'analyseur XML de Java, dans la langue du système (ici le français). Sans lien Reject, les deux messages sont écrits sur la sortie d'erreur et les lignes sont perdues : Row 4 (null) gives nothing. The message of a malformed XML comes from the XML parser of Java, in the language of the system (here French). Without a Reject link, both messages are written to the error output and the rows are lost:

For input string: "two"
Error on line 1 of document  : Le type d'élément "line" doit se terminer par la balise de fin correspondante "</line>".

Avec Arrêter en cas d'erreur, le job s'arrête sur la ligne 2 (code 1 ; nom du job remplacé par MyJob) : With Die on error, the job stops on row 2 (exit code 1; job name replaced with MyJob):

Exception in component tExtractXMLField_1 (MyJob)
java.lang.NumberFormatException: For input string: "two"
	at routines.system.ParserUtils.parseTo_int(ParserUtils.java:122)
	at routines.system.ParserUtils.parseTo_Integer(ParserUtils.java:137)
	…

Espaces de nomsNamespaces

Deux documents : <order xmlns="http://example.com/orders" id="A1"><line sku="P-10"><label>Pen</label></line>… (espace par défaut) et <o:order xmlns:o="http://example.com/orders" id="A2"><o:line sku="P-30"><o:label>Paper</o:label></o:line></o:order> (préfixe o). Colonnes id (recopiée), order_id ← "../@id", sku ← "@sku", label. Cinq sous-jobs ; chaque titre donne le document, la boucle et le réglage : Two documents: <order xmlns="http://example.com/orders" id="A1"><line sku="P-10"><label>Pen</label></line>… (default namespace) and <o:order xmlns:o="http://example.com/orders" id="A2"><o:line sku="P-30"><o:label>Paper</o:label></o:line></o:order> (o prefix). Columns id (copied), order_id ← "../@id", sku ← "@sku", label. Five subjobs; each title gives the document, the loop and the setting:

=== default namespace, no prefix
1|A1|P-10|Pen
1|A1|P-20|Ink
=== prefix o
2|A2|P-30|Paper
=== prefix o, no prefix in XPath
=== prefix o, IGNORE_NS
2|A2|P-30|Paper
=== default namespace, IGNORE_NS
1|A1|P-10|Pen
1|A1|P-20|Ink
  • default namespace : boucle "/order/line", label ← "label". Le composant ajoute lui-même un préfixe interne aux noms : les requêtes s'écrivent sans préfixe.default namespace: loop "/order/line", label ← "label". The component adds an internal prefix to the names itself: the queries are written without prefix.
  • prefix o : boucle "/o:order/o:line", label ← "o:label", les préfixes du document.prefix o: loop "/o:order/o:line", label ← "o:label", the prefixes of the document.
  • no prefix in XPath : la boucle "/order/line" ne trouve rien sur le document préfixé, sans erreur.no prefix in XPath: the "/order/line" loop finds nothing on the prefixed document, without an error.
  • IGNORE_NS : Ignorer les espaces de noms coché, requêtes sans préfixe : les deux documents sont lus.IGNORE_NS: Ignore the namespaces checked, queries without prefix: both documents are read.

Colonne Document en entréeDocument column as input

Colonne xml de type Document, valeur ParserUtils.parseTo_Document(…) du premier document ; id recopiée, sku ← "@sku" : xml column of type Document, value ParserUtils.parseTo_Document(…) of the first document; id copied, sku ← "@sku":

1|P-10
1|P-20

Même résultat qu'avec une chaîne. Le document produit par un tWriteXMLField se relit de la même façon. Same result as with a string. The document produced by a tWriteXMLField is read back the same way.

LimiteLimit

Trois lignes d'entrée : le premier document (2 éléments line), le second (1), le premier encore (2). Limite 2, colonnes id (recopiée) et sku : Three input rows: the first document (2 line elements), the second one (1), the first one again (2). Limit 2, columns id (copied) and sku:

1|P-10
1|P-20
tExtractXMLField_1_NB_LINE: 4

Deux lignes en tout, toutes du premier document : la limite vaut pour tout le flux. NB_LINE vaut 4, et non 2 (voir les pièges). Two rows in all, all from the first document: the limit applies to the whole flow. NB_LINE is 4, not 2 (see the pitfalls).

Erreurs et piègesErrors and pitfalls

Fonction XPath vers une colonne IntegerXPath function into an Integer column

Premier document, sku ← "@sku", nb (Integer) ← "count(../line)", lien Reject vers un tLogRow simple. Aucune ligne ne sort sur Main ; le Reject reçoit : First document, sku ← "@sku", nb (Integer) ← "count(../line)", Reject link to a basic tLogRow. No row leaves on Main; the Reject gets:

P-10||<order id="A1">…</order>||For input string: "2.0" - Line: 0
P-20||<order id="A1">…</order>||For input string: "2.0" - Line: 1

(Document abrégé.) Les fonctions numériques XPath rendent un nombre décimal, que la conversion en entier refuse. Convertissez dans la requête avec string(), ou prenez une colonne Double. Avec nb (Integer) ← "string(count(../line))" et total (Double) ← "sum(../line/price)" : (Document shortened.) The XPath number functions return a decimal number, which the conversion to an integer rejects. Convert in the query with string(), or take a Double column. With nb (Integer) ← "string(count(../line))" and total (Double) ← "sum(../line/price)":

P-10|2|5.7
P-20|2|5.7

Limite pour tout le flux, NB_LINE fausséeLimit for the whole flow, NB_LINE off

Le compteur de la Limite n'est pas remis à zéro pour chaque ligne d'entrée : avec plusieurs documents, les suivants ne donnent plus rien une fois la limite atteinte (voir l'exemple). Le même compteur sert à NB_LINE, augmenté avant le test de la limite : chaque document suivant y ajoute 1 sans donner de ligne (défaut du modèle tExtractXMLField_main.javajet). Pour limiter chaque document, filtrez plutôt dans la boucle. Mêmes trois lignes, Limite vide, boucle "/order/line[position() <= 1]", colonne info ← "concat(label, ' x ', @qty)" : The Limit counter is not reset for each input row: with several documents, the next ones give nothing once the limit is reached (see the example). The same counter is used for NB_LINE, increased before the limit test: each following document adds 1 to it without giving a row (defect of the tExtractXMLField_main.javajet template). To limit each document, filter in the loop instead. Same three rows, Limit empty, loop "/order/line[position() <= 1]", info column ← "concat(label, ' x ', @qty)":

1|P-10|Pen x 2
2|P-30|Paper x 5
3|P-10|Pen x 2

Préfixes oubliés : aucune ligneForgotten prefixes: no row

Sur un document à préfixes (o:order), une boucle sans préfixe ne trouve rien, et le composant ne le signale pas : il ne sort simplement aucune ligne (voir les exemples). Reprenez les préfixes du document, ou cochez Ignorer les espaces de noms. On a document with prefixes (o:order), a loop without prefix finds nothing, and the component does not report it: it simply sends out no row (see the examples). Use the prefixes of the document, or check Ignore the namespaces.

Une erreur arrête l'extraction de la ligneAn error stops the extraction of the row

Les colonnes sont extraites dans l'ordre du schéma : à la première conversion qui échoue, les colonnes suivantes ne sont pas remplies (label et price vides dans la ligne rejetée de l'exemple). Lisez en String les valeurs douteuses et convertissez-les ensuite, par exemple dans un tMap. The columns are extracted in the schema order: at the first conversion that fails, the next columns are not filled (label and price empty in the rejected row of the example). Read the doubtful values as String and convert them afterwards, for example in a tMap.

Conseils et limitesTips and limits

XPath 1.0XPath 1.0

Les requêtes sont évaluées par dom4j et Jaxen : XPath 1.0 complet, prédicats (line[@qty > 1]) et fonctions (count(), sum(), string(), concat()). Chaque document est chargé entièrement en mémoire, une ligne d'entrée à la fois. The queries are evaluated by dom4j and Jaxen: full XPath 1.0, predicates (line[@qty > 1]) and functions (count(), sum(), string(), concat()). Each document is fully loaded in memory, one input row at a time.

Garder les colonnes de l'entréeKeeping the input columns

Une colonne de sortie qui porte le nom d'une colonne d'entrée et dont la requête est vide est recopiée telle quelle : la clé de la ligne d'origine (id des exemples) suit chaque ligne extraite, et chaque ligne rejetée. An output column that has the name of an input column and whose query is empty is copied as it is: the key of the original row (id of the examples) follows each extracted row, and each rejected row.

Voir aussiSee also