ComposantsComponents

ComposantsComponents › ESB › Route

tRouteInput

tRouteInput

ESB › Route

Point d'entrée d'un job appelé par une route. Dans la route, le composant cTalendJob désigne le job ; à chaque message, le tRouteInput lit ce message et en fait une ligne : chaque colonne de son schéma reçoit le résultat d'une expression Camel (langage Simple) évaluée sur le message, son corps, ses en-têtes, ses propriétés. La réponse repart par un tRouteOutput, une erreur par un tRouteFault. Entry point of a job called by a route. In the route, the cTalendJob component names the job; for each message, the tRouteInput reads that message and turns it into one row: each column of its schema receives the result of a Camel expression (Simple language) evaluated on the message, its body, its headers, its properties. The reply goes back through a tRouteOutput, an error through a tRouteFault.

EntréeInput

Aucune ligne Il commence son sous-job. Déclencheurs acceptés : On Subjob Ok On Subjob Error On Component Ok Run if No row It starts its subjob. Accepted triggers: On Subjob Ok On Subjob Error On Component Ok Run if

SortieOutput

Un seul lien Main : une ligne par message de la route. A single Main link: one row per message of the route.

Déclencheurs en sortieOutput triggers

On Subjob Ok On Subjob Error On Component Ok Run if

UtilisationUsage

Un job qui répond à la routeA job that replies to the route

La routeThe route

route1 route2 cMessagingEndpoint_1 cTalendJob_1 cLog_1

Le jobThe job

row1 (Main) row2 (Main) tRouteInput_1 tMap_1 tRouteOutput_1

La route reçoit un message et le confie au job. Le job lit le corps et les en-têtes, calcule, et le tRouteOutput écrit le résultat dans le message : la route continue avec lui. The route receives a message and hands it to the job. The job reads the body and the headers, computes, and the tRouteOutput writes the result into the message: the route goes on with it.

Un job qui traite sans répondreA job that processes without replying

Le jobThe job

row1 (Main) row2 (Main) tRouteInput_1 tExtractXMLField_1 tDBOutput_1

Le job enregistre ce qu'il reçoit. Sans tRouteOutput ni tRouteFault, il ne touche pas au message : la route continue avec le message tel qu'elle l'a envoyé. The job stores what it receives. Without a tRouteOutput or a tRouteFault, it does not touch the message: the route goes on with the message as it sent it.

  1. Dans un job, déposez le tRouteInput depuis la famille ESB › Route de la palette. Un seul par job. In a job, drop the tRouteInput from the ESB › Route family of the palette. Only one per job.
  2. Ouvrez son schéma : il a une colonne body de type Document (XML). Changez son type si le corps n'est pas du XML, ajoutez une colonne par valeur à lire. Open its schema: it has one body column of type Document (XML). Change its type if the body is not XML, add one column per value to read.
  3. Dans la table Camel, donnez à chaque colonne son expression : "${in.body}", "${header.customer}"… (voir Les expressions). In the Camel table, give each column its expression: "${in.body}", "${header.customer}"… (see The expressions).
  4. Reliez sa sortie Main à la suite du job, et terminez par un tRouteOutput si le job répond. Connect its Main output to the rest of the job, and end with a tRouteOutput if the job replies.
  5. Dans la route, posez un cTalendJob, choisissez ce job, puis exécutez la route, pas le job : lancé seul, le job n'a pas de message à lire (voir Pièges). In the route, add a cTalendJob, select this job, then run the route, not the job: started alone, the job has no message to read (see Pitfalls).

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. Le composant n'a ni paramètres avancés ni variables globales. Labels are those of the Component tab; the technical name, in grey, is the parameter name in the job file. The component has no advanced settings and no global variables.

