h2. servicemix-saxon

h3. Overview
The servicemix-saxon component is a standard JBI Service Engine for XSLT / XQuery. This component is based on Saxon and supports XSLT 2.0 and XPath 2.0, and XQuery 1.0.

h4. Namespace and xbean.xml
The namespace URI for the servicemix-bean JBI component is {{http://servicemix.apache.org/saxon/1.0}}.  This is an example of {{xbean.xml}} file with a namespace definition with prefix {{saxon}}.
{pygmentize:lang=xml}
    <beans xmlns:saxon="http://servicemix.apache.org/saxon  /1.0">

      <!-- add saxon:xslt, saxon:xquery or saxon:proxy definitions here -->

    </beans>
{pygmentize}

h4. Endpoint types
The servicemix-saxon component defines these endpoints:
* [{{saxon:xslt}}|#xslt]: Translates the in message content using XSLT to send back the translated content in the out message
* {{saxon:proxy}}: Acts as a proxy for an endpoint, translating the message passed to/from the endpoint using XSLT
* {{saxon:xquery}}: Use xquery to extract parts of the XML

h3. Endpoint {{saxon:xslt}} {anchor:xslt}

The XSLT endpoint can be used to apply an XSLT stylesheet to the incoming exchange and will return the transformed result as the output message.
{pygmentize:lang=xml}
<saxon:xslt service="test:xslt" endpoint="endpoint"
            resource="classpath:transform.xsl" />
{pygmentize}

h4. Endpoint properties
{include:jbi/components/_servicemix-saxon-xslt.conf}

h4. Mandatory properties
The endpoint requires one of these two properties to be specified:
|| Attribute || Type || description ||
| {{resource}} | ([Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html]) | the spring resource pointing to the XSLT stylesheet |
| {{expression}} | ([ServiceMix expression|http://incubator.apache.org/servicemix/dist/servicemix-3.0-incubating/site/servicemix-core/apidocs/org/apache/servicemix/expression/Expression.html]) | expression used to dynamically load the stylesheet |

h4. Optional properties
|| Attribute || Type || description ||
| {{wsdlResource}} |([Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html]) | if set, the wsdl will be retrieved from the given Spring resource |
| {{transformerFactory}} | (TransformerFactory, defaults to the Saxon implementation) | TraX factory to create transformers |
| {{configuration}} | ([Saxon configuration|http://www.saxonica.com/documentation/javadoc/net/sf/saxon/Configuration.html]) | Saxon configuration object |
| {{result}} | (String, defaults to {{dom}}) | Allows specifying the output result type, possible values are {{dom}}, {{bytes}}, {{string}} |
| {{copyAttachments}}, {{copyProperties}} and {{copySubject}} | (default to {{true}} |  Configure to copy message attachments, properties and security subject over to the result message |
| {{useDomSourceForXslt}} | (defaults to {{true}} | when set to {{true}}, forces the transformation of the xslt stylesheet into a DOM document before giving it to the transformer |
| {{useDomSourceForContent}} | (defaults to {{false}}) | when set to {{true}}, forces the transformation of the incoming JBI message into a DOM document before giving it to the transformer |
| {{parameters}} | a {{Map}} | containing additional parameters to give to the transformation engine |

h4. Using properties and parameters
All properties defined on the JBI exchange and input JBI message will be available for use inside the XSLT stylesheet as parameters.

In addition to those properties and the one specified in the {{parameters}} property on the endpoint, the following objects are also available:
* {{exchange}} : the JBI exchange
* {{in}} : the input JBI NormalizedMessage
* {{component}} : the XsltEndpoint instance being called

Below is an example that demonstrates how the properties of the exchange and normalized message can be accessed from inside the xslt.
{pygmentize:lang=xml}
<?xml version="1.0" encoding="windows-1253"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0"
                xmlns:class="http://saxon.sf.net/java-type"
                xmlns:me="java:javax.jbi.messaging.MessageExchange"
                xmlns:nm="java:javax.jbi.messaging.NormalizedMessage">
    <xsl:output method="xml" indent="yes" encoding="ISO-8859-1"/>
    <xsl:param name="exchange" as="class:javax.jbi.messaging.MessageExchange"/>
    <xsl:param name="in" as="class:javax.jbi.messaging.NormalizedMessage"/>

    <xsl:template match="/">
    <message>
        <!-- The value of messageId will be read from thr property MSG_ID of the "in" NormalizedMessage -->
        <messageId>
            <xsl:value-of select="nm:getProperty($in, 'MSG_ID')"/>
        </messageId>
    </message>
</xsl:stylesheet>    
{pygmentize}

All those parameters can be accessed using XSLT standard ways using {{<xsl:param/>}}.

h3. Endpoint {{saxon:proxy}}
One common use case is the need to transform a request coming from a service and send it to another service and do the same with the response.  A simple example is the need to translate the request and responses between two SOAP endpoints.  Such a use case could be implemented using two XSLT endpoints and an EIP StaticRoutingSlip.  However, there are some drawbacks, as the operation is lost in the process, and a static routing slip can not be used to process InOnly exchanges.
{pygmentize:lang=xml}
<saxon:proxy service="test:proxy" endpoint="endpoint"
             resource="classpath:transform-in.xsl"
             outResource="classpath:transform-out.xsl"
             faultResource="classpath:transform-fault.xsl">
  <saxon:target>
    <saxon:exchange-target service="test:echo" />
  </saxon:target>
</saxon:proxy>
{pygmentize}

h4. Endpoint properties
{include:jbi/components/_servicemix-saxon-proxy.conf}

h4. Mandatory properties
Depending on the MEP, you have to set one or more XSL stylesheets to be used for converting the message payloads:
|| Attribute || Type || Description ||
| {{resource}} | [Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html] | the XSLT stylesheet used to transform the input message |
| {{outResource}} | [Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html] | the XSLT stylesheet used to transform the output message |
| {{faultResource}} | [Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html] | the XSLT stylesheet used to transform the fault message |
| {{expression}} | [ServiceMix expression|http://incubator.apache.org/servicemix/dist/servicemix-3.0-incubating/site/servicemix-core/apidocs/org/apache/servicemix/expression/Expression.html] | used to dynamically load the stylesheet. If set, it will prevail against all resource, outResource and faultResource attributes |

You also have to specify the target service that should be invoked from this endpoint:
* {{target}} : ExchangeTarget that specifies the target service for the proxy endpoint

h4. Optional properties
|| Attribute || Type || Description ||
| {{wsdlResource}} | [Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html] | if set, the wsdl will be retrieved from the given ([Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html]) |
| {{transformerFactory}} (defaults to the Saxon implementation) :: TraX TransformerFactory to create transformers
| {{configuration}} | ([Saxon configuration|http://www.saxonica.com/documentation/javadoc/net/sf/saxon/Configuration.html]) | Saxon configuration object |
| {{result}} | (defaults to {{dom}}) :: Allows specifying the output result type, possible values are {{dom}}, {{bytes}}, {{string}}
| {{copyAttachments}}, {{copyProperties}} and {{copySubject}} | (default to {{true}}) |  Configure to copy message attachments, properties and security subject over to the result message |

h3. Endpoint {{saxon:xquery}}
The XQuery endpoint can be used to apply a selected XQuery to the input document.
{pygmentize:lang=xml}
<saxon:xquery service="test:xquery" endpoint="endpoint"
              resource="classpath:query.xq" />
{pygmentize}

h4. Endpoint properties
{include:jbi/components/_servicemix-saxon-xquery.conf}

h4. Mandatory properties
You need to specify one of {{query}}, {{resource}} or {{expression}}
|| Attribute || Type || Description ||
| {{query}} |  String | containing the inlined XQuery expression |
| {{resource}} | [Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html] | resource pointing to the XQuery |
| {{expression}} | [ServiceMix expression|http://incubator.apache.org/servicemix/dist/servicemix-3.0-incubating/site/servicemix-core/apidocs/org/apache/servicemix/expression/Expression.html] | expression to dynamically load the xquery |

h4. Optional properties
|| Attribute || Type || Description ||
| {{wsdlResource}} | ([Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html]) | WSDL describing the endpoint |
| {{outputProperties}} | Map | Saxon specific output properties |
| {{configuration}} | ([Saxon configuration|http://www.saxonica.com/documentation/javadoc/net/sf/saxon/Configuration.html]) | Saxon configuration object |
| {{result}} | (defaults to {{dom}}) | Allows specifying the output result type, possible values are {{dom}}, {{bytes}}, {{string}} |
| {{copyAttachments}}, {{copyProperties}} and {{copySubject}} | (default to {{true}}) |  Configure to copy message attachments, properties and security subject over to the result message |

h3. Sample configurations
h4. Dynamic stylesheet selection ({{saxon:xslt}})
This endpoint configuration will dynamically load the XSL-T resource that is specified in the {{xslt.source}} property on the {{NormalizedMessage}}
{pygmentize:lang=xml}
<saxon:xslt service="test:xslt-dynamic" endpoint="endpoint">
  <saxon:expression>
    <bean class="org.apache.servicemix.expression.PropertyExpression">
      <property name="property" value="xslt.source" />
    </bean>
  </saxon:expression>
</saxon:xslt>
{pygmentize}

h4. Using parameters in the XSL-T stylesheet ({{saxon:xslt}})
You can define a Map of parameters on the {{saxon:xslt}} endpoint.
{pygmentize:lang=xml}
<saxon:xslt service="test:xslt-params" endpoint="endpoint"
            resource="classpath:parameter-test.xsl">
  <property name="parameters">
    <map>
      <entry key="stringParam" value="cheeseyCheese"/>
      <entry key="integerParam">
        <bean class="java.lang.Integer">
          <constructor-arg index="0" value="4002"/>
        </bean>
      </entry>
    </map>
  </property>
</saxon:xslt>
{pygmentize}

In the XSL file, you can access the parameter values with {{<xsl:param/>}}.  You can also access headers on the NormalizedMessage (like e.g. {{org.apache.servicemix.file}}) with the same syntax.
{pygmentize:lang=xml}
<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>
  <xsl:param name="stringParam"/>
  <xsl:param name="integerParam"/>
  <xsl:param name="org.apache.servicemix.file" />
  ...
</xsl:stylesheet>
{pygmentize}

h4. Inlined XQuery and specific output configuration ({{saxon:xquery}})
{pygmentize:lang=xml}
<saxon:xquery service="test:xquery-inline" endpoint="endpoint">
  <saxon:query>
    for $x in /bookstore/book
    where $x/price > 30
    return $x/title
  </saxon:query>
  <saxon:outputProperties>
    <saxon:property key="{http://saxon.sf.net/}wrap-result-sequence">yes</saxon:property>
  </saxon:outputProperties>
</saxon:xquery>
{pygmentize}

h4. Dynamic XQuery selection ({{saxon:xquery}})
This endpoint configuration will dynamically load the XQuery resource that is specified in the {{xquery.source}} property on the {{NormalizedMessage}}
{pygmentize:lang=xml}
<saxon:xquery service="test:xquery-dynamic" endpoint="endpoint">
  <saxon:expression>
    <bean class="org.apache.servicemix.expression.PropertyExpression">
      <property name="property" value="xquery.source" />
    </bean>
  </saxon:expression>
</saxon:xquery>
{pygmentize}