ComposantsComponents

ComposantsComponents › ESB › Web Services

tESBProviderFault

tESBProviderFault

ESB › Web Services

Répond une erreur SOAP à la place de la réponse, dans un job qui sert une opération de service web par un tESBProviderRequest. C'est l'erreur métier, prévue : un client inconnu, une commande déjà validée. L'appelant reçoit un message soap:Fault dont le texte est le Titre Fault du composant et dont le détail est le document XML de la colonne payload. Le job, lui, continue d'écouter. Answers a SOAP fault instead of the response, in a job that serves a web service operation through a tESBProviderRequest. It is the business error, the expected one: an unknown client, an order already validated. The caller receives a soap:Fault message whose text is the Fault title of the component and whose detail is the XML document of the payload column. The job itself keeps listening.

EntréeInput

Un lien Main, obligatoire. Sa colonne payload (Document), si elle existe, donne le détail de l'erreur. One Main link, required. Its payload column (Document), if any, gives the detail of the fault.

SortieOutput

Aucun flux Il termine sa branche. No flow It ends its branch.

Déclencheurs en sortieOutput triggers

On Component Ok Run if

UtilisationUsage

La branche d'erreur d'une opérationThe error branch of an operation

row1 (Main) out1 (Main) out2 (Main) tESBProviderRequest_1 tXMLMap_1 tESBProviderResponse_1 tESBProviderFault_1

La sortie out2 reçoit les requêtes que le job refuse et construit le document du détail, celui que le WSDL déclare pour cette erreur. The out2 output receives the requests the job refuses and builds the detail document, the one the WSDL declares for this fault.

Une erreur par casOne fault per case

notFound (Main) notAllowed (Main) tXMLMap_1 tESBProviderFault_1 tESBProviderFault_2

Un job peut contenir plusieurs tESBProviderFault, chacun avec son titre. Le job créé depuis une opération du service en reçoit un par erreur déclarée dans le WSDL, avec le nom de cette erreur pour titre. A job can hold several tESBProviderFault components, each with its own title. The job created from an operation of the service gets one per fault declared in the WSDL, with the name of that fault as its title.

  1. Déposez le tESBProviderFault depuis la famille ESB › Web Services, dans le job du tESBProviderRequest. Drop the tESBProviderFault from the ESB › Web Services family, in the job of the tESBProviderRequest.
  2. Reliez-y la branche des cas d'erreur, avec une colonne payload de type Document si l'erreur a un détail. Connect the branch of the error cases to it, with a payload column of type Document if the fault has a detail.
  3. Saisissez le Titre Fault, entre guillemets : c'est une expression Java. Enter the Fault title, in double quotes: it is a Java expression.

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 paramètre avancé Propriétés personnalisées de l'activité de service (SERVICE_ACTIVITY_CUSTOM_PROPERTIES, des couples nom et valeur joints à l'erreur pour le Service Activity Monitoring) existe dans le fichier du job mais n'est jamais affiché. Labels are those of the Component tab; the technical name, in grey, is the parameter name in the job file. The advanced parameter Service Activity Custom Properties (SERVICE_ACTIVITY_CUSTOM_PROPERTIES, name and value pairs attached to the fault for Service Activity Monitoring) exists in the job file but is never displayed.

ParamètreSetting DéfautDefault VisibleShown Description
SchémaSchemaSCHEMA payload (Document) ToujoursAlways Une colonne payload, de type Document. À la différence du tESBProviderResponse, le schéma se modifie et la colonne n'est pas obligatoire : si le flux entrant n'a pas de colonne payload de type Document, l'erreur part sans détail. One payload column, of type Document. Unlike the tESBProviderResponse, the schema can be edited and the column is not required: if the incoming flow has no payload column of type Document, the fault leaves without a detail.
Titre FaultFault titleESB_FAULT_TITLE "" ToujoursAlways Texte de l'erreur (faultstring), en Java : une chaîne entre guillemets, ou une expression ("Client " + row2.id + " not found"). Le nom du composant entre crochets y est ajouté : Client not found [tESBProviderFault_1]. Text of the fault (faultstring), in Java: a string in double quotes, or an expression ("Client " + row2.id + " not found"). The name of the component in square brackets is appended to it: Client not found [tESBProviderFault_1].

Variable globale : NB_LINE est déclarée par le composant, mais son modèle ne la renseigne pas. Global variable: NB_LINE is declared by the component, but its template never sets it.

Le message d'erreurThe fault message

Ce que l'appelant reçoit, pour une erreur envoyée par le composant et pour une exception du job. Valeurs relevées à l'exécution, sur un service SOAP 1.1. What the caller receives, for a fault sent by the component and for an exception of the job. Values read from runs, on a SOAP 1.1 service.

