ComposantsComponents

ComposantsComponents › OrchestrationOrchestration

tRunJob

tRunJob

OrchestrationOrchestration SystèmeSystem

Lance un autre job du projet (le job enfant) depuis le job en cours (le job parent), en donnant des valeurs à ses variables de contexte, puis récupère son code de retour et, au besoin, les lignes qu'il renvoie. C'est le composant pour découper un traitement en plusieurs jobs, ou lancer le même job pour chaque fichier, chaque client… Runs another job of the project (the child job) from the current job (the parent job), giving values to its context variables, then gets its exit code and, if needed, the rows it returns. It is the component to split a processing into several jobs, or to run the same job for each file, each customer…

EntréeInput

Aucune : il peut commencer un sous-job. Sinon un lien Iterate (un lancement par itération) ou Main. None: it can start a subjob. Otherwise one Iterate link (one run per iteration) or Main.

SortieOutput

Facultative : un lien Main, avec les lignes que le job enfant envoie par un tBufferOutput. Optional: one Main link, with the rows that the child job sends through a tBufferOutput.

Déclencheurs en sortieOutput triggers

On Subjob Ok On Subjob Error On Component Ok On Component Error Run if

On Subjob : seulement quand il commence son sous-job. On Subjob: only when it starts its subjob.

UtilisationUsage

Une étape du traitementOne step of the processing

OnSubjobOk OnSubjobOk tRunJob_1 tRunJob_2 tJava_1

Chaque job enfant s'exécute en entier, pré-job et post-job compris, puis le parent continue : un job « chef d'orchestre » enchaîne les étapes. Each child job runs entirely, prejob and postjob included, then the parent goes on: a "conductor" job chains the steps.

Pour chaque ligne d'un fluxFor each row of a flow

row1 (Main) Iterate tFileInputDelimited_1 tFlowToIterate_1 tRunJob_1

Le job enfant est lancé une fois par ligne ; ses paramètres de contexte lisent les valeurs de la ligne en cours : (String) globalMap.get("row1.name"). The child job is run once per row; its context parameters read the values of the current row: (String) globalMap.get("row1.name").

  1. Déposez le tRunJob depuis la famille Orchestration (ou Système) de la palette, ou glissez directement le job enfant depuis le Référentiel sur la grille : un tRunJob qui le lance est créé. Drop the tRunJob from the Orchestration (or System) family of the palette, or drag the child job straight from the Repository onto the canvas: a tRunJob that runs it is created.
  2. Dans Job, choisissez le job enfant (bouton …), sa version (Latest : la plus récente) et l'environnement de contexte où il tourne. Un double clic sur le tRunJob ouvre le job enfant. In Job, choose the child job (… button), its version (Latest: the most recent) and the context environment it runs in. A double click on the tRunJob opens the child job.
  3. Dans Paramètres de contexte, ajoutez une ligne par variable du job enfant à fixer : son nom, choisi dans la liste, et une expression Java évaluée dans le job parent. In Context Param, add one row per child job variable to set: its name, chosen in the list, and a Java expression evaluated in the parent job.

Même JVM ou processus indépendantSame JVM or independent process

  • Par défaut, le job enfant tourne dans la machine Java du parent : le parent crée un objet du job enfant et appelle son lancement. Ses sorties arrivent dans la même console, il peut renvoyer des lignes, et les valeurs des paramètres de contexte lui sont passées telles quelles, avec leur type Java. By default, the child job runs in the Java machine of the parent: the parent creates an object of the child job and calls its start. Its outputs arrive in the same console, it can return rows, and the values of the context parameters are passed to it as they are, with their Java type.
  • Processus indépendant : le job enfant est lancé par une nouvelle commande java, avec ses propres réglages de mémoire. Sa sortie standard est recopiée dans la console du parent ; sa sortie d'erreur est gardée pour CHILD_EXCEPTION_STACKTRACE. Les paramètres passent par la ligne de commande, sous forme de texte, et les lignes d'un tBufferOutput ne reviennent pas au parent. Independent process: the child job is started by a new java command, with its own memory settings. Its standard output is copied to the parent console; its error output is kept for CHILD_EXCEPTION_STACKTRACE. The parameters go through the command line, as text, and the rows of a tBufferOutput do not come back to the parent.

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. Labels are those of the Component tab; the technical name, in grey, is the parameter name in the job file.

