ComposantsComponents

ComposantsComponents › ESB › Route

tRouteFault

tRouteFault

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.

UtilisationUsage

Réponse ou erreur, selon la donnéeReply or error, depending on the data

row1 (Main) ok (Main) rejected (Main) tRouteInput_1 tMap_1 tRouteOutput_1 tRouteFault_1

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.

Dans la route : attraper l'erreurIn the route: catching the error

route1 route2 route3 cMessagingEndpoint_1 cTalendJob_1 cLog_1 cOnException_1 cProcessor_1

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.

  1. Dans un job qui a un tRouteInput, déposez le tRouteFault depuis la famille ESB › Route de la palette. In a job that has a tRouteInput, drop the tRouteFault from the ESB › Route family of the palette.
  2. Reliez-lui la sortie qui porte les lignes en erreur (un rejet, une sortie filtrée de tMap) : son schéma prend celui du lien. Connect to it the output that carries the rows in error (a reject, a filtered tMap output): its schema takes that of the link.
  3. Dans la table Camel, donnez à chaque colonne son Type et, sauf pour le corps, son Nom entre guillemets. In the Camel table, give each column its Type and, except for the body, its Name in quotes.
  4. Dans la route, prévoyez le traitement de l'erreur, puis exécutez la route. In the route, plan the handling of the error, then run the route.

Paramètres simplesBasic settings

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.

Ce que reçoit la routeWhat the route receives

À 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 job, lui, n'échoue pasThe job itself does not fail

  • Le tRouteFault ne lève rien dans le job : il note l'erreur sur le message et le flux continue. Les sous-jobs suivants (On Subjob Ok) s'exécutent, et le job se termine normalement.The tRouteFault throws nothing in the job: it records the error on the message and the flow goes on. The following subjobs (On Subjob Ok) run, and the job ends normally.
  • C'est au retour dans la route que Camel voit l'exception : les composants placés après le cTalendJob ne sont pas exécutés.Camel sees the exception on the return to the route: the components placed after the cTalendJob do not run.
  • Aucun tLogCatcher du job n'est prévenu : ce n'est ni un tDie ni une exception Java du job.No tLogCatcher of the job is notified: it is neither a tDie nor a Java exception of the job.

Studio, Talaxie et Talend RuntimeStudio, Talaxie and Talend Runtime

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.

ExemplesExamples

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 (…).

Une erreur attrapée par un cOnExceptionAn error caught by a cOnException

Le jobThe job

row1 (Main) row2 (Main) tRouteInput_1 tJavaRow_1 tRouteFault_1

La routeThe route

route1 route2 route3 route4 cTimer_1 cSetBody_1 cTalendJob_1 cProcessor_1 cOnException_1 cProcessor_2

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.

La même erreur, sans traitement dans la routeThe same error, with no handling in the route

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.

La suite du job après le tRouteFaultThe rest of the job after the tRouteFault

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

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.

PiègesPitfalls

Le message de l'exception n'est pas votre motifThe message of the exception is not your reason

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 job continueThe job goes on

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).

tRouteOutput et tRouteFault sur la même lignetRouteOutput and tRouteFault on the same row

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.

Un nom vide, un job sans tRouteInputAn empty name, a job without a tRouteInput

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.

Le job lancé seulThe job started alone

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.

ConseilsTips

Un code en en-tête, un motif en corpsA code as a header, a reason as the body

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.

Erreur métier ou panneBusiness error or failure

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.

Voir aussiSee also