E-mail
SummaryThis tutorial explains how you can create a XSL Transformation service.
|
Creating the Service-Unit project
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.
A wizard opens up, showing three drop-down lists.
In the Use Case list, select Use a Petals technical service.
In the Petals Component list, select XSLT // petals-se-xslt.
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:
Click Next.
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.
You can simply complete the service and end-point names.
 | 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. |
| 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. |
Once the fields have been filled-in, click Next.
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 service-units have a naming convention. For a service-unit which provides a service, the convention is su-<Protocol or Technology>-<Service name>-provide |
Then, click Next.
Specifying the XSLT parameters
This page defines information which are specific to the Petals XSLT component.
In fact, only 3 elements are required:
- A XSL style sheet: you can either import an existing one or create a new one.
- Decide whether a default WSDL definition should be created or not (SOA vs. Integration usage).
- The output attachment name: with this component, the transformation result may be attached to the response, depending on the invoked operation.
This parameter is optional.
You can get more information in the documentation of the Petals-SE-XSLT component.
Click Next.
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 component.
Click Finish to complete the wizard.
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.
Updating, packaging and deploying
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.
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).
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.
<?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>
 | The studio embeds a builder that validates XSL style sheets. This builder prevents errors from happening at deployment time in Petals ESB. |
Updating the WSDL definition
The WSDL that is generated by this wizard is a default one.
| 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. |
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.
| 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. |
| You can only modify the XML elements and the XML types in the generated WSDL. |
 | 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).
Not having a WSDL definition is a bad practice in SOA. |
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.
| 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. |
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, you can package it as any Service-Unit project.
It results in the creation of a Service Assembly for the Petals-SE-XSLT component. Its location depends on your export choices.
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.