{section}
{column}

h1. Features

The XSLT Service-Engine allows to transform Petals messages using XSL style sheets.

\\
Each configuration of this component embeds an XSL style sheet.
When such a configuration (i.e. service, i.e. service-unit) is called, it transforms the received message into another one.
The XML payload of the input message is transformed using the XSL style sheet.

{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}

First, you want to call the operation *lookup* of a service "*White Pages*".
This operation takes the first name and the family name of a person, and returns a list of phone numbers.
Each phone number is given as a string.

Its prototype looks like

{code:lang=javascript}
lookup( String firstName, String familyName ) --> String[] phoneNumbers
{code}

Do not forget this prototype would be in fact described in the WSDL interface of the service (under an XML shape).

\\
Then, you want to call a service that finds a geographical area (e.g. a city) from a phone prefix.
It is the operation *resolve* from a service "*PrefixToAreaLocalizer*".
From a phone prefix, it returns a geographical area.

Its prototype looks like

{code:lang=javascript}
resolve( int phonePrefix ) --> String areaName
{code}

Once again, this prototype is described in the WSDL interface of this second service.

\\
To chain these calls, you have to transform the output of the operation *lookup* to match the input of the operation *resolve*.
Indeed, you cannot directly execute

{code:lang=java}
resolve( lookup( "Pierre", "Paul"));
{code}

\\
What you will do in your XSL style sheet is extracting the phone prefix from a phone number.
The list go-through will most likely not be made in the XSLT transformation.

\\
There is no more simple way to make the transformation.
In Petals, as well as in most of SOA-related technologies, messages are XML messages.
And for every service, the operations, with their in and out parameters, are described in their WSDL interface.
So, the output message of the *resolve* operation is an XML (SOAP) message, and the input message of *resolve* operation is an XML message too.
These XML messages must match the WSDL descriptions of these services.

\\
Obviously, this example is extremely simple.
But the usage remains the same, even with complex XML structures.


h2. XSLT and chaining services

Following our previous example, it appears that chaining and transforming service calls implies using a chaining service (some could say an orchestration service).
This chaining service would do the following calls:

# Message from the chaining service to a first service.
# Response from the first service to the chaining service (we assume the first service works in InOut message exchange pattern).
# Message from the chaining service to the XSLT service.
# Response from the XSLT service to the chaining service (the MEP is InOut, always).
# Message from the chaining service to a second service. The transformed message is sent to it.
# Optional response, depending on the MEP for the second service.

\\
This chaining service can be implemented by a POJO (a Java service that runs in Petals) or an Enterprise Integration Pattern (EIP).
It could also be implemented by a BPEL process, but in fact, that would not be a great idea.
BPEL supports the extraction of data from XML messages during the orchestration. When you have a BPEL process, you do not need XSLT. You can use XPath expressions and functions directly in the BPEL. Besides, working with BPEL would require the XSLT configuration to have a WSDL interface while they do not always have one.


h2. Limitations

Configurations for this component cannot be used as a proxy to call other services.
Neither to transform attachments, nor to intercept messages on the fly.
Interceptors would better fit this kind of use case.

\\
The transformed content is always the payload from the input message.
And a chaining service is always required.

JBI descriptor for the Petals' "petals-se-xslt" component (XSLT).
Originally created for the version 2.3 of the component.
-->
<jbi:jbi version="1.0"
xmlns:generatedNs="http://petals.ow2.org/components/xslt/version-2"
xmlns:jbi="http://java.sun.com/xml/ns/jbi"
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xslt="http://petals.ow2.org/components/xslt/version-2">

<!-- Import a Service into Petals or Expose a Petals Service => use a BC. -->
<jbi:services binding-component="false">

<!-- Import a Service into Petals => provides a Service. -->
<jbi:provides
interface-name="generatedNs:XsltInterface"
service-name="generatedNs:PersonLocalizer"
endpoint-name="PersonLocalizerEndpoint">

<!-- CDK specific elements -->
<petalsCDK:timeout>30000</petalsCDK:timeout>
<petalsCDK:validate-wsdl>true</petalsCDK:validate-wsdl>
<petalsCDK:forward-security-subject>false</petalsCDK:forward-security-subject>
<petalsCDK:forward-message-properties>false</petalsCDK:forward-message-properties>
<petalsCDK:forward-attachments>false</petalsCDK:forward-attachments>
<petalsCDK:wsdl>XsltService.wsdl</petalsCDK:wsdl>

<!-- Component specific elements -->
<xslt:stylesheet>fromTo.xsl</xslt:stylesheet>

<!-- The following parameter is optional -->
<xslt:output-attachment-name>TransformedMessage</xslt:output-attachment-name>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}

\\
A JBI descriptor for an XSLT service-unit can only define one _provides_ block.

| stylesheet | The relative file path of the XSL style sheet in the service-unit \\ | \- | Yes |
| output-attachment-name | The attachment name to use when the operation *transformToAttachment* is invoked \\ | \- | No |

\\
{include:0 CDK SU Provide Configuration}
\\
{include:0 CDK Interceptor configuration for SU}

It is also highly recommended to provide a WSDL description for this service.
This WSDL is not mandatory, but not providing it will prevent your service from interacting with other Petals services and components.

The archive may also embed a JAR containing the custom functions referenced in the XSL style sheet, if any.

\\
The directory structure of a SU for the Petals-SE-XSLT looks like this:

{noformat}
su-xslt-TransformationName-provide.zip
+ META-INF
- jbi.xml
+ XsltService.wsdl (recommended)
+ <XSL style sheet>.xsl