{section}
{column}

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

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

{column}

{column:width=40%}
{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 service-unit

A service-unit associated to a service 'Facade' contains:
* the WSDL of your service, the one implemented by the service 'Facade',
* WSDL annotations defining:
** the transformations to apply,
** the operation of the 3PP service provider to invoke,
* the 3PP service provider to invoke, defined in the service-unit JBI descriptor as consumer section.

h2. Creating the service contract

Write your WSDL according to your needs. No requirement about the WSDL is expected.

A best practice is to explode your WSDL in two parts:
* an abstract part containing data definition (XSD) and the service interface (port type),
* a concrete part containing the binding of the port type, and the service definition.

h2. Annotating the WSDL

Annotations take place in each operation of the binding definition:
{code:xml}
<binding name="FactureServicePortBinding" type="tns:FactureService">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />
<operation name="stocker">
<soap:operation soapAction="" />
<mapping:service-provider-operation>ged:stocker</mapping:service-provider-operation>
<mapping:input-transformation xsl="input-stocker.xsl" />
<mapping:output-transformation xsl="output-stocker.xsl">
<mapping:should-return-fault as-xpath-expr="true">false()</mapping:should-return-fault>
</mapping:output-transformation>
<input>
<soap:body use="literal" />
</input>
<output>
<soap:body use="literal" />
</output>
</operation>
</binding>
{code}

All annotations are member of the namespace "{{http://petals.ow2.org/se/mapping/annotations/1.0}}":
* {{service-provider-operation}} defines the qualified name of the 3PP service provider operation to invoke when the current operation is invoked,
* {{input-transformation}} defines the transformation to apply on incoming requests on the current operation,
* {{output-transformation}} defines the transformation to apply on response for the current operation,

h3. Defining input transformations

The input transformation is defined by the annotation '{{input-transformation}}'.

Now, only XSL transformations are available.

h4. Defining an XSL input transformation

To define an input transformation as an XSL transformation, just define the XSL style-sheet to use by the attribute '{{xsl}}' of the annotation '{{input-transformation}}'. The XSL style-sheet is provided as a file located in the root directory of the service unit.

{code:xml}
<binding name="FactureServicePortBinding" type="tns:FactureService">
...
<operation name="stocker">
...
<mapping:input-transformation xsl="input-stocker.xsl" />
...
</operation>
</binding>
{code}

A property defined at component level (through the component configuration parameter '{{properties-file}}' can be accessed into the XSL through a global XSL parameter defined by the qualified name: '{{<property-name>}}' of namespace '{{http://petals.ow2.org/se/mapping/xsl/param/1.0}}'.

{tip}For a unit test purpose, an extension of JUnit is available to test your XSL. See chapter "[Unit testing|#Unit_Testing]".{tip}

h3. Defining output transformations

The output transformation is defined by the annotation '{{output-transformation}}'.

The result of the transformation can be returned to the service consumer as a normal response or as a fault according to the result of the expression defined by the sub-annotation '{{should-return-fault}}'. If the expression returns '{{true}}', a fault will be returned to the service consumer, otherwise a normal response will be returned:
{code:xml}
<binding name="FactureServicePortBinding" type="tns:FactureService">
...
<operation name="stocker">
...
<mapping:output-transformation xsl="output-stocker.xsl">
<mapping:should-return-fault as-xpath-expr="true">false()</mapping:should-return-fault>
</mapping:output-transformation>
...
</operation>
</binding>
{code}

Now, only XSL transformations and XPath expression are available.

h4. Defining an XSL output transformation

To define an output transformation as an XSL transformation, just define the XSL style-sheet to use by the attribute '{{xsl}}' of the annotation '{{output-transformation}}'. The XSL style-sheet is provided as a file located in the root directory of the service unit.

{code:xml}
<binding name="FactureServicePortBinding" type="tns:FactureService">
...
<operation name="stocker">
...
<mapping:output-transformation xsl="output-stocker.xsl">
...
</mapping:output-transformation>
...
</operation>
</binding>
{code}

The incoming request can be accessed into the XSL through a global XSL parameter defined by the qualified name: '{{incoming-request}}' of namespace '{{http://petals.ow2.org/se/mapping/xsl/param/output/1.0}}'.

A property defined at component level (through the component configuration parameter '{{properties-file}}' can be accessed into the XSL through a global XSL parameter defined by the qualified name: '{{<property-name>}}' of namespace '{{http://petals.ow2.org/se/mapping/xsl/param/1.0}}'.

{tip}For a unit test purpose, an extension of JUnit is available to test your XSL. See chapter "[Unit testing|#Unit_Testing]".{tip}

h4. Selecting response nature through XPath

The expression to select the response nature to return (fault or normal response) can be expressed as an XPath expression using the attribute '{{as-xpath-expr}}' set to '{{true}}', and giving the XPath expression as value of the annotation '{{should-return-fault}}':
{code}
<mapping:output-transformation xsl="output-stocker.xsl">
<mapping:should-return-fault as-xpath-expr="true">false()</mapping:should-return-fault>
</mapping:output-transformation>
{code}

{tip}For a unit test purpose, an extension of JUnit is available to verify your XPath expression syntax when checking your WSDL. See chapter "[Unit testing|#Unit_Testing]".{tip}

h2. Defining the 3PP service provider

The 3PP service provider is defined in the service unit JBI descriptor as a service consumer:
{code}
<!-- The service invoked -->
<jbi:consumes interface-name="ged:GedService" service-name="ged:GedService">
<petalsCDK:timeout>15000</petalsCDK:timeout>
<petalsCDK:mep>InOut</petalsCDK:mep>
</jbi:consumes>
{code}

Supported parameters of the section '{{consumes}}' are:
* {{timeout}}, to set on the message exchange used for the service provider invocation,
* {{mep}}, is not used because we reuse the one of the incoming exchange,
* {{operation}}, is not used. As we can have a service 'Facade' providing several operations, it was needed to define the annotation '{{service-provider-operation}}'. A warning will appear in log traces if this field is set.
* {{exchange-properties}}, the properties to set on the message exchange used to invoke the service provider,
* {{message-properties}}, the properties to set on the message of message exchange used to invoke the service provider.

{include:0 CDK SU Provide Configuration 5.7.0}

{center}{*}Configuration of a Mapping Service Unit*{center}
No specific configuration exists

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.

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.6.0}
{include:0 CDK Parameter scope}
{include:0 CDK Component Interceptor configuration}

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.6.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.6.0}

h3. Dedicated alerts

No dedicated alert is available.

{anchor:Unit_Testing}
h1. Unit testing

The unit testing can occur at several levels in your Mapping service unit:
* to check the annotation compliance of the WSDL with the attendees of the component,
* to unit test your XSL transformations.

A dedicated framework is available as an extension of JUnit providing facilities:
* to validate your WSDL:
** in a WSDL point of view,
** checking the compliance of the WSDL with the attendees of the component,
** checking syntax of the XPath expressions,
* to verify easily the XSL style-sheets.

This dedicated framework is provided by the Maven artifact {{org.ow2.petals:petals-se-mapping-junit}}:
{code:xml}
<project>
...
<dependencies>
...
<dependency>
<groupId>org.ow2.petals</groupId>
<artifactId>petals-se-mapping-junit</artifactId>
<version>1.0.0</version>
<scope>test</scope>
</dependency>
...
</dependencies>
...
</project>

The unit test framework contains an assertion '{{assertWsdlCompliance}}' to verify easily the compliance of your WSDL with the attendees of the mode 'service':
{code:lang=java}
import static org.ow2.petals.se.mapping.junit.Assert.assertWsdlCompliance;

import javax.xml.namespace.QName;
import org.junit.Test;

public class WsdlComplianceTest {

private static final String TARGET_NAMESPACE = "http://facture.mapping.samples.petals.ow2.org/";

@Test
public void validate() throws Exception {
assertWsdlCompliance(
new QName[] { new QName(TARGET_NAMESPACE, "stocker"), new QName(TARGET_NAMESPACE, "consulter") });
}

}
{code}

See the Javadoc for more details on parameters.

h2. Unit-testing your XSLs

The unit test framework contains an assertion '{{assertXslTransformation}}' to verify easily the result of your XSL transformations:
{code:lang=java}
import static org.ow2.petals.se.mapping.junit.Assert.assertXslTransformation;
...
import org.junit.Test;

public class XslTest {

private static final String XML_DIR = "xml-to-transform/";
private static final String XML_RESULT_DIR = "xml-result/";
private static final String INPUT_CONSULTER_DIR = "input-consulter/";
private static final String INPUT_CONSULTER_XML_DIR = XML_DIR + INPUT_CONSULTER_DIR;
private static final String INPUT_CONSULTER_RESULT_DIR = XML_RESULT_DIR + INPUT_CONSULTER_DIR;
private static final String XSL_INPUT_CONSULTER = "input-consulter.xsl";

@Test
public void inputConsulter_Nominal() throws IOException, TransformerException, SAXException {
assertXslTransformation(INPUT_CONSULTER_RESULT_DIR + "nominal.xml", INPUT_CONSULTER_XML_DIR + "nominal.xml",
XSL_INPUT_CONSULTER);
}
}
{code}

See the Javadoc for more details on parameters.