ÉlémentElement tESBProviderFault Exception dans le jobException in the job
Code HTTPHTTP code 500 500
faultcode businessFault, dans l'espace de noms du servicebusinessFault, in the namespace of the service soap:Server
faultstring Le Titre Fault, une espace, puis le nom du composant entre crochetsThe Fault title, a space, then the name of the component in square brackets Le message de l'exceptionThe message of the exception
detail Le document de payload, à partir de sa racine ; absent sans documentThe document of payload, from its root; missing without a document AbsentMissing
Console du jobConsole of the job RienNothing L'exception et sa pile d'appels, sur la sortie d'erreurThe exception and its stack trace, on the error output

Une erreur est une réponseA fault is a response

Pour le job, envoyer une erreur n'est pas échouer : rien n'est écrit sur la sortie d'erreur, aucun tLogCatcher n'est prévenu, et le job attend la requête suivante. Comme pour le tESBProviderResponse, une requête ne reçoit qu'un seul envoi : une réponse ou une erreur. For the job, sending a fault is not failing: nothing is written to the error output, no tLogCatcher is notified, and the job waits for the next request. As with the tESBProviderResponse, a request only gets one send: a response or a fault.

Studio et RuntimeStudio and Runtime

Le composant construit la même erreur dans les deux cas et la remet au tESBProviderRequest du job. À l'exécution du job, le serveur démarré par le job la renvoie ; dans le Talend Runtime, c'est le service publié par le conteneur. Voir tESBProviderRequest. The component builds the same fault in both cases and hands it to the tESBProviderRequest of the job. When the job runs, the server started by the job returns it; in the Talend Runtime, the service published by the container does. See tESBProviderRequest.

ExemplesExamples

Service Clients, opération getClient, dont le WSDL déclare l'erreur clientNotFound. Le job a été exécuté dans Talaxie et appelé en local ; messages et consoles sont copiés tels quels. Le nom du job est remplacé par MyService et les piles d'appels sont abrégées (…). Clients service, getClient operation, whose WSDL declares the clientNotFound fault. The job was run in Talaxie and called locally; messages and consoles are copied as they are. The job name is replaced with MyService and the stack traces are shortened (…).

Client inconnuUnknown client

row1 (Main) row2 (Main) row3 (Main) row4 (Filter) row5 (Reject) tESBProviderRequest_1 tLogRow_1 tJavaRow_1 tFilterRow_1 tESBProviderResponse_1 tESBProviderFault_1

Titre Fault : "Client not found". Pour un client inconnu, le tJavaRow met dans payload le document du détail, et le tFilterRow envoie la ligne vers son rejet : Fault title: "Client not found". For an unknown client, the tJavaRow puts the detail document in payload, and the tFilterRow sends the row to its reject:

org.dom4j.Document doc = org.dom4j.DocumentHelper.createDocument();
org.dom4j.Element root = doc.addElement("tns:clientNotFound", "http://www.talend.org/service/");
root.addElement("id").setText(id);
root.addElement("reason").setText("No client with this id");
output_row.payload = new routines.system.Document();
output_row.payload.setDocument(doc);
POST http://localhost:8090/services/Clients
SOAPAction: "http://www.talend.org/service/getClient"

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><tns:getClientRequest xmlns:tns="http://www.talend.org/service/"><id>99</id></tns:getClientRequest></soap:Body></soap:Envelope>

HTTP 500 Server Error
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><soap:Fault><faultcode xmlns:ns1="http://www.talend.org/service/">ns1:businessFault</faultcode><faultstring>Client not found [tESBProviderFault_1]</faultstring><detail><tns:clientNotFound xmlns:tns="http://www.talend.org/service/"><id>99</id><reason>No client with this id</reason></tns:clientNotFound></detail></soap:Fault></soap:Body></soap:Envelope>

Le document se retrouve sous <detail>. La console du job ne montre que la requête, affichée par le tLogRow ; le job sert ensuite les requêtes suivantes. The document ends up under <detail>. The console of the job only shows the request, printed by the tLogRow; the job then serves the next requests.

La même erreur, vue par un tESBConsumerThe same fault, seen by a tESBConsumer

Un second job appelle le service pour les clients 1 et 99. Le tESBConsumer sort la réponse sur son lien Response (tLogRow_1) et l'erreur sur son lien Fault (tLogRow_2, mode Vertical) : A second job calls the service for clients 1 and 99. The tESBConsumer outputs the response on its Response link (tLogRow_1) and the fault on its Fault link (tLogRow_2, Vertical mode):

