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 component in provides mode. Level: Advanced Estimated time: 10 minutes, without counting the XSL edition time Expected skills: -

Table of contents Summary Creating the Service-Unit project Getting started Identifying the service Defining the project name Specifying the XSLT parameters Specifying the CDK parameters Checking the result Updating, packaging and deploying Further edition and packaging Editing the XSL style sheet Updating the WSDL definition Packaging the project Deployment

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 Miscellaneaous.
In the Petals Component list, select XSLT   // petals-se-xslt.
In the Component Usage list, select Provide or Import a Service in Petals ESB.
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). 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. Not having a WSDL definition is a bad practice in SOA. But it is acceptable for integration projects (e.g. combined with Enterprise Integration Patterns).

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.