ComposantsComponents › ESB › Route
Renvoie une erreur à la route qui a appelé le job. Comme le tRouteOutput, il écrit les colonnes de la ligne reçue dans le message de la route, comme corps, en-tête ou propriété ; mais il marque en plus le message en échec, avec une exception CamelException. Au retour du cTalendJob, la route quitte son chemin normal : c'est son traitement d'erreur (cOnException, cTry, ou le gestionnaire par défaut de Camel) qui prend la suite. Le job doit commencer par un tRouteInput.
Sends an error back to the route that called the job. Like the tRouteOutput, it writes the columns of the received row into the message of the route, as the body, a header or a property; but it also marks the message as failed, with a CamelException. When the cTalendJob returns, the route leaves its normal path: its error handling (cOnException, cTry, or the default handler of Camel) takes over. The job must start with a tRouteInput.
EntréeInput
Un lien Main, obligatoire : c'est l'arrivée d'une ligne qui déclenche l'erreur. One Main link, required: the arrival of a row is what raises the error.
SortieOutput
Aucune Il termine son flux. None It ends its flow.
DéclencheursTriggers
Aucun Ni en entrée ni en sortie : le composant ne déclare que le lien Main. None Neither incoming nor outgoing: the component only declares the Main link.
Le tMap a deux sorties, chacune avec son filtre : la ligne valide repart par le tRouteOutput, la ligne refusée par le tRouteFault, avec un motif et un code. Une seule des deux sorties reçoit la ligne. The tMap has two outputs, each with its filter: the valid row goes back through the tRouteOutput, the rejected row through the tRouteFault, with a reason and a code. Only one of the two outputs receives the row.
Un cOnException posé dans la route reçoit le message en échec : le corps et les en-têtes écrits par le tRouteFault y sont lisibles. Sans lui, Camel journalise l'erreur et abandonne le message.
A cOnException placed in the route receives the failed message: the body and the headers written by the tRouteFault can be read there. Without it, Camel logs the error and drops the message.
Les mêmes que ceux du tRouteOutput. 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. The same as those of the tRouteOutput. 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 de sortieOutput SchemaINPUT_SCHEMA | VideEmpty | ToujoursAlways | Les colonnes de la ligne reçue, reprises du lien entrant : le motif de l'erreur, son code, ce que la route doit savoir. The columns of the received row, taken from the incoming link: the reason of the error, its code, what the route must know. |
| CamelVALUES | Une ligne par colonneOne row per column | ToujoursAlways | Table calquée sur le schéma : une ligne par colonne, à compléter par les deux réglages ci-dessous. Table modelled on the schema: one row per column, to complete with the two settings below. |
| TypeVALUES › TYPE | En-têteHeader | ToujoursAlways |
Où va la valeur de la colonne : En-tête (Header) ou Corps (Body) du message d'erreur, Propriété (Property) de l'échange, ou Système (System) : propriété système de la machine Java.
Where the value of the column goes: Header or Body of the error message, Property of the exchange, or System: system property of the Java machine.
|
| NomNameVALUES › VALUE | VideEmpty | ToujoursAlways |
Le nom de l'en-tête, de la propriété ou de la propriété système : une expression Java, donc un texte entre guillemets ("errorCode"). Obligatoire pour ces trois types ; ignoré pour le type Corps, comme le rappelle la note sous la table : The "Name" with "Body" type will be ignored.
The name of the header, of the property or of the system property: a Java expression, hence a text in quotes ("errorCode"). Required for these three types; ignored for the Body type, as the note under the table recalls: The "Name" with "Body" type will be ignored.
|
À chaque ligne reçue, le tRouteFault prépare un message d'erreur (le message de sortie de l'échange, out), puis pose l'exception. Le message d'entrée, celui que la route avait envoyé, n'est pas modifié. For each received row, the tRouteFault prepares an error message (the output message of the exchange, out), then sets the exception. The input message, the one the route had sent, is not modified.
| ÉlémentItem | ContenuContent | Lu dans la route parRead in the route with |
|---|---|---|
| L'exceptionThe exception | Une org.apache.camel.CamelException. Son message est le corps du message d'entrée, converti en texte : ce que la route avait envoyé au job, pas la colonne de type Corps.An org.apache.camel.CamelException. Its message is the body of the input message, converted to text: what the route had sent to the job, not the column with the Body type. |
${exception.message}, exchange.getProperty(Exchange.EXCEPTION_CAUGHT, Exception.class) |
| Le corpsThe body | La colonne de type Corps ; sans elle, le corps d'entrée, recopié.The column with the Body type; without one, the input body, copied. | exchange.getMessage().getBody() |
| Les en-têtesThe headers | Ceux du message d'entrée, recopiés, plus les colonnes de type En-tête.Those of the input message, copied, plus the columns with the Header type. | exchange.getMessage().getHeader("errorCode") |
| Propriétés, SystèmeProperties, System | Comme pour le tRouteOutput : propriété de l'échange, propriété système de la machine Java.As for the tRouteOutput: exchange property, system property of the Java machine. | exchange.getProperty("…"), System.getProperty("…") |
Le composant n'a ni adresse ni option de sécurité : il agit en mémoire sur le message de la route, de la même façon partout. Ce qui change est ce que la route fait de l'erreur : dans le Studio ou Talaxie, le gestionnaire par défaut de Camel l'écrit dans la console ; déployée, elle l'écrit dans le journal du conteneur. Si la route publie un service (cSOAP, cREST), c'est son traitement d'erreur qui décide de la réponse faite à l'appelant.
The component has no address and no security option: it acts in memory on the message of the route, the same way everywhere. What changes is what the route does with the error: in the Studio or Talaxie, the default handler of Camel writes it to the console; once deployed, it writes it to the log of the container. If the route publishes a service (cSOAP, cREST), its error handling decides the reply made to the caller.
Sorties copiées depuis l'exécution locale d'une route d'essai : cTimer → cSetBody → cTalendJob → cProcessor. La route envoie le corps A-1001 ; le cProcessor final écrirait route: after the job. Les noms du job et de la route sont remplacés par MyJob et MyRoute, les piles d'appels sont abrégées (…).
Outputs copied from the local run of a test route: cTimer → cSetBody → cTalendJob → cProcessor. The route sends the body A-1001; the final cProcessor would write route: after the job. The names of the job and of the route are replaced with MyJob and MyRoute, the stack traces are shortened (…).
Le jobThe job
La routeThe route
Le tRouteInput lit body (String). Le tJavaRow prépare l'erreur ; dans le tRouteFault, reason a le type Corps et code le type En-tête, de nom "errorCode". Code du tJavaRow :
The tRouteInput reads body (String). The tJavaRow prepares the error; in the tRouteFault, reason has the Body type and code the Header type, with the name "errorCode". Code of the tJavaRow:
System.out.println("job: body = " + input_row.body);
output_row.reason = "Unknown order " + input_row.body;
output_row.code = "E42";
Le cOnException attrape java.lang.Exception, option Gérer les exceptions cochée. Code du cProcessor qui le suit :
The cOnException catches java.lang.Exception, with the Handle the exceptions option checked. Code of the cProcessor that follows it:
Exception error = exchange.getProperty(org.apache.camel.Exchange.EXCEPTION_CAUGHT, Exception.class);
System.out.println("handler: exception = " + error.getClass().getName());
System.out.println("handler: message = " + error.getMessage());
System.out.println("handler: body = " + exchange.getMessage().getBody(String.class));
System.out.println("handler: errorCode = " + exchange.getMessage().getHeader("errorCode"));
job: body = A-1001 handler: exception = org.apache.camel.CamelException handler: message = A-1001 handler: body = Unknown order A-1001 handler: errorCode = E42
Le motif et le code sont dans le message d'erreur ; le message de l'exception, lui, est le corps d'origine A-1001. Le cProcessor placé après le cTalendJob n'a rien écrit.
The reason and the code are in the error message; the message of the exception, however, is the original body A-1001. The cProcessor placed after the cTalendJob wrote nothing.
Le même job ; la route n'a plus de cOnException. The same job; the route no longer has a cOnException.
job: body = A-1001 [ERROR] 18:43:44 org.apache.camel.processor.errorhandler.DefaultErrorHandler- Failed delivery for (MessageId: F67AE8B2F2518A0-0000000000000000 on ExchangeId: F67AE8B2F2518A0-0000000000000000). Exhausted after delivery attempt: 1 caught: org.apache.camel.CamelException: A-1001 Message History … Stacktrace --------------------------------------------------------------------------------------------------------------------------------------- org.apache.camel.CamelException: A-1001 at demo.myjob_0_1.MyJob.tRouteInput_1_LoopProcess(MyJob.java:1428) ~[classes/:?] at demo.myjob_0_1.MyJob.runJobInTOS(MyJob.java:2029) ~[classes/:?] at demo.myjob_0_1.MyJob$1.runSingleUseJob(MyJob.java:413) ~[classes/:?] at org.talend.camel.TalendProducer.invokeTalendJob(TalendProducer.java:203) ~[camel-talendjob-8.8.8-SNAPSHOT.jar:?] … [WARN ] 18:43:44 org.apache.camel.component.timer.TimerConsumer- Error processing exchange. Exchange[F67AE8B2F2518A0-0000000000000000]. Caused by: [org.apache.camel.CamelException - A-1001] …
Le gestionnaire d'erreur par défaut de Camel journalise l'échec avec l'historique du message, et le message est abandonné. Ni le motif ni le code n'apparaissent : seul le message de l'exception, le corps d'origine, est écrit. The default error handler of Camel logs the failure with the history of the message, and the message is dropped. Neither the reason nor the code shows up: only the message of the exception, the original body, is written.
Le job du premier exemple, suivi d'un tJava qui écrit une ligne. La route, avec son cOnException, envoie deux messages ; la case Invocation rapide de Job du cTalendJob est cochée. The job of the first example, followed by a tJava that writes one line. The route, with its cOnException, sends two messages; the Fast Job Invocation box of the cTalendJob is checked.
job: body = A-1001 job: tJava_1, after the fault handler: exception = org.apache.camel.CamelException handler: message = A-1001 handler: body = Unknown order A-1001 handler: errorCode = E42 job: body = A-1001 job: tJava_1, after the fault handler: exception = org.apache.camel.CamelException handler: message = A-1001 handler: body = Unknown order A-1001 handler: errorCode = E42
Le sous-job suivant s'exécute malgré l'erreur, avant le retour à la route ; et le job, resté prêt, traite le message suivant. The following subjob runs despite the error, before the return to the route; and the job, still ready, handles the next message.
On s'attend à retrouver la colonne de type Corps dans le message de l'exception. Ce n'est pas le cas : le composant y met le corps que la route avait envoyé (A-1001 dans les exemples, alors que le motif était Unknown order A-1001). Un journal qui n'écrit que ${exception.message}, ou le gestionnaire par défaut de Camel, ne montre donc jamais le motif. Dans le traitement d'erreur de la route, lisez le corps et les en-têtes du message (exchange.getMessage()), pas le message de l'exception. Si le corps d'entrée est volumineux ou confidentiel, sachez qu'il se retrouve en entier dans les journaux par ce chemin.
One expects to find the column with the Body type in the message of the exception. It is not there: the component puts in it the body the route had sent (A-1001 in the examples, while the reason was Unknown order A-1001). A log that only writes ${exception.message}, or the default handler of Camel, therefore never shows the reason. In the error handling of the route, read the body and the headers of the message (exchange.getMessage()), not the message of the exception. If the input body is large or confidential, be aware that it ends up whole in the logs this way.
Le tRouteFault n'arrête rien : les lignes suivantes du flux et les sous-jobs suivants sont traités. Si une écriture en base suit par On Subjob Ok, elle a lieu malgré l'erreur. Seule une exception du job arrête son flux, et la route ne reçoit alors qu'un message général (voir le tRouteInput). The tRouteFault stops nothing: the following rows of the flow and the following subjobs are processed. If a database write follows through On Subjob Ok, it happens despite the error. Only an exception of the job stops its flow, and the route then only receives a general message (see the tRouteInput).
Les deux composants écrivent dans le même échange. Si une même ligne atteint les deux, l'exception est posée de toute façon et la route part en erreur. Filtrez en amont (deux sorties de tMap, un tFilterRow et son rejet) pour qu'une ligne n'aille que d'un côté. Both components write into the same exchange. If the same row reaches both, the exception is set anyway and the route goes into error. Filter upstream (two tMap outputs, a tFilterRow and its reject) so that a row goes only one way.
Les deux pièges du tRouteOutput valent ici, pour la même raison : une colonne de type En-tête, Propriété ou Système sans Nom empêche le job de compiler, et un job qui a un tRouteFault sans tRouteInput ne peut pas être généré. The two pitfalls of the tRouteOutput apply here, for the same reason: a column with the Header, Property or System type without a Name prevents the job from compiling, and a job that has a tRouteFault without a tRouteInput cannot be generated.
Sans route, le tRouteInput ne produit aucune ligne : le tRouteFault ne reçoit rien et ne signale rien. Une erreur ne se constate qu'en exécutant la route. Without a route, the tRouteInput produces no row: the tRouteFault receives nothing and reports nothing. An error can only be observed by running the route.
Renvoyez toujours un en-tête court et stable ("errorCode") à côté du motif lisible : la route peut choisir son traitement sur le code (${header.errorCode} == 'E42' dans un cMessageRouter placé après le cOnException), et garder le motif pour le journal ou la réponse.
Always send back a short and stable header ("errorCode") next to the readable reason: the route can pick its handling from the code (${header.errorCode} == 'E42' in a cMessageRouter placed after the cOnException), and keep the reason for the log or the reply.
Gardez le tRouteFault pour les erreurs que le job sait nommer : commande inconnue, donnée refusée. Une panne (base injoignable, fichier absent) lève déjà une exception dans le job, que la route reçoit sans autre réglage ; un cOnException de la route peut distinguer les deux par la classe de l'exception, CamelException pour le tRouteFault.
Keep the tRouteFault for the errors the job can name: unknown order, rejected data. A failure (unreachable database, missing file) already throws an exception in the job, which the route receives with no other setting; a cOnException of the route can tell the two apart by the class of the exception, CamelException for the tRouteFault.
tRouteInput · lire le message de la route, au début du jobread the message of the route, at the start of the jobtRouteOutput · renvoyer une réponse normale à la routesend a normal reply back to the routetESBProviderFault · l'erreur d'un job qui publie un service SOAPthe fault of a job that publishes a SOAP servicetFilterRow · séparer les lignes valides des lignes en erreursplit the valid rows from the rows in errortWarn · signaler sans arrêter, dans le journal du jobreport without stopping, in the log of the jobtLogCatcher · capter les exceptions du jobcatch the exceptions of the job