src/main/webapp/jbi/servicemix-saxon.conf

h1. servicemix-saxon

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

h3. 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}

h3. Endpoint types
The servicemix-saxon component defines these endpoints:
- {{saxon: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

h2. Endpoint {{saxon: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}

h3. Mandatory properties
The endpoint requires one of these two properties to be specified:
- {{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

h3. Optional properties
- {{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

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

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

h2. 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}

h3. Mandatory properties
Depending on the MEP, you have to set one or more XSL stylesheets to be used for converting the message payloads:
- {{resource}} :: [Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html] pointing to the XSLT stylesheet used to transform the input message
- {{outResource}} :: [Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html] pointing to the XSLT stylesheet used to transform the output message
- {{faultResource}} :: [Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html] pointing to 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

h3. Optional properties
- {{wsdlResource}} :: 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

h2. 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}

h3. Mandatory properties
You need to specify one of {{query}}, {{resource}} or {{expression}}
- {{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]  to dynamically load the xquery

h3. Optional properties
- {{wsdlResource}} :: if set, the wsdl will be retrieved from the given ([Spring resource|http://springframework.org/docs/api/org/springframework/core/io/Resource.html])
- {{outputProperties}} :: Map containing the 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

h2. Sample configurations
h3. {{saxon:xslt}} : Dynamic stylesheet selection
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}

h3. {{saxon:xslt}} : Using parameters in the XSL-T stylesheet
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}

h3. {{saxon:xquery}} : Inlined XQuery and specific output configuration
{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}

h3. {{saxon:xquery}} : Dynamic XQuery selection
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}