.---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------.
|                                                                                        #1. tLogRow_2                                                                                        |
+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| key         | value                                                                                                                                                                         |
+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| faultCode   | {http://www.talend.org/service/}businessFault                                                                                                                                 |
| faultString | Client not found [tESBProviderFault_1]                                                                                                                                        |
| faultActor  | null                                                                                                                                                                          |
| faultNode   | null                                                                                                                                                                          |
| faultRole   | null                                                                                                                                                                          |
| faultDetail | <?xml version="1.0" encoding="UTF-8"?>
<tns:clientNotFound xmlns:tns="http://www.talend.org/service/"><id>99</id><reason>No client with this id</reason></tns:clientNotFound> |
+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

faultCode porte l'espace de noms du service entre accolades ; faultDetail est le document du détail. (Le saut de ligne après la déclaration XML vient de l'affichage du document par le tLogRow.) faultCode carries the namespace of the service in braces; faultDetail is the detail document. (The line break after the XML declaration comes from the way the tLogRow prints the document.)

Par comparaison : une exceptionBy comparison: an exception

Dans le même job, le tJavaRow lève new RuntimeException("Clients database is unreachable") pour l'identifiant boom. Aucun tESBProviderFault n'intervient : In the same job, the tJavaRow throws new RuntimeException("Clients database is unreachable") for the boom identifier. No tESBProviderFault is involved:

POST http://localhost:8090/services/Clients
SOAPAction: "http://www.talend.org/service/getClient"

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><tns:getClientRequest xmlns:tns="http://www.talend.org/service/"><id>boom</id></tns:getClientRequest></soap:Body></soap:Envelope>

HTTP 500 Server Error
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><soap:Fault><faultcode>soap:Server</faultcode><faultstring>Clients database is unreachable</faultstring></soap:Fault></soap:Body></soap:Envelope>

Code soap:Server, pas de détail : l'appelant ne peut pas distinguer ce cas d'une panne. Réservez les exceptions aux pannes, et le tESBProviderFault aux refus que l'appelant doit comprendre. soap:Server code, no detail: the caller cannot tell this case from a breakdown. Keep exceptions for breakdowns, and the tESBProviderFault for the refusals the caller must understand.

PiègesPitfalls

Le nom du composant dans le texteThe component name in the text

[tESBProviderFault_1] est toujours ajouté au titre. Un appelant qui compare le texte de l'erreur à une valeur attendue échouera : faites-lui lire le code ou le détail. Le nom change aussi si le composant est supprimé puis recréé. [tESBProviderFault_1] is always appended to the title. A caller that compares the text of the fault to an expected value will fail: have it read the code or the detail. The name also changes if the component is deleted then created again.

Un code d'erreur uniqueA single fault code

Le code est toujours businessFault, quel que soit le composant ou le titre : il ne se règle pas. Pour distinguer plusieurs erreurs, donnez-leur des documents de détail différents, comme le WSDL le prévoit. The code is always businessFault, whatever the component or the title: it cannot be set. To tell several faults apart, give them different detail documents, as the WSDL provides for.

Le détail n'est pas comparé au WSDLThe detail is not checked against the WSDL

Le composant envoie le document reçu sans vérifier qu'il correspond à une erreur déclarée par l'opération. Un client généré depuis le WSDL ne reconnaîtra l'erreur que si la racine du détail est l'élément déclaré, avec son espace de noms. The component sends the received document without checking that it matches a fault declared by the operation. A client generated from the WSDL will only recognise the fault if the root of the detail is the declared element, with its namespace.

Sans tESBProviderRequestWithout a tESBProviderRequest

Dans un job sans tESBProviderRequest, le composant n'envoie rien et écrit à chaque ligne : [WARN] nonsense: tESBProviderFault component used without tESBProviderRequest component on the job. Il ne sert pas non plus à arrêter un job ordinaire : voyez le tDie. In a job without a tESBProviderRequest, the component sends nothing and writes at each row: [WARN] nonsense: tESBProviderFault component used without tESBProviderRequest component on the job. Nor is it meant to stop an ordinary job: see the tDie.

ConseilsTips

Déclarer les erreurs dans le WSDLDeclare the faults in the WSDL

Ajoutez un wsdl:fault à l'opération et son élément au schéma : les appelants savent quoi attendre, et le job créé depuis l'opération reçoit le tESBProviderFault correspondant. Add a wsdl:fault to the operation and its element to the schema: callers know what to expect, and the job created from the operation gets the matching tESBProviderFault.

Mettre l'information dans le détailPut the information in the detail

Le titre est fait pour être lu par une personne. Ce qu'un programme doit exploiter (identifiant refusé, motif, code interne) a sa place dans le document du détail, où un tESBConsumer le retrouve dans la colonne faultDetail. The title is meant to be read by a person. What a program must use (refused identifier, reason, internal code) belongs in the detail document, where a tESBConsumer finds it in the faultDetail column.

Voir aussiSee also