ComposantsComponents › XML
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
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.
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.
"/order/line".
Choose the column in XML field and write the Loop XPath query, absolute: "/order/line".
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è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). |
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.
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.)
lineOne row per line element
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 |
|---|---|---|
| id | Integer | (vide)(empty) |
| order_id | String | "../@id" |
| customer | String | "../customer" |
| sku | String | "@sku" |
| qty | Integer | "@qty" |
| label | String | "label" |
| price | BigDecimal | "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.
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).
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.
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) …
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
"/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."/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."/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.
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.
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).
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
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
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.
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.
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.
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.
tFileInputXML · la même lecture, depuis un fichierthe same reading, from a filetWriteXMLField · construire une colonne XMLbuild an XML columntXMLMap · lire et transformer des documents dans un éditeur de correspondancesread and transform documents in a mapping editortExtractRegexFields · extraire des champs par expression régulièreextract fields with a regular expressiontRESTClient · recevoir une réponse XML à découperreceive an XML response to splittXSDValidator · valider un document avant de le lirevalidate a document before reading it