This component allows to expose Talend jobs as services into Petals and to execute them inside the bus.
It only acts as service provider, not as a service consumer.
This component supports jobs created with both Talend Open Studio and Talend Integration Suite.

It provides several mechanisms to pass information and data to a job.
Il also supports several mechanisms to retrieve information and data from a job.


Before going further, it must be clear that no configuration for this component is intended to be created by hand.
And neither by the Petals Studio. In fact, only Talend Open Studio and Talend Integration Suite have the ability to generate a correct configuration for this component.

h1. The way it works

This section deals with the way requests are processed by the Petals-SE-Talend component.
As a user, it is important to understand the logic of the component to use it efficiently.


There are five steps in the processing of a request.

h2. Validating the request

When a request is received and started to be processed in the Petals-SE-Talend component, it is validated before being really processed.
The following list describes the order and the conditional steps in this validation process.
# If the validate-by-wsdl parameter is set to true, either in the component or in the service-unit, then the request is validated against the WSDL's schemas of the service-unit.
## If the validation fails, a fault is raised.
## Be careful, WSDL-based validation does not work when the input message contains attachments. The Talend export for Petals does prevent that from happening.
## Be careful, the current implementation of this feature makes disk access, thus reducing the performances.
# Then, there is a check made with respect to the singleton property of a job.
If a job is singleton, it means that only one instance of this job can be executed at once. One typical example of a singleton job is a job which moves data from one database to another. It would make no sense for two instances of this job tor un at the same time, especially if they work on the same databases.
If the job is singleton and already running, then a fault is raised.

h2. Preparing the job's input

Once the request has been accepted, it is parsed to get the different possible parameters for a job.
The message input contains up to 4 parts, that are desribed in the serivce's WSDL.
# The first parameters are the context parameters, child elements of the contexts element from the input message. These parameters will be passed to the job in its main method.
# Then, the data flow to be passed to a tPetalsIOnput instance is retrieved from the request. 
# The third kind of parameters is the input attachments.
## Each input attachments is serialized as a temporary file.
## Its location will be passed to the job through a context variable. This is why attachments are associated with context variables.

Notice that the input message may not define any of these parameters. In this case, the component will pass nothing to the job.

In fact, the WSDL content and the expected parameters depend on the job's content and on the defined options during the export operation.


h2. Executing the job

At this point, the Petals-SE-Talend has built the job instance and prepared its parameter.
If the job contains a tPetalsInput component, the data for this component is passed to the job.
The Talend contexts and options are then passed to the job and it is executed.



h2. Getting the job's output

The job's output is an array of array of String.
This result can contain only an integer, indicating the result of the job execution, or raw data (if the job has a tBufferOutput).
This is a way to determine whether the job execution succedded or not. The Petals-SE-Talend does not do it. It is the responsibility of the client to make this check (since in fact, it depends on the job itself).

The deletion of these files is not an option. Letting them on the disk could represent important risks. Indeed, a malicious client could override the context on each call, thus creating an infinite number of files on the disk. Unfinite until the disk crashes, obviously.

Now that everything has been gathered from the job, the response can be built and returned.
Hence, the response can count up to 3 parts:
# The job's result (String\[\]\[\]). This part is always returned.
# The output data beans, if the job contained a tPetalsOutput.
# The output attachments.

Two products can be used to create Talend jobs and export them into Petals: Talend Open Studio, which is an open source product, and Talend Integration Suite, which is the upgraded version of Talend Open Studio (but not free).
There are slight differences between what can be made in these two products.

h2. Talend Open Studio

Talend Open Studio does not support any specific component for Petals.
It supports the following features for the Petals-SE-Component:
* Expose a context as a parameter into the service's WSDL.
* Pass attachment files to a job.
* Pass native parameters to a job.
* Get the job's execution result.

Other features are only supported by Talend Integration Suite.
However, it is possible to use alternative ways, depending on the missing features.


h2. Talend Integration Suite

In Talend Integration Suite, all the features of Talend Open Studio are supported. In fact, there are more.

