{section}
{column}

{warning}This version must be installed on [Petals ESB 5.4.0|petalsesb540:Petals ESB 5.4.0]+{warning}

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

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

{column}

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

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.5 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.
* *transformToMtomAttachment*: the received message is transformed with the XSL style sheet. The transformation result is attached to the response in MTOM mode.

h2. The "transform" operation

The fully qualified name of this operation is:
* Name space URI: any URI, provided it is not null (e.g. *{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.

If an error occurs during the transformation, then a fault is raised.

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<xsltFault xmlns="the name space of the invoked operation">
<message>An error message</message>
<details>A stack trace (optional)</details>
</xsltFault>
{code}

{tip}
Don't forget to enable the attachment forward ([forward-attachments|#forward-attachments]) when transforming an incoming request containing MTOM reference.
{tip}

h2. The "transformToMtomAttachment" operation

The fully qualified name of this operation is:
* Name space URI: any URI, provided it is not null (e.g. *{html}http://petals.ow2.org/components/xslt/version-2{html}*)
* Local part: *transformToMtomAttachment*

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 in MTOM mode.

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

{code:lang=xml}
<attachedTransformResponse xmlns="..." xmlns:xop="http://www.w3.org/2004/08/xop/include">
<fileContent>
<xop:include href="cid:attachmentName" />
</fileContent>
<attachedTransformResponse>
{code}

... where _attachmentName_ is the name of the attachment (as specified in the service-unit, or a default value otherwise).

If an error occurs during the transformation, then a fault is raised.

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<xsltFault xmlns="the name space of the invoked operation">
<message>An error message</message>
<details>A stack trace (optional)</details>
</xsltFault>
{code}

h2. XSL parameters

XSL style sheets supports the definition of parameters.
These parameters can be passed dynamically when executing it.

You can find additional information about it on these web sites:
* [http://www.w3schools.com/XSL/el_param.asp]
* [http://projects.ischool.washington.edu/tabrooks/545/ContentManagement/PassingParameters.htm]
* [http://www.xml.com/pub/a/2001/02/07/trxml9.html]

The Petals XSLT component allows you to set XSL parameters in two different ways:
* The first one is a static definition in the jbi.xml.
** It allows you to reuse a same XSL style sheet in several services.
** Take a look at the [jbi.xml parameters|#jbi-parameters] for more information.

* The second way is by setting them at runtime, in the message properties.
** Please, understand that this is not the message payload that defines the parameter values.
** It is the properties of the incoming Petals service (called an exchange). For more details, see Exchange#setInMessageProperty( String, Object ).

Static parameter values may be overriden by dynamic ones.
But only if the static values were defines as _overridable_.
Trying to override a parameter value that is not overridable will result in a fault.

{info}Remember, XSL parameters are declared with a *param* element in the XSL style-sheet.
A XSL parameter can be global (declared as a root element) or local (declared inside a template).
The value of a XSL parameter can be retrieved with *$parameter_name* or *\{$parameter_name\}*, depending on the parameter usage.{info}

h2. XSLT transformer processor

The Petals XSLT component enables you to choose the XSLT processor.

By default, Xalan 2.7.0 (shipped with Java 7) is used as the default XSLT engine. It is possible to select another XSLT processor for a specific SU than the default one by:
* installing a shared library containing the XSLT processor to use,
* setting this shared library into the Petals XSLT component,
* *AND* [the XSL transformer factory classname parameter|#xslt-engine-factory-class-name] in the jbi.xml of the SU.

{tip}
To set the shared library to use into the Petals XSLT component, use the [Petals maven plugin|Maven Petals Plug-in 2.1.4+].
{tip}

h2. XSLT efficiency

A pool of XSL transformers is created for each SU at its start in order to obtain better performance. [Two parameters|Petals-SE-XSLT 2.5.x-2.6.x#xslt-engine-pool-size] enable you to set the number of XSL transformers to create at the start of the SU and the maximum number of transformers to instantiate. If all the XSL transformers are used (because of receiving a lot of requests concurrently on the service), the request blocks until a transformer is released.

h2. WSDL definitions

It is recommended to define a WSDL definition which describes the *transform* and "transformToMtomAttachment" operations.

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.

The input message for the *transformToMtomAttachment* operation is 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). The WSDL message should reference a XML element of the same type than the input message of the *transform* operation.
And the output message should describe the MTOM structure that was documented above. In this structure, _fileContent_ is a base64Binary element and the _xop:include_ element does not appear.

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. Service Unit Configuration

All needed information must be defined in the service-unit JBI descriptor. This JBI descriptor is configured through parameters divided in following groups:
* *JBI parameters* that defines the service provider identification,
* *CDK parameters* that are parameters driving the service provider implementation at CDK layer,
* *CDK interceptor parameters* that are parameters driving interceptors at CDK layer,

{include:0 CDK SU Provide Configuration 5.9.0}

h3. CDK parameters driving interceptors
The following parameters drive interceptors at CDK layer.

{include:0 CDK SU Interceptor configuration 5.9.0}

{anchor:jbi-parameters}
h3. Dedicated configuration
The following parameters correspond to the component specific configuration of the service provider implementation.

{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 *transformToMtomAttachment* operations is invoked | {center}\-{center} | {center}No{center} |
| xsl-parameters | A list of *xsl-parameter* elements | {center}\-{center} | {center}No{center} |
| xslt-engine-factory-class-name {anchor:xslt-engine-factory-class-name} | The XSL transformer factory classname | {center}\-{center} | {center}No{center} |
| xslt-engine-pool-size-min {anchor:xslt-engine-pool-size}| The number of XSL transformers to create at the start of the SU | {center}\-{center} | {center}No{center} |
| xslt-engine-pool-size-max | The maximum number of XSL transformers to instantiate for the SU (at the same time). It corresponds to the maximum
number of requests treated simultaneously by the component for the SU. | {center}\-{center} | {center}No{center} |
{table-plus}

A *xsl-parameter* element has the following structure:

{code:lang=xml}
<xs:complexType name="XslParameter">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="name" type="xs:string" />
<xs:attribute name="overridable" type="xs:boolean" default="false" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
{code}

* Its value is a text.
* The *name* attribute must match the name of a XSL parameter.
* The *overridable* attribute defines whether this static value can be overriden by a dynamic value (from an incoming message).

h3. Service unit content

The service unit has to contain the following elements, packaged in the archive:
* the META-INF/jbi.xml descriptor file as described above,
* it is also highly recommended to provide a WSDL description for service provider embedded in the service-unit,
* the XSL style sheet,
* an optional JAR containing custom functions referenced in the XSL style sheet.

{code}
service-unit.zip
+ META-INF
- jbi.xml (as defined above)
- service.wsdl (recommended)
- xsl-stylesheet.xsl
- customFunctions.jar (optional)
{code}

h3. Example

An example of a Service Unit descriptor to provide an XSLT service:
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<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">

<jbi:services binding-component="false">

<jbi:provides
interface-name="generatedNs:XsltInterface"
service-name="generatedNs:Test"
endpoint-name="TestEndpoint">

<!-- 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>transformation.xsl</xslt:stylesheet>

<!-- XSL parameters -->
<generatedNs:xsl-parameters>
<generatedNs:xsl-parameter name="street" overridable="true">
17, rue du Parc
</generatedNs:xsl-parameter>
<generatedNs:xsl-parameter name="city" overridable="false">
Grenoble
</generatedNs:xsl-parameter>
</generatedNs:xsl-parameters>
</jbi:provides>
</jbi:services>
</jbi:jbi>
{code}

h1. Configuring the component

The component can be configured through the parameters of its JBI descriptor file. These parameters are divided in following groups:
* *JBI parameters* that have not to be changed otherwise the component will not work,
* *CDK parameters* that are parameters driving the processing of the CDK layer,
* *Dedicated parameters* that are parameters specific to this component.

h2. CDK parameters
The component configuration includes the configuration of the CDK. The following parameters correspond to the CDK configuration.

{include:0 CDK Component Configuration Table 5.9.0}

h2. Interception configuration
{include:0 CDK Component Interceptor configuration 5.9.0}

h2. Dedicated configuration

No dedicated configuration parameter is available.

h1. Business monitoring

h2. MONIT traces

{include:0 CDK SE Business Monitoring Traces 5.9.0}

h2. Flow tracing activation

{include:0 CDK SE Business Monitoring Flow Tracing Activation 5.9.0}

h1. Monitoring the component

h2. Using metrics

Several probes providing metrics are included in the component, and are available through the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.

h3. Common metrics

{include:0 CDK Component Monitoring Metrics 5.9.0}

h3. Dedicated metrics

No dedicated metric is available.

h2. Receiving alerts

Several alerts are notified by the component through notification of the JMX MBean '{{org.ow2.petals:type=custom,name=monitoring_*<component-id>*}}', where {{*<component-id>*}} is the unique JBI identifier of the component.

{tip}To integrate these alerts with Nagios, see [petalsesbsnapshot:Receiving Petals ESB defects in Nagios].{tip}

h3. Common alerts

{include:0 CDK Component Monitoring Alerts 5.9.0}

h3. Dedicated alerts

No dedicated alert is available.