{section}
{column}

h1. Features

Additional information about XSLT can be found at [http://www.w3.org/TR/xslt].


h1. Recommended usage

The XSLT component should be used when chaining calls to services whose output and input do not match.
It can also be used to expose XSL transformations as a service, provided that the content to transform is passed in the message payload, and not as attachment.


h2. An example to understand the problematic

Let's suppose you want to know where lives a person.
You have two services that can help you in this task.

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.

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.

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.

h2. Using XSLT means using an chaining service

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.

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


h1. XSLT configurations and WSDL interfaces

Configurations (service-units) for the XSLT component do not have, in general, a WSDL interface.

When calling *transform*, the transformed message is returned as the message payload.
When calling *transformToAttachment*, the transformed message is attached to the response.
In this second case, the payload is

{code:lang=xml}
<attached-files>
<file-name>myOutputAttachmentName</file-name>
<attached-files>
{code}

\\
The input and output messages for these operations is related to the XSL style sheet.
In fact, the input message should be the output message of the previous service (the one whose output must be transformed).

And the output message depends on the operation.
For the *transform* operation, it should be the input message of the next service to be called.
For the other operation, it is almost the same every time, since it is an attachment.
Obviously, each time it is written _service_, it means *service operation*. Because you cannot chain calls to services, but only chain calls to service operations.

{warning}
The XSLT component supports only the *InOut* message exchange pattern.
{warning}

\\
As said at the beginning of this section, WSDL are not mandatory though.
Typically, integration use cases do not require one. But not having one is bad practice in SOA. Your XSLT service is then not reusable, and no one else will ever use it unless you give him the XSL style sheet to determine the expected input and output.

\\
Thus, beginning by creating a WSDL, and then continuing by the XSL style sheet appears as the best practice to have.


h1. Component configuration

The component can be configured through its JBI descriptor file, as shown below.

<name>petals-se-xslt</name>

<petalsCDK:ignored-status>DONE_AND_ERROR_IGNORED</petalsCDK:ignored-status>
<petalsCDK:notifications>false</petalsCDK:notifications>
<petalsCDK:jbi-listener-class-name>org.ow2.petals.se.xslt.listener.JBIListener</petalsCDK:jbi-listener-class-name>
</component>
</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 does not have any specific configuration parameter.

\\
{warning}
The Petals-SE-XSLT 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 descriptor

xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"

<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>

</jbi:jbi>
{code}

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

\\
*Configuration of a Service Unit to expose an XSLT-transformation service into Petals ESB :*

|| Parameter || Description || Default || Required ||
| 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}


h2. Service Unit content

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

{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}