ParamètreSetting DéfautDefault VisibleShown Description
SchémaSchemaSCHEMA videempty ToujoursAlways Colonnes des lignes renvoyées par le job enfant. Les valeurs sont reprises par position : gardez l'ordre des colonnes du tBufferOutput. Columns of the rows returned by the child job. The values are taken by position: keep the column order of the tBufferOutput.
Utiliser un Job dynamiqueUse dynamic jobUSE_DYNAMIC_JOB NonNo ToujoursAlways Le job à lancer est choisi à l'exécution, parmi plusieurs jobs choisis dans Job. Il tourne toujours dans un processus indépendant. The job to run is chosen at run time, among several jobs selected in Job. It always runs in an independent process.
Context jobCONTEXT_JOB videempty Job dynamiqueDynamic job Expression Java qui donne le nom du job à lancer. Un nom absent de la liste arrête le composant : The child job named … is not in the job list. Java expression that gives the name of the job to run. A name missing from the list stops the component: The child job named … is not in the job list.
JobPROCESS · PROCESS:PROCESS_TYPE_VERSION · PROCESS:PROCESS_TYPE_CONTEXT — ToujoursAlways Le job enfant, choisi dans le projet, avec sa version (Latest : la plus récente au moment de la génération) et l'environnement de contexte dans lequel il tourne. Les valeurs de cet environnement sont son point de départ. The child job, chosen in the project, with its version (Latest: the most recent at generation time) and the context environment it runs in. The values of this environment are its starting point.
ContexteContextCONTEXT_NAME Default Job dynamiqueDynamic job Environnement de contexte du job lancé, écrit sans guillemets (ils sont retirés s'il y en a). Context environment of the job run, written without quotes (they are removed if present).
Utiliser un processus indépendant pour exécuter le sous-JobUse an independent process to run subjobUSE_INDEPENDENT_PROCESS NonNo Sans job dynamiqueWithout dynamic job Lance le job enfant dans une nouvelle machine Java. Voir Même JVM ou processus indépendant. Runs the child job in a new Java machine. See Same JVM or independent process.
Arrêter en cas d'erreur de l'enfantDie on child errorDIE_ON_CHILD_ERROR OuiYes ToujoursAlways Quand le job enfant échoue, le tRunJob échoue aussi. Décochée, le parent continue : le code de retour dit ce qui s'est passé. Voir les erreurs. When the child job fails, the tRunJob fails too. Unchecked, the parent goes on: the exit code tells what happened. See the errors.
Transmettre le contexte completTransmit whole contextTRANSMIT_WHOLE_CONTEXT NonNo ToujoursAlways Passe toutes les variables de contexte du parent : le job enfant prend la valeur de celles qui portent le même nom que les siennes, et ignore les autres. Passes all the context variables of the parent: the child job takes the value of those that have the same name as its own, and ignores the others.
Paramètres de contexteContext ParamCONTEXTPARAMS videempty ToujoursAlways Une ligne par variable du job enfant à fixer. Paramètres : son nom, choisi dans la liste de ses variables. Valeurs : une expression Java, évaluée dans le parent à chaque lancement. Ces lignes passent après le contexte complet : elles l'emportent sur lui. One row per child job variable to set. Parameters: its name, chosen in the list of its variables. Values: a Java expression, evaluated in the parent at each run. These rows come after the whole context: they win over it.

Paramètres avancésAdvanced settings

ParamètreSetting DéfautDefault VisibleShown Description
Propager les résultats enfants au schéma de sortiePropagate the child result to the output schemaPROPAGATE_CHILD_RESULT NonNo Même JVM, sans job dynamiqueSame JVM, without dynamic job Pour un tRunJob au milieu d'un flux : la sortie reçoit les lignes du job enfant au lieu de la ligne reçue. Décochée, la ligne reçue repart si les schémas d'entrée et de sortie sont identiques. For a tRunJob in the middle of a flow: the output receives the rows of the child job instead of the incoming row. Unchecked, the incoming row goes on if the input and output schemas are identical.
Afficher les paramètresPrint ParametersPRINT_PARAMETER NonNo ToujoursAlways Écrit dans la console, avant chaque lancement, les arguments passés au job enfant (voir l'exemple). Les mots de passe y sont chiffrés. Writes to the console, before each run, the arguments passed to the child job (see the example). Passwords are encrypted in it.
Utiliser les arguments JVM du Job enfantUse child job JVM argumentsUSE_CHILD_JVM_SETTING OuiYes Job dynamique ou processus indépendantDynamic job or independent process La nouvelle machine Java reprend les arguments du job enfant. Choix exclusif avec le suivant. The new Java machine takes the arguments of the child job. Exclusive choice with the next one.
Écraser les arguments JVM du Job enfantOverwrite child job JVM argumentsUSE_CUSTOM_JVM_SETTING · JVM_ARGUMENTS NonNo Job dynamique ou processus indépendantDynamic job or independent process Utilise à la place les arguments du tableau JVM, une expression Java par ligne ("-Xmx2048M"). Uses instead the arguments of the JVM table, one Java expression per row ("-Xmx2048M").
Utilisez un contexte dynamique pour le sous-JobUse dynamic context for subJobUSE_DYNAMIC_CONTEXT · DYNAMIC_CONTEXT NonNo ToujoursAlways Le nom de l'environnement de contexte du job enfant vient d'une expression Java, évaluée à l'exécution (context.env), à la place de celui choisi dans Job. The name of the context environment of the child job comes from a Java expression, evaluated at run time (context.env), instead of the one chosen in Job.
Utilisez un classpath supplémentaire pour le sous-JobUse extra classpath for subJobUSE_EXTRA_CLASSPATH · EXTRA_CLASSPATH NonNo Job dynamique ou processus indépendantDynamic job or independent process Chemins (expression Java) placés devant le classpath de la nouvelle machine Java. Paths (Java expression) placed in front of the classpath of the new Java machine.
Charger les paramètres de contexte depuis un fichierLoad context parameters from fileLOAD_CONTEXT_FROM_FILE NonNo Job dynamique ou processus indépendantDynamic job or independent process Les paramètres passent par un fichier temporaire, effacé à la fin ; les mots de passe y sont chiffrés. The parameters go through a temporary file, deleted at the end; passwords are encrypted in it.

Variables globalesGlobal variables

Disponibles après le composant, à chaque lancement : Available after the component, at each run:

CHILD_RETURN_CODE
Integer : 0 si le job enfant a réussi, le code d'erreur d'un tDie, 1 pour une exception. En processus indépendant, le code de sortie de la nouvelle machine Java.Integer: 0 if the child job succeeded, the error code of a tDie, 1 for an exception. In an independent process, the exit code of the new Java machine.
CHILD_EXCEPTION_STACKTRACE
String : la trace de l'exception du job enfant. En processus indépendant, sa sortie d'erreur, quand le code n'est pas 0.String: the exception trace of the child job. In an independent process, its error output, when the code is not 0.
((Integer) globalMap.get("tRunJob_1_CHILD_RETURN_CODE"))
((String) globalMap.get("tRunJob_1_CHILD_EXCEPTION_STACKTRACE"))

ExemplesExamples

Le job enfant, ChildJob, a une variable de contexte customer (String, Nobody par défaut) et un tJava. Sorties copiées depuis une exécution du job parent ; les noms des jobs sont remplacés par MyJob (parent) et ChildJob (enfant), les traces d'exception sont abrégées. The child job, ChildJob, has a context variable customer (String, Nobody by default) and a tJava. Outputs copied from a run of the parent job; the job names are replaced with MyJob (parent) and ChildJob (child), the exception traces are shortened.

// ChildJob › tJava_1
System.out.println("Child job: hello " + context.customer);

Passer une valeur au job enfantPass a value to the child job

OnSubjobOk tRunJob_1 tJava_1

Paramètres de contexte : customer / "Ada". Le tJava du parent affiche le code de retour. Context Param: customer / "Ada". The parent tJava prints the exit code.

System.out.println("Child return code: " + globalMap.get("tRunJob_1_CHILD_RETURN_CODE"));
Child job: hello Ada
Child return code: 0

Même sortie en processus indépendant. Same output in an independent process.

Sans paramètre, puis avec le contexte completWithout a parameter, then with the whole context

OnSubjobOk tRunJob_1 tRunJob_2

Le parent a lui aussi une variable customer, qui vaut Grace. tRunJob_1 : aucun réglage. tRunJob_2 : Transmettre le contexte complet coché. The parent also has a customer variable, set to Grace. tRunJob_1: no setting. tRunJob_2: Transmit whole context checked.

Child job: hello Nobody
Child job: hello Grace

Sans réglage, le job enfant garde la valeur de son propre contexte, même si le parent a une variable du même nom. Without a setting, the child job keeps the value of its own context, even if the parent has a variable with the same name.

Un lancement par ligneOne run per row

row1 (Main) Iterate tFixedFlowInput_1 tFlowToIterate_1 tRunJob_1

Trois lignes (name : Ada, Grace, Alan). Paramètres de contexte : customer / (String) globalMap.get("row1.name"). Three rows (name: Ada, Grace, Alan). Context Param: customer / (String) globalMap.get("row1.name").

Child job: hello Ada
Child job: hello Grace
Child job: hello Alan

Lignes renvoyées par le job enfantRows returned by the child job

ChildJob

row1 (Main) tFixedFlowInput_1 tBufferOutput_1

MyJob

row1 (Main) tRunJob_1 tLogRow_1

Le job enfant met deux lignes (id, name) dans un tBufferOutput ; le tRunJob a le même schéma. The child job puts two rows (id, name) in a tBufferOutput; the tRunJob has the same schema.

1|Ada
2|Grace

Afficher les paramètresPrint Parameters

Le premier exemple, avec Afficher les paramètres coché. La ligne donne la classe du job enfant et tous ses arguments ; --father_pid et --root_pid changent à chaque exécution. The first example, with Print Parameters checked. The line gives the class of the child job and all its arguments; --father_pid and --root_pid change at each run.

tRunJob_1 in MyJob call demo.childjob_0_1.ChildJob with:

[--father_pid=rMjON7, --root_pid=rMjON7, --father_node=tRunJob_1, --context=Default, --stat_port=3334, --parent_part_launcher=JOB:MyJob/NODE:tRunJob_1, --context_param customer=Ada]

Child job: hello Ada

Erreurs du job enfantErrors of the child job

Le job enfant ChildJob est ici remplacé par un job qui échoue : un tJava qui lève une exception, ou un tDie (message "File not found", code d'erreur 4). The child job ChildJob is replaced here with a job that fails: a tJava that throws an exception, or a tDie (message "File not found", error code 4).

Exception, arrêt en cas d'erreur (par défaut)Exception, die on error (default)

// ChildJob › tJava_1
if (true) {
    throw new RuntimeException("Database unavailable");
}
Exception in component tJava_1 (ChildJob)
java.lang.RuntimeException: Database unavailable
	at …
Exception in component tRunJob_1 (MyJob)
java.lang.RuntimeException: Child job running failed.
java.lang.RuntimeException: Database unavailable
	at …

Le tRunJob reprend l'exception du job enfant ; le parent s'arrête avec le code 1. The tRunJob reports the exception of the child job; the parent stops with code 1.

Exception, case décochée : le parent continueException, box unchecked: the parent goes on

OnSubjobOk tRunJob_1 tJava_1
System.out.println("Child return code: " + globalMap.get("tRunJob_1_CHILD_RETURN_CODE"));
String trace = (String) globalMap.get("tRunJob_1_CHILD_EXCEPTION_STACKTRACE");
System.out.println("First line: " + trace.split("\n")[0]);
Exception in component tJava_1 (ChildJob)
java.lang.RuntimeException: Database unavailable
	at …
Child return code: 1
First line: java.lang.RuntimeException: Database unavailable

L'exception est écrite par le job enfant, mais le parent suit On Subjob Ok et se termine avec le code 0. The exception is written by the child job, but the parent follows On Subjob Ok and ends with code 0.

tDie dans le job enfanttDie in the child job

Le job enfant écrit Child job: the file is missing, puis son tDie s'exécute. Arrêt en cas d'erreur coché : The child job writes Child job: the file is missing, then its tDie runs. Die on error checked:

Child job: the file is missing
File not found
Exception in component tRunJob_1 (MyJob)
java.lang.RuntimeException: Child job running failed.

	at …

Un tDie ne laisse pas d'exception : rien ne suit Child job running failed. Le parent se termine avec le code 4 du tDie. Case décochée, le parent continue : A tDie leaves no exception: nothing follows Child job running failed. The parent ends with the tDie code 4. Box unchecked, the parent goes on:

Child job: the file is missing
File not found
Child return code: 4

tDie, processus indépendant, case décochéetDie, independent process, box unchecked

Child job: the file is missing
Child job returns 4. It doesn't terminate normally.
File not found

Child return code: 4

Le tRunJob écrit sur la sortie d'erreur le code de la nouvelle machine Java, suivi de la sortie d'erreur du job enfant (File not found), qu'il a gardée. Case cochée, le même texte devient le message de l'exception du tRunJob. The tRunJob writes on the error output the code of the new Java machine, followed by the error output of the child job (File not found), which it kept. Box checked, the same text becomes the message of the tRunJob exception.

PiègesPitfalls

Un texte pour une variable IntegerA text for an Integer variable

Le job enfant a une variable limit de type Integer et affiche limit + 1. Paramètres de contexte : limit / "42", entre guillemets. The child job has a limit variable of type Integer and prints limit + 1. Context Param: limit / "42", in quotes.

Exception in component tRunJob_1 (MyJob)
java.lang.ClassCastException: class java.lang.String cannot be cast to class java.lang.Integer (java.lang.String and java.lang.Integer are in module java.base of loader 'bootstrap')
	at …

Dans la même JVM, le job enfant reçoit la valeur elle-même, un String, là où il attend un Integer ; le parent s'arrête avec le code 1. Avec 42 sans guillemets, ou en processus indépendant (les valeurs y passent en texte et sont converties) : In the same JVM, the child job receives the value itself, a String, where it expects an Integer; the parent stops with code 1. With 42 without quotes, or in an independent process (the values go as text and are converted):

Child job: limit + 1 = 43

Les variables globales ne passent pasGlobal variables are not passed

OnSubjobOk OnSubjobOk tSetGlobalVar_1 tJava_1 tRunJob_1

Le parent range "customer" = "Ada" et l'affiche ; le job enfant affiche globalMap.get("customer"). The parent stores "customer" = "Ada" and prints it; the child job prints globalMap.get("customer").

Parent job: customer = Ada
Child job: customer = null

Le job enfant a ses propres variables globales, même dans la JVM du parent. Passez la valeur par une variable de contexte. The child job has its own global variables, even in the JVM of the parent. Pass the value through a context variable.

ConseilsTips

Réagir à l'échec du job enfantReact to the failure of the child job

Décochez Arrêter en cas d'erreur de l'enfant et testez le code dans un Run if : ((Integer) globalMap.get("tRunJob_1_CHILD_RETURN_CODE")) != 0. Le parent peut alors écrire un message, relancer, ou s'arrêter avec un tDie. Uncheck Die on child error and test the code in a Run if: ((Integer) globalMap.get("tRunJob_1_CHILD_RETURN_CODE")) != 0. The parent can then write a message, try again, or stop with a tDie.

Des valeurs du bon typeValues of the right type

Dans la même JVM, chaque valeur de Paramètres de contexte doit avoir le type de la variable du job enfant : 42 pour un Integer, "42" pour un String, Integer.valueOf(…) pour convertir un texte. In the same JVM, each value of Context Param must have the type of the child job variable: 42 for an Integer, "42" for a String, Integer.valueOf(…) to convert a text.

Quand prendre un processus indépendantWhen to take an independent process

Pour un job enfant qui a besoin de ses propres arguments JVM (mémoire…), ou qui ne doit pas partager la mémoire du parent. Il coûte le démarrage d'une machine Java à chaque lancement et ne renvoie pas de lignes. For a child job that needs its own JVM arguments (memory…), or that must not share the memory of the parent. It costs the start of a Java machine at each run and returns no rows.

Un job enfant qui se lance aussi seulA child job that also runs alone

Donnez aux variables du job enfant des valeurs par défaut utilisables : il se teste alors seul, et un oubli dans les Paramètres de contexte se voit tout de suite (hello Nobody plus haut). Give the child job variables usable default values: it can then be tested alone, and something forgotten in the Context Param shows at once (hello Nobody above).

Voir aussiSee also