View Source

{section}
{column}
{multi-excerpt-include:Petals-SE-XSLT|name=features|nopanel=true}
{column}

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

{multi-excerpt-include:Petals-SE-XSLT|name=recommended-usage|nopanel=true}

h1. Creating a XSL Transformation service (Provides modes)

Each XSLT service runs on the Petals XSLT component.
The Petals XSLT component has native operations to invoke. These operations are inherited by the XSLT services.
A XSLT service cannot add additional operations. It only has the ones of the XSLT component.

\\
The version 2.3 of the Petals XSLT component exposes two operations.
* *transform*: the received message is transformed with the XSL style sheet. The transformation result is returned as the response payload.
* *transformToAttachment*: the received message is transformed with the XSL style sheet. The transformation result is attached to the response.


h2. The "transform" operation

The fully qualified name of this operation is:
* Name space URI: *{html}http://petals.ow2.org/components/xslt/version-2{html}\*
* Local part: *transform*

\\
This operation only supports the *InOut* message exchange pattern (MEP).
When invoking this operation, you must call it using its fully qualified name.
It must also be the operation name in the WSDL of any XSLT service.

\\
Here is the execution flow for this operation:
# The received message is transformed with the XSL style sheet.
# The transformation result is returned as the response payload.

\\
The result of the transformation depends on the XSL style sheet.


h2. The "transformToAttachment" operation

The fully qualified name of this operation is:
* Name space URI: *{html}http://petals.ow2.org/components/xslt/version-2{html}\*
* Local part: *transformToAttachment*

\\
This operation only supports the *InOut* message exchange pattern (MEP).
When invoking this operation, you must call it using its fully qualified name.
This operation cannot be described in a WSDL, because of the result it returns.

\\
Here is the execution flow for this operation:
# The received message is transformed with the XSL style sheet.
# The transformation result is attached to the response.

\\
The attachment is not sent in MTOM mode.
The result of the transformation has always the same shape.

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

... where _myOutputAttachmentName_ is the name of the attachment (as specified in the service-unit, or a default value otherwise).
This operation will most likely be depreciated in future versions.


h2. WSDL definitions

Configurations (service-units) for the XSLT component do not have, in general, a WSDL definition.
However, it is possible to define one. This WSDL can only describe the *transform* operation.
The *transformToAttachment* operation cannot be described in a WSDL. This last operation is rather intended for integration use cases.
This is also why this operation will probably be marked as depreciated in the next version.

\\
The input and output messages for the *transform* operation are related to the XSL style sheet.
In fact, the input message should be the output message of the previous chained service (the one whose output must be transformed).
And the output message should be the input message of the next chained service.

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

\\
{tip}
Beginning by creating a WSDL, and then continuing by the XSL style sheet appears as the best practice to have.
{tip}


h2. JBI descriptor

The Service-Unit descriptor file ( jbi.xml ) looks like this:
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<!--
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.

\\
{include:0 CDK SU Provide Configuration}
\\
{center}{*}Configuration of a Service Unit to provide a service (XSLT)*{center}
{table-plus}


|| Parameter || Description || Default || Required ||
| stylesheet | The relative file path of the XSL style sheet in the service-unit | {center}\-{center} | {center}Yes{center} |
| output-attachment-name | The attachment name to use when the operation *transformToAttachment* is invoked | {center}\-{center} | {center}No{center} |
{table-plus}

{include:0 CDK SU Interceptor configuration}

h2. Service-Unit content

The service unit must contain the XSL style sheet.
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
+ customFunctions.jar (optional)
{noformat}


h1. Configuring the component

The component can be configured through its JBI descriptor file, as shown below.
{code:lang=xml}<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<jbi
version="1.0"
xmlns='http://java.sun.com/xml/ns/jbi'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5">

<component type="service-engine">
<identification>
<name>petals-se-xslt</name>
<description>A Xslt Service Engine</description>
</identification>

<component-class-name description="Xslt Component class">org.ow2.petals.se.xslt.XsltComponent</component-class-name>
<component-class-path><path-element/></component-class-path>
<bootstrap-class-name>org.ow2.petals.component.framework.DefaultBootstrap</bootstrap-class-name>
<bootstrap-class-path><path-element/></bootstrap-class-path>

<petalsCDK:acceptor-pool-size>3</petalsCDK:acceptor-pool-size>
<petalsCDK:processor-pool-size>10</petalsCDK:processor-pool-size>
<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 2.0}
{include:0 CDK Parameter scope}
{include:0 CDK Component Interceptor configuration}
\\
This component does not have any specific configuration parameter.