ParamètreSetting DéfautDefault VisibleShown Description
Schéma d'entréeInput SchemaINPUT_SCHEMA Une colonne body, DocumentOne body column, Document ToujoursAlways Les colonnes de la ligne que le job reçoit pour chaque message. Le schéma est libre : renommez, retypez, ajoutez des colonnes. Le type de la colonne décide de la conversion de la valeur lue. The columns of the row the job receives for each message. The schema is free: rename, retype, add columns. The type of the column decides how the value read is converted.
CamelVALUES Une ligne par colonne, "${in.body}"One row per column, "${in.body}" ToujoursAlways Table calquée sur le schéma : une ligne par colonne. La colonne Expression simple (VALUE) est une chaîne Java, entre guillemets, écrite dans le langage Simple de Camel. Chaque nouvelle colonne du schéma arrive avec "${in.body}" : pensez à la changer. Cellule vidée : la colonne reçoit sa valeur par défaut du schéma (null sans valeur par défaut). Table modelled on the schema: one row per column. The Simple Expression column (VALUE) is a Java string, in quotes, written in the Simple language of Camel. Each new schema column comes with "${in.body}": remember to change it. Emptied cell: the column receives its default value from the schema (null without a default value).

Les expressionsThe expressions

Chaque expression est évaluée par Camel sur le message en cours (l'exchange), puis convertie par Camel dans le type Java de la colonne. Les valeurs de la dernière colonne ont été relevées à l'exécution, pour un message de corps A-1001 portant les en-têtes customer = Alice et lines = 3 (texte). Each expression is evaluated by Camel on the current message (the exchange), then converted by Camel to the Java type of the column. The values of the last column were read from runs, for a message with body A-1001 carrying the headers customer = Alice and lines = 3 (text).

Expression Type de la colonneColumn type Ce qui est luWhat is read Valeur reçueValue received
"${in.body}" String Le corps du message.The body of the message. A-1001
"${in.body}" Document Le corps, lu comme du texte puis analysé comme un document XML.The body, read as text then parsed as an XML document. Une erreur ici : A-1001 n'est pas du XML (voir Pièges).An error here: A-1001 is not XML (see Pitfalls).
"${header.customer}" String L'en-tête customer.The customer header. Alice
"${header.lines}" Integer L'en-tête lines, converti en entier.The lines header, converted to an integer. 3
"${header.missing}" String, Integer Un en-tête que le message n'a pas.A header the message does not have. null
"${routeId}" String L'identifiant de la route : son nom, puis celui de son premier composant.The identifier of the route: its name, then the name of its first component. MyRoute_cTimer_1
"Order ${in.body} of ${header.customer}" String Du texte et plusieurs expressions. Un en-tête absent y devient du vide, pas null.Text and several expressions. A missing header becomes empty there, not null. Order A-1001 of Alice

Comment la route lance le jobHow the route starts the job

  • Par défaut, le cTalendJob exécute le job entier pour chaque message : tous ses sous-jobs, du premier au dernier, comme un lancement ordinaire.By default, the cTalendJob runs the whole job for each message: all its subjobs, from the first to the last, like an ordinary start.
  • Avec Invocation rapide de Job (paramètres avancés du cTalendJob), le job démarre une seule fois et s'arrête sur le tRouteInput, en attente. Chaque message n'exécute alors que le sous-job du tRouteInput et ceux qui le suivent par un déclencheur ; ce qui précède le tRouteInput n'est exécuté qu'une fois.With Fast Job Invocation (advanced settings of the cTalendJob), the job starts only once and stops on the tRouteInput, waiting. Each message then runs only the subjob of the tRouteInput and those that follow it through a trigger; what comes before the tRouteInput runs only once.
  • Dans les deux cas, le job tourne dans la machine Java de la route, et la route attend sa fin avant de continuer.In both cases, the job runs in the Java machine of the route, and the route waits for its end before going on.

Studio, Talaxie et Talend RuntimeStudio, Talaxie and Talend Runtime

Le tRouteInput n'ouvre aucun point d'accès : pas d'adresse, pas de port, pas d'option de sécurité, rien à régler d'un environnement à l'autre. La route désigne le job par sa classe Java (talend://…) et l'appelle en mémoire. À l'exécution de la route dans le Studio ou dans Talaxie, le job est généré et compilé avec elle. Le contexte du job et ses variables se choisissent dans le cTalendJob (contexte, table Paramètres de contexte), pas ici. The tRouteInput opens no endpoint: no address, no port, no security option, nothing to set from one environment to another. The route names the job by its Java class (talend://…) and calls it in memory. When the route runs in the Studio or in Talaxie, the job is generated and compiled with it. The context of the job and its variables are chosen in the cTalendJob (context, Context Param table), not here.

ExemplesExamples

Sorties copiées depuis l'exécution locale d'une route d'essai qui appelle le job : un cTimer émet le message, un cSetBody et un cSetHeader le remplissent, le cTalendJob appelle le job, puis un cProcessor affiche ce que la route a reçu en retour (lignes route:). Les lignes job: sont écrites par un tJavaRow du job. Outputs copied from the local run of a test route that calls the job: a cTimer emits the message, a cSetBody and a cSetHeader fill it, the cTalendJob calls the job, then a cProcessor prints what the route got back (route: lines). The job: lines are written by a tJavaRow of the job.

Le corps et un en-têteThe body and a header

La routeThe route

route1 route2 route3 route4 cTimer_1 cSetBody_1 cSetHeader_1 cTalendJob_1 cProcessor_1

Le jobThe job

row1 (Main) row2 (Main) tRouteInput_1 tJavaRow_1 tRouteOutput_1

La route envoie le corps A-1001 et l'en-tête customer = Alice. Schéma du tRouteInput : body (String, "${in.body}") et customer (String, "${header.customer}"). Code du tJavaRow : The route sends the body A-1001 and the header customer = Alice. Schema of the tRouteInput: body (String, "${in.body}") and customer (String, "${header.customer}"). Code of the tJavaRow:

System.out.println("job: body = " + input_row.body + ", customer = " + input_row.customer);
output_row.reply = "Order " + input_row.body + " accepted for " + input_row.customer;
output_row.status = "ACCEPTED";
job: body = A-1001, customer = Alice
route: body = Order A-1001 accepted for Alice
route: status = ACCEPTED

Le tRouteOutput renvoie reply comme corps et status comme en-tête : après le cTalendJob, la route a le nouveau corps et l'en-tête status. The tRouteOutput sends reply back as the body and status as a header: after the cTalendJob, the route has the new body and the status header.

Le schéma par défaut : un corps XMLThe default schema: an XML body

row1 (Main) row2 (Main) tRouteInput_1 tJavaRow_1 tRouteOutput_1

Le tRouteInput garde son schéma d'origine, body de type Document. La route envoie le corps <order><id>A-1001</id></order>. Le tJavaRow lit un élément, en ajoute un, et passe le document au tRouteOutput (colonne body, Document, type Corps) : The tRouteInput keeps its original schema, body of type Document. The route sends the body <order><id>A-1001</id></order>. The tJavaRow reads an element, adds one, and passes the document to the tRouteOutput (body column, Document, Body type):

System.out.println("job: id = " + input_row.body.getDocument().getRootElement().elementText("id"));
input_row.body.getDocument().getRootElement().addElement("status").setText("checked");
output_row.body = input_row.body;
job: id = A-1001
route: class = com.sun.org.apache.xerces.internal.dom.DeferredDocumentImpl
route: body = <order><id>A-1001</id><status>checked</status></order>

Dans le job, la colonne est un Document de Talaxie (dom4j), utilisable par un tXMLMap ou un tExtractXMLField. Au retour, la route reçoit un document DOM (org.w3c.dom.Document) : la deuxième ligne donne sa classe. In the job, the column is a Talaxie Document (dom4j), usable by a tXMLMap or a tExtractXMLField. On the way back, the route receives a DOM document (org.w3c.dom.Document): the second line gives its class.

Trois messages, appel par défautThree messages, default call

OnSubjobOk row1 (Main) row2 (Main) tJava_1 tRouteInput_1 tJavaRow_1 tRouteOutput_1

Le job du premier exemple, précédé d'un tJava qui écrit une ligne. Le cTimer émet trois messages. The job of the first example, preceded by a tJava that writes one line. The cTimer emits three messages.

job: tJava_1, start of the job
job: body = A-1001, customer = Alice
route: body = Order A-1001 accepted for Alice
route: status = ACCEPTED
job: tJava_1, start of the job
job: body = A-1001, customer = Alice
route: body = Order A-1001 accepted for Alice
route: status = ACCEPTED
job: tJava_1, start of the job
job: body = A-1001, customer = Alice
route: body = Order A-1001 accepted for Alice
route: status = ACCEPTED

Le job entier est exécuté à chaque message : le tJava aussi. The whole job runs for each message: the tJava too.

Les mêmes, en invocation rapideThe same, with Fast Job Invocation

Même route et même job ; seule la case Invocation rapide de Job du cTalendJob est cochée. Same route and same job; only the Fast Job Invocation box of the cTalendJob is checked.

job: tJava_1, start of the job
job: body = A-1001, customer = Alice
route: body = Order A-1001 accepted for Alice
route: status = ACCEPTED
job: body = A-1001, customer = Alice
route: body = Order A-1001 accepted for Alice
route: status = ACCEPTED
job: body = A-1001, customer = Alice
route: body = Order A-1001 accepted for Alice
route: status = ACCEPTED

Le tJava n'est exécuté qu'une fois, au démarrage du job ; chaque message ne relance que le sous-job du tRouteInput. C'est la place d'une ouverture de connexion ou d'un chargement de référentiel. The tJava runs only once, when the job starts; each message only reruns the subjob of the tRouteInput. This is the place for opening a connection or loading reference data.

Un en-tête absentA missing header

La route n'envoie que le corps A-1001, sans en-tête. Colonnes du tRouteInput : customer (String, "${header.customer}"), lines (Integer, "${header.lines}") et label (String, "Order ${in.body} of ${header.customer}"). Le job les affiche et renvoie le corps tel quel. The route only sends the body A-1001, without a header. Columns of the tRouteInput: customer (String, "${header.customer}"), lines (Integer, "${header.lines}") and label (String, "Order ${in.body} of ${header.customer}"). The job prints them and sends the body back unchanged.

job: customer = null, lines = null, label = Order A-1001 of
route: body = A-1001

Pas d'erreur : une expression seule donne null, la même expression au milieu d'un texte donne du vide. No error: an expression alone gives null, the same expression in the middle of a text gives an empty string.

PiègesPitfalls

Le job lancé seulThe job started alone

Le job du premier exemple, exécuté directement, sans route. Sortie d'erreur : The job of the first example, run directly, without a route. Error output:

ERROR: No input for tRouteInput_1, You may need to start it Via a Route instead of running it directly!
ERROR: No input for tRouteInput_1, You may need to start it Via a Route instead of running it directly!

Une ligne par colonne qui a une expression (deux ici). Aucune ligne ne sort du tRouteInput, la suite du flux n'est pas exécutée, et le job se termine pourtant avec le code 0. Pour essayer le job, exécutez une route qui l'appelle : un cTimer à une répétition suivi d'un cSetBody suffit. One line per column that has an expression (two here). No row leaves the tRouteInput, the rest of the flow does not run, and yet the job ends with code 0. To try the job, run a route that calls it: a cTimer with one repetition followed by a cSetBody is enough.

Schéma par défaut et corps qui n'est pas du XMLDefault schema and a body that is not XML

Le tRouteInput garde sa colonne body de type Document, et la route envoie le texte A-1001. Sortie de la route (noms remplacés par MyJob et MyRoute, piles d'appels abrégées ; le message de l'analyseur XML est dans la langue du poste) : The tRouteInput keeps its body column of type Document, and the route sends the text A-1001. Output of the route (names replaced with MyJob and MyRoute, stack traces shortened; the message of the XML parser is in the language of the machine):

Exception in component tRouteInput_1_In (MyJob)
org.dom4j.DocumentException: Error on line 1 of document  : Contenu non autorisé dans le prologue.
	at org.dom4j.io.SAXReader.read(SAXReader.java:511)
	at org.dom4j.io.SAXReader.read(SAXReader.java:408)
	at routines.system.ParserUtils.parseTo_Document(ParserUtils.java:280)
	…
[ERROR] 18:44:07 org.apache.camel.processor.errorhandler.DefaultErrorHandler- Failed delivery for (MessageId: D49FD50E2917467-0000000000000000 on ExchangeId: D49FD50E2917467-0000000000000000). Exhausted after delivery attempt: 1 caught: java.lang.RuntimeException: Job execution failure - details see stderr.
	…
[WARN ] 18:44:07 org.apache.camel.component.timer.TimerConsumer- Error processing exchange. Exchange[D49FD50E2917467-0000000000000000]. Caused by: [java.lang.RuntimeException - Job execution failure - details see stderr. ]

Le job échoue dès la lecture, et la route reçoit une exception. Pour un corps en texte, en JSON ou en CSV, passez la colonne en String. The job fails as soon as it reads, and the route receives an exception. For a text, JSON or CSV body, set the column to String.

Une exception du job, vue de la routeAn exception of the job, seen from the route

Un tJavaRow du job lève IllegalStateException: Order A-1001 is locked. Appel par défaut : la route reçoit java.lang.RuntimeException, message Job execution failure - details see stderr. , sans cause ; le détail n'est que sur la sortie d'erreur. Avec Invocation rapide de Job : la route reçoit une RuntimeException dont la cause est l'exception d'origine, et la pile d'appels est écrite sur la sortie standard. Pour une erreur que la route doit comprendre, utilisez un tRouteFault. A tJavaRow of the job throws IllegalStateException: Order A-1001 is locked. Default call: the route receives java.lang.RuntimeException, message Job execution failure - details see stderr. , without a cause; the detail is only on the error output. With Fast Job Invocation: the route receives a RuntimeException whose cause is the original exception, and the stack trace is written to the standard output. For an error the route must understand, use a tRouteFault.

Les valeurs nullesNull values

Un en-tête ou une propriété absente arrive à null, sans erreur ni avertissement : dans le job, input_row.lines * 10 lève alors une NullPointerException. Testez la valeur avant de vous en servir, ou faites poser l'en-tête par la route (cSetHeader) avant le cTalendJob. A missing header or property arrives as null, with no error and no warning: in the job, input_row.lines * 10 then throws a NullPointerException. Test the value before using it, or have the route set the header (cSetHeader) before the cTalendJob.

Un seul tRouteInput par jobOnly one tRouteInput per job

Le code du job est écrit pour le premier tRouteInput trouvé : c'est son sous-job que la route exécute, ce sont ses colonnes et ses expressions qui sont lues. Un second tRouteInput n'a pas de sens. De même, un seul lien Main en sort. The code of the job is written for the first tRouteInput found: its subjob is the one the route runs, its columns and expressions are the ones read. A second tRouteInput makes no sense. Likewise, a single Main link leaves it.

Pas de lien On Component ErrorNo On Component Error link

Le composant ne propose pas ce déclencheur. Pour réagir à une erreur de lecture dans le job, utilisez On Subjob Error ; pour la traiter dans la route, un cOnException ou un cTry. The component does not offer this trigger. To react to a read error in the job, use On Subjob Error; to handle it in the route, a cOnException or a cTry.

ConseilsTips

Une colonne par donnée utileOne column per useful value

Plutôt que de tout mettre dans le corps, laissez la route poser des en-têtes (cSetHeader) et lisez-les chacun dans sa colonne, au bon type : le job reste lisible et le tMap qui suit n'a rien à découper. Rather than putting everything in the body, let the route set headers (cSetHeader) and read each one in its own column, with the right type: the job stays readable and the tMap that follows has nothing to split.

Préparer avant, traiter ensuitePrepare first, process next

Pour une route très sollicitée, cochez Invocation rapide de Job dans le cTalendJob et placez avant le tRouteInput, relié par On Subjob Ok, ce qui ne doit se faire qu'une fois. Sans cette case, tout le job, connexions comprises, est refait à chaque message. For a busy route, check Fast Job Invocation in the cTalendJob and put before the tRouteInput, linked by On Subjob Ok, what must be done only once. Without that box, the whole job, connections included, is redone for each message.

Voir aussiSee also