* You can use tPetalsInput and tPetalsOutput components in your jobs.
** These components respectively allow you to pass data from Petals to the job and from the job to Petals.
** These two components do not have any specific parameters. They just need their schema to be defined.
* You can simulate the Petals behavior for these two components, meaning you can execute your job in Talend Integration Suite if it contains a tPetalsInput or a tPetalsOutput component.
** Thus, for a tPetalsInput, you can provide what would be the Petals input from a file that will be loaded before the simulation.
** For the tPetalsOutput, the returned document will be printed into the console.
* Eventually, Talend Integration Suite allows to attach files in the responses.

h2. The Talend export for Petals

The export is the same in both Talend Open Studio and Talend Integration Suite.
The generated artifacts are the same in both of them. The content of the jbi.xml is the same in both of them.
The only differences are the job's content (which Talend components) and the generated WSDL (which depend on the job content and the export options).

The service-unit structure and the jbi.xml are desribed farther.
This section only introduces the export options, their impact on the result, while the next section describes the generated WSDL.

Here is a snapshot version of the Talend export for Petals.

!SimpleJobExport.jpg!

The target file is the location of the service-assembly to generate.
The job version meaning is explicit.

h1.

h1. Component Configuration


The component can be configured through its JBI descriptor file, as shown below.
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi
    version="1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
    xmlns:jbi="http://java.sun.com/xml/ns/jbi"
    xmlns:talend="http://petals.ow2.org/components/talend/version-1">
    
    <jbi:component type="service-engine">
        
        <jbi:identification>
            <jbi:name>petals-se-talend</jbi:name>
            <jbi:description>A service engine to expose and run Talend jobs as services in Petals</jbi:description>
        </jbi:identification>
        
        <jbi:component-class-name>org.ow2.petals.se.talend.TalendSe</jbi:component-class-name>
        <jbi:component-class-path>
            <jbi:path-element/>
        </jbi:component-class-path>
        
        <jbi:bootstrap-class-name>org.ow2.petals.component.framework.DefaultBootstrap</jbi:bootstrap-class-name>
        <jbi:bootstrap-class-path>
            <jbi:path-element />
        </jbi:bootstrap-class-path>
        
        <!-- CDK specific fields -->
        <petalsCDK:acceptor-pool-size>5</petalsCDK:acceptor-pool-size>
        <petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
        <petalsCDK:ignored-status>DONE_AND_ERROR_IGNORED</petalsCDK:ignored-status>
        <petalsCDK:jbi-listener-class-name>org.ow2.petals.se.talend.TalendJBIListener</petalsCDK:jbi-listener-class-name>        
        
        <!-- Component specific configuration -->
        <!--
            The WSDL-based validation for exchanges checks that the called operation,
            the MEP and the input message are valid with respect to the WSDL.
            
            This property is also available for service-units.
            Enabling this property in the component enables it for all the service-units
            deployed on this component and overrides their configurations.
            
            When set to false, the service-unit property is used.
            
            Set this property to true to enable it, false to disable it.
            This property is optional. Default is false.
            Beware, performances are impacted if this property is enabled.
         -->
        <talend:validate-exchange-by-wsdl>false</talend:validate-exchange-by-wsdl>
        
    </jbi:component>
</jbi:jbi>{code}



The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.
{include:0 CDK Component Configuration Table}
This component also has one specific configuration parameter.

|| Parameter || Description || Default || Required ||
| validate-exchange-by-wsdl | True to validate the received messages with respect to the WSDL's schemas of the target service. \\
This parameter is also available in the configuration of the service-units. \\
Setting it in the component enables it for all the service-units deployed on this component. It also overrides the service-unit configuration for this parameter. \\
\\
Beware, for the moment, WSDL-based validation does not work with messages having attachments. | false | false |

{warning}
The Petals-SE-Talend component can only handle messages coming from inside the bus. Therefore, you cannot specify an external-listener class-name.{warning}

h1. Service Configuration

h2. Service Unit content&nbsp;