{section}
{column}

h1. Summary

This tutorial explains how you can create a XSL Transformation service.
Concretely, such a service transforms messages with a XSL style sheet.

\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-SE-XSLT|petalscomponents:Petals-SE-XSLT] component in *provides* mode.

{info}
*Level:* Advanced
*Estimated time:* 10 minutes, without counting the XSL edition time
*Expected skills:* \-
{info}
{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{column}
{section}


h1. Creating the Service-Unit project

h2. Getting started

Start Petals Studio.
In the menu, select *File > New > Service-Unit Project*.
If you do not see it, go into *File > New > Other...* Then, select *Service-Unit Project* under the *Petals* category.

In the *Component Version* list, select the version of the Petals-SE-XSLT that you are using in Petals.

\\
In the scope of this tutorial, we are going to work with the version 2.4 of the XSLT component.
Which gives us:

!petals-studio-tuto-provides-xslt-1.jpg!

\\
Click *Next*.


h2. Identifying the service

The current page requires you to fill-in the base information to put in the JBI descriptor (*META-INF/jbi.xml*).
In particular, it defines the interface, service and end-point names of the service that is imported.
The tooling for the Petals XSLT component provides a generic WSDL definition, and thus defines *fixed values*.
This WSDL definition is only a basis and may be updated then.

!petals-studio-tuto-provides-xslt-2.jpg!

\\
You can simply complete the service and end-point names.

!petals-studio-tuto-provides-xslt-3.jpg!

\\
{note}
The values for the interface, service and end-point names must match the WSDL interface.
That is to say there must be a service with this name, implementing the so-called interface at this end-point.
The WSDL which is generated on wizard completion respects this rule.
{note}

{note}
The auto-generation of the end-point means the service end-point is generated at deployment time.
By deploying a such service-unit on _n_ Petals nodes, you would have _n_ times the same service, implementing the same interface, but available at _n_ different locations.
{note}

\\
Once the fields have been filled-in, click *Next*.


h2. Defining the project name

This page defines the name and the location of the project that will be created.
Indeed, this wizard will result in the creation of a project containing all the required elements for a XSLT service-unit.

\\
Enter a project name for your project.
If you do not want your project to be created in the default workspace, uncheck *Use default location*.
Then click *Browse...* and select the location where the project will be created.

!petals-studio-tuto-provides-xslt-4.jpg!

\\
{note}
Petals service-units have a naming convention.
For a service-unit which provides a service, the convention is *su\-*_<Protocol or Technology>_*\-*_<Service name>_*\-provide*
{note}

\\
Then, click *Next*.


h2. Specifying the XSLT parameters

\\ !petals-studio-tuto-provides-xslt-5.jpg!

\\
You can get more information in the documentation of the [Petals-SE-XSLT|petalscomponents:Petals-SE-XSLT] component.
Click *Next*.


h2. Specifying the CDK parameters

The CDK is the Petals framework to develop JBI components.
The Petals-SE-XSLT component was developed with this framework.

This page requires information related to the CDK.
By default, you have nothing to do here.
The meaning of all the CDK parameters for XSLT can be found in the documentation of the [Petals-SE-XSLT|petalscomponents:Petals-SE-XSLT] component.

\\ !petals-studio-tuto-provides-xslt-6.jpg!

\\
Click *Finish* to complete the wizard.


h2. Checking the result

When the wizard has completed, a new project has been created and is visible in your workspace.

It contains a jbi.xml file, located under *src/main/jbi*.
This hierarchy allows you to work with Apache Maven then (a pom.xml was also created at the root of the project).
In the same directory, you can see the WSDL definition that was generated for this version of the XSLT component.
Eventually, there is a XSL style sheet, which is either the one that was imported, or a default one to complete.

\\ !petals-studio-tuto-provides-xslt-7.jpg!


h1. Updating, packaging and deploying

h2. Further edition and packaging

After completion, the newly created jbi.xml file has been open in the Service-Unit editor.
This jbi.xml is complete and does not need to be updated. The edition mainly concerns the XSL style sheet and the WSDL definition.


h3. Editing the XSL style sheet

Petals Studio embeds the XSL editor from the Eclipse WTP project.
You can use it to edit the XSL style sheet, using its built-in validation and content assistance (available by pressing *Ctrl + space*).

!petals-studio-tuto-provides-xslt-8.jpg!

\\
The following XSL style sheet is the one generated by the wizard.
It replaces the root element "transformRequest" of a XML document by a "transformResponse" element.
This XSL style sheet and the element names match the WSDL content.

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<!-- Replace the root "transformRequest" elements and copy their children and attributes. -->
<!-- This XSL style sheet is synchronized with the generated WSDL! -->
<xsl:template match="*[count(parent::*) = 0 and local-name() = 'transformRequest']">
<xsl:element name="transformResponse" namespace="{namespace-uri()}">
<xsl:copy-of select="@* | namespace::*" />
<xsl:copy-of select="./*" />
</xsl:element>
</xsl:template>

</xsl:stylesheet>
{code}

\\
{tip}
The studio embeds a builder that validates XSL style sheets.
This builder prevents errors from happening at deployment time in Petals ESB.
{tip}


h3. Updating the WSDL definition

The WSDL that is generated by this wizard is a default one.

\\
{tip}
If you imported an existing style sheet, you imperatively have to edit the WSDL definition.
If you generated a default XSL style sheet and modified it, you imperatively have to edit the WSDL definition.
{tip}

\\
*What can you modify in the generated WSDL?*.

* You can modify the *input* and *output* messages of the *transform* operation.
* You can modify the *input* message of the *transformToMtomAttachment* operation.
* You can modify the *XML types*.

And that's it. Do not change the rest of the WSDL.

\\
The generated WSDL is a _Document/Literal_ WSDL.
It means there must be a unique XML element for each WSDL message.

As an example, the *transformToMtomAttachment* operation is supposed to have the same input than the *transform* operation.
However, their input message are associated with different elements.

The input message of the *transform* operation is associated with the *transformRequest* element.
The input message of the *transformToMtomAttachment* operation is associated with the *attachedTransformRequest* element.
But these two XML elements have the same XML type.

\\
If the input element is *transformRequest*, it means the messages this service expects must have a *transformRequest* element as the root element.
If the output element is *transformResponse*, it means the responses must have a *transformResponse* element as the root element.
This relation must be ported in the XSL style sheet: *transformRequest* elements must be transformed in *transformResponse* elements.

\\
{tip}
The WSDL shape sets constraints on your XSL style sheet.
The input elements of all the operations must have the same type.
And the XSL style sheet must transform the input element of the *transform* operation in its output element.
{tip}

{tip}
You can only modify the XML elements and the XML types in the generated WSDL.
{tip}

\\
{warning}
If having a WSDL is a too constraining for your XSL style sheet, you can delete the generated one and set the WSDL field to _null_ in the jbi.xml.
This value can be set to _null_ by setting the attribute *xsi:nil="true"* (the xsi prefix should be already defined).

\\
*Note that not providing a WSDL makes your service-unit a Petals end-point, but not a real Petals service.*
It will be registered in the Petals registry, but creating a service consumer for it will be almost impossible.
Service consumers are generally created from WSDL definitions.

\\
Eventually, if you change any XML type, you have to update the the interface name.
This can be done either by changing the name space URI of the WSDL, or by changing the local part, or by changing both.

{tip}
When you customize XML types in a generated XSLT WSDL, change the (interface) port type name in the WSDL.
Then update your jbi.xml to match the WSDL's content.
{tip}

h3. Packaging the project

The project contains everything the XSLT component needs.
You can now package it before deploying it.

\\
The created project being a [Service-Unit project|Working with Service-Unit projects], you can [package it as any Service-Unit project|Working with Service-Unit projects#Export for Petals].
It results in the creation of a Service Assembly for the Petals-SE-XSLT component. Its location depends on your export choices.

h2. Deployment

The deployment of the created service assembly can be achieved with the Petals web console.
Or you can do it by dropping the service assembly in the *install* directory of your Petals installation.
This second option should only be used in development steps.

\\
First, make sure the Petals-SE-XSLT is installed in your Petals environment.
Then, install the service assembly in your Petals, using one of the two ways indicated above.

\\
There is no need to update configuration of the XSLT component to make it work.
Using the default settings is enough to make the service-unit work.