{section}{column}
( this is a first draft )
h1. Features
This Service-Engine (SE) allows to expose Talend jobs as services into Petals and to execute them inside the bus.
This component supports jobs created with both Talend Open Studio and Talend Integration Suite. It also provides several mechanisms to pass information and data to 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.
However, which one of these tool created the configuration is not important for this service-engine.
Two catagories of Talend jobs can be distinguished in the scope of Petals:
* Simple jobs, or classic jobs, are Talend jobs that do not need any specific interaction with Petals. Everything they need is in the job context and content.
* Petals jobs, are Talend jobs that may interact with the Petals-SE-Talend component.
h2. Classic Talend jobs
h2. Talend jobs for Petals
h3. Those created with Talend Open Studio
h3. Those created with Talend Integration Suite
In this former category, the permitted interactions depend on the job's content.
Basically, there are five kinds of interactions:
* Input parameters
** Context overriding: the service defines the contexts that can be overriden. You can use this mechanism to pass information or data to the job.
** File attachments: the service may expect attachments in input.
** Raw data: the service may also expect a flow of data rows to process inside the job. This mechanism relies on a Talend component called tPetalsInput.
* Output parameters
** The execution result: any executed job returns
For more information, please refer to the use cases.
{column}
{column:width=350px}
{panel}{toc}{panel}
{column}
{section}
h1. Component Configuration
Before installing the bc-ejb component, you must check in your $\{PETALS_HOME}/conf/server.properties configuration file if the property "petals.classloaders.isolated=true" is set and uncommented. The BC-EJB component need the isolated classloaders to work correctly.
The component can be configured through its JBI descriptor file like this :
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:jbi="http://java.sun.com/xml/ns/jbi" version="1.0">
<jbi:component type="binding-component" component-class-loader-delegation="parent-first">
<jbi:identification>
<jbi:name>petals-bc-ejb</jbi:name>
<jbi:description>an EJB Binding Component sending messages to local or distant EJB instances</jbi:description>
</jbi:identification>
<jbi:component-class-name>org.ow2.petals.bc.ejb.EjbBC</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-classname>
<jbi:bootstrap-class-path>
<jbi:path-element/>
</jbi:bootstrap-class-path>
<petalsCDK:acceptor-pool-size>5</petalsCDK:acceptor-pool-size>
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<petalsCDK:ignored-status>NOTHING_IGNORED</petalsCDK:ignored-status>
<shared-library>petals-sl-ejb</shared-library>
<petalsCDK:jbi-listener-class-name>org.ow2.petals.bc.ejb.listener.JBIListener</petalsCDK:jbi-listener-class-name>
</jbi:component>
</jbi:jbi>{code}
This component doesn't have any specific configuration parameters.
You can customize the component configuration by changing the following common parameters.
{include:0 CDK Component Configuration Table}
{warning}
EJB binding component can only handle outgoing message (JBI \-> EJB), so you can't specify an external-listenerclass-name.{warning}
h1. Service Configuration
h2. Send a JBI message to an external EJB
When a JBI message is received on an endpoint linked to an EJB, the message is transformed into a RMI message, then sent to the linked EJB.
!petals-bc-ejb.png!
The RMI message is created following these steps :
# The JBI message payload is mapped to Java objects. These objects (and their types) are used as operation parameters for the RMI call. The mapping is done thanks to the PEtALS-JAXB-Databinding library. For more information about XML databinding feel free to read the chapter entitled XML to Java binding.
# The JBI message exchange operation local part is used as the EJB method to invoke.
# If a security subject is provided by the JBI message it is used as authentication information during the RMI invokation.
{info}
For more information about JAAS read the chapter : JAAS authentication for EJB calls
{info}
In order to reach the remote EJB, the component need to get an RMI stub of the EJB from a JNDI server. The JNDI name of the target EJB is defined in the parameter ejb.jndi.name.
The external EJB is called and the response is processed by the PEtALS-JAXB-Databinding library and then returned to the JBI environment.
h2. Service Unit descriptor
The Service Unit descriptor file ( jbi.xml ) looks like this :
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<!--
JBI descriptor for the PEtALS' "petals-bc-ejb" component (EJB).
Originally created for the version 1.1 of the component.
-->
<jbi:jbi version="1.0"
xmlns:ejb="http://petals.ow2.org/components/ejb/version-1.1"
xmlns:generatedNs="http://application.localisation.watersupply.petals.ow2.org/"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<!-- Import a Service into PEtALS or Expose a PEtALS Service => use a BC. -->
<jbi:services binding-component="true">
<!-- Import a Service into PEtALS => provides a Service. -->
<jbi:provides
interface-name="generatedNs:LocalisationFinderBusinessServicePortType"
service-name="generatedNs:LocalisationFinderBusinessService"
endpoint-name="LocalisationFinderBusinessServiceEndpoint">
<!-- CDK specific elements -->
<petalsCDK:wsdl>Localisation.wsdl</petalsCDK:wsdl>
<!-- Component specific elements -->
<ejb:ejb.jndi.name>LocalisationFinderBusinessService</ejb:ejb.jndi.name>
<ejb:java.naming.factory.initial>org.jnp.interfaces.NamingContextFactory</ejb:java.naming.factory.initial>
<ejb:java.naming.provider.url>jnp://localhost:1099/</ejb:java.naming.provider.url>
<ejb:ejb.version>2.1</ejb:ejb.version>
<ejb:ejb.home.interface>org.ow2.petals.watersupply.localisation.application.LocalisationFinderBusinessServiceRemoteHome</ejb:ejb.home.interface>
<ejb:marshalling.engine>jaxb</ejb:marshalling.engine>
<ejb:security.name />
<ejb:security.principal />
<ejb:security.credencials />
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}
*Configuration of a Service Unit to expose an EJB onto Petals ESB :*
{table-plus}
|| Parameter || Description || Default || Required ||
| ejb.jndi.name | The JNDI name of the targeted EJB | \- | Yes |
| java.naming.factory.initial | The name of the targeted JNDI Initial Context Factory | \- | Yes |
| java.naming.provider.url | The URL of the targeted JNDI service | \- | Yes |
| ejb.version | Implemention version of the targeted EJB.\\
Supported versions are 2.0, 2.1, 3.0 and 3.1 | \- | Yes |
| ejb.home.interface | Fully qualified name of the targeted EJB Home Interface. Used only
with ejb 2.0 and 2.1.
Fully qualified name of the targeted EJB Home Interface. Used only with ejb 2.0 and 2.1. | \- | No |
| security.name | Fully qualified name of the security module used. | \- | No |
| security.principal | Username | \- | No |
| security.credencials | Password | \- | No |
| marshalling.engine | The marshalling engine to use | jaxb | Yes |
{table-plus}
{include:0 CDK SU Provide Configuration}
{include:0 CDK Interceptor configuration for SU}
h2. Service Unit content
The service unit must contain a JAR archive including the EJB Interface (and EJB Home Interface for a 2.x EJB) and all specific Java classes used by this interface.
It is also highly recommended to provide a WSDL description of your EJB interface. This WSDL description will be used as Service Description for the JBI Endpoint linked to your EJB.
The directory structure of a SU for the BC-EJB must look like this :
{noformat}my-su-ejb.zip
+ META-INF
- jbi.xml
- my-ejb-wsdl-description.wsdl
- my-ejb.jar
- my-ejb-dependency1.jar
- my-ejb-dependency2.jar
h2. Provider restrictions
h2. Provider usage{noformat}
h1.
( this is a first draft )
h1. Features
This Service-Engine (SE) allows to expose Talend jobs as services into Petals and to execute them inside the bus.
This component supports jobs created with both Talend Open Studio and Talend Integration Suite. It also provides several mechanisms to pass information and data to 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.
However, which one of these tool created the configuration is not important for this service-engine.
Two catagories of Talend jobs can be distinguished in the scope of Petals:
* Simple jobs, or classic jobs, are Talend jobs that do not need any specific interaction with Petals. Everything they need is in the job context and content.
* Petals jobs, are Talend jobs that may interact with the Petals-SE-Talend component.
h2. Classic Talend jobs
h2. Talend jobs for Petals
h3. Those created with Talend Open Studio
h3. Those created with Talend Integration Suite
In this former category, the permitted interactions depend on the job's content.
Basically, there are five kinds of interactions:
* Input parameters
** Context overriding: the service defines the contexts that can be overriden. You can use this mechanism to pass information or data to the job.
** File attachments: the service may expect attachments in input.
** Raw data: the service may also expect a flow of data rows to process inside the job. This mechanism relies on a Talend component called tPetalsInput.
* Output parameters
** The execution result: any executed job returns
For more information, please refer to the use cases.
{column}
{column:width=350px}
{panel}{toc}{panel}
{column}
{section}
h1. Component Configuration
Before installing the bc-ejb component, you must check in your $\{PETALS_HOME}/conf/server.properties configuration file if the property "petals.classloaders.isolated=true" is set and uncommented. The BC-EJB component need the isolated classloaders to work correctly.
The component can be configured through its JBI descriptor file like this :
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<jbi:jbi xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:jbi="http://java.sun.com/xml/ns/jbi" version="1.0">
<jbi:component type="binding-component" component-class-loader-delegation="parent-first">
<jbi:identification>
<jbi:name>petals-bc-ejb</jbi:name>
<jbi:description>an EJB Binding Component sending messages to local or distant EJB instances</jbi:description>
</jbi:identification>
<jbi:component-class-name>org.ow2.petals.bc.ejb.EjbBC</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-classname>
<jbi:bootstrap-class-path>
<jbi:path-element/>
</jbi:bootstrap-class-path>
<petalsCDK:acceptor-pool-size>5</petalsCDK:acceptor-pool-size>
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<petalsCDK:ignored-status>NOTHING_IGNORED</petalsCDK:ignored-status>
<shared-library>petals-sl-ejb</shared-library>
<petalsCDK:jbi-listener-class-name>org.ow2.petals.bc.ejb.listener.JBIListener</petalsCDK:jbi-listener-class-name>
</jbi:component>
</jbi:jbi>{code}
This component doesn't have any specific configuration parameters.
You can customize the component configuration by changing the following common parameters.
{include:0 CDK Component Configuration Table}
{warning}
EJB binding component can only handle outgoing message (JBI \-> EJB), so you can't specify an external-listenerclass-name.{warning}
h1. Service Configuration
h2. Send a JBI message to an external EJB
When a JBI message is received on an endpoint linked to an EJB, the message is transformed into a RMI message, then sent to the linked EJB.
!petals-bc-ejb.png!
The RMI message is created following these steps :
# The JBI message payload is mapped to Java objects. These objects (and their types) are used as operation parameters for the RMI call. The mapping is done thanks to the PEtALS-JAXB-Databinding library. For more information about XML databinding feel free to read the chapter entitled XML to Java binding.
# The JBI message exchange operation local part is used as the EJB method to invoke.
# If a security subject is provided by the JBI message it is used as authentication information during the RMI invokation.
{info}
For more information about JAAS read the chapter : JAAS authentication for EJB calls
{info}
In order to reach the remote EJB, the component need to get an RMI stub of the EJB from a JNDI server. The JNDI name of the target EJB is defined in the parameter ejb.jndi.name.
The external EJB is called and the response is processed by the PEtALS-JAXB-Databinding library and then returned to the JBI environment.
h2. Service Unit descriptor
The Service Unit descriptor file ( jbi.xml ) looks like this :
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<!--
JBI descriptor for the PEtALS' "petals-bc-ejb" component (EJB).
Originally created for the version 1.1 of the component.
-->
<jbi:jbi version="1.0"
xmlns:ejb="http://petals.ow2.org/components/ejb/version-1.1"
xmlns:generatedNs="http://application.localisation.watersupply.petals.ow2.org/"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-4.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<!-- Import a Service into PEtALS or Expose a PEtALS Service => use a BC. -->
<jbi:services binding-component="true">
<!-- Import a Service into PEtALS => provides a Service. -->
<jbi:provides
interface-name="generatedNs:LocalisationFinderBusinessServicePortType"
service-name="generatedNs:LocalisationFinderBusinessService"
endpoint-name="LocalisationFinderBusinessServiceEndpoint">
<!-- CDK specific elements -->
<petalsCDK:wsdl>Localisation.wsdl</petalsCDK:wsdl>
<!-- Component specific elements -->
<ejb:ejb.jndi.name>LocalisationFinderBusinessService</ejb:ejb.jndi.name>
<ejb:java.naming.factory.initial>org.jnp.interfaces.NamingContextFactory</ejb:java.naming.factory.initial>
<ejb:java.naming.provider.url>jnp://localhost:1099/</ejb:java.naming.provider.url>
<ejb:ejb.version>2.1</ejb:ejb.version>
<ejb:ejb.home.interface>org.ow2.petals.watersupply.localisation.application.LocalisationFinderBusinessServiceRemoteHome</ejb:ejb.home.interface>
<ejb:marshalling.engine>jaxb</ejb:marshalling.engine>
<ejb:security.name />
<ejb:security.principal />
<ejb:security.credencials />
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}
*Configuration of a Service Unit to expose an EJB onto Petals ESB :*
{table-plus}
|| Parameter || Description || Default || Required ||
| ejb.jndi.name | The JNDI name of the targeted EJB | \- | Yes |
| java.naming.factory.initial | The name of the targeted JNDI Initial Context Factory | \- | Yes |
| java.naming.provider.url | The URL of the targeted JNDI service | \- | Yes |
| ejb.version | Implemention version of the targeted EJB.\\
Supported versions are 2.0, 2.1, 3.0 and 3.1 | \- | Yes |
| ejb.home.interface | Fully qualified name of the targeted EJB Home Interface. Used only
with ejb 2.0 and 2.1.
Fully qualified name of the targeted EJB Home Interface. Used only with ejb 2.0 and 2.1. | \- | No |
| security.name | Fully qualified name of the security module used. | \- | No |
| security.principal | Username | \- | No |
| security.credencials | Password | \- | No |
| marshalling.engine | The marshalling engine to use | jaxb | Yes |
{table-plus}
{include:0 CDK SU Provide Configuration}
{include:0 CDK Interceptor configuration for SU}
h2. Service Unit content
The service unit must contain a JAR archive including the EJB Interface (and EJB Home Interface for a 2.x EJB) and all specific Java classes used by this interface.
It is also highly recommended to provide a WSDL description of your EJB interface. This WSDL description will be used as Service Description for the JBI Endpoint linked to your EJB.
The directory structure of a SU for the BC-EJB must look like this :
{noformat}my-su-ejb.zip
+ META-INF
- jbi.xml
- my-ejb-wsdl-description.wsdl
- my-ejb.jar
- my-ejb-dependency1.jar
- my-ejb-dependency2.jar
h2. Provider restrictions
h2. Provider usage{noformat}
h1.