JBI Support deprecated in Apache ServiceMix 4

JBI 1.0 support is available in Apache ServiceMix 4 to allow existing users to migrate more easily to this latest version - if you're a new user, you should consider JBI deprecated and not use it for your project. Take a look at our technology selection guidelines for more information.

servicemix-saxon

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.

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.

    <beans xmlns:saxon="http://servicemix.apache.org/saxon  /1.0">

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

    </beans>

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

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.

<saxon:xslt service="test:xslt" endpoint="endpoint"
            resource="classpath:transform.xsl" />

Endpoint properties

Property Name Type Description
configuration net.sf.saxon.Configuration Additional configuration for the Saxon XSL-T/XQuery processor.
copyAttachments boolean Copy attachments into the resulting normalized message. Defaults to <code>true</code>.
copyProperties boolean Copy properties into the resulting normalized message. Defaults to <code>true</code>.
copySubject boolean Copy the security subject into the resulting normalized message. Defaults to <code>true</code>.
endpoint java.lang.String The name of the endpoint.
expression org.apache.servicemix.expression.Expression Expression to dynamically determine the stylesheet to use for processing the exchange.
interfaceName javax.xml.namespace.QName The qualified name of the interface exposed by the endpoint.
parameters java.util.Map Add parameter names and values that are available during XSL/XQuery processing.
reload boolean Sets whether the endpoint should reload the resource each time it is used. A value of <code>true</code> will ensure that the resource is not cached which can be useful if the resource is updated regularly and is stored outside of the service unit.
resource org.springframework.core.io.Resource Spring Resource for the XSL-T stylesheet or XQuery file to use.
result java.lang.String The output result type, possible values are dom, bytes, string. Defaults to dom.
service javax.xml.namespace.QName The qualified name of the service the endpoint exposes.
sourceTransformer org.apache.servicemix.jbi.jaxp.SourceTransformer Set a SourceTransformer instance to use for handling XML conversions.
transformerFactory javax.xml.transform.TransformerFactory Set a transform factory, e.g. for injecting a custom transformer configuration or implementation.
useDomSourceForContent java.lang.Boolean Convert the message body Source into a DOMSource. Defaults to <code>false</true>.
useDomSourceForXslt boolean Convert the XSL-T stylesheet Source into a DOMSource. Defaults to <code>true</true>.
wsdlResource org.springframework.core.io.Resource Resource referring to the WSDL resource that defines this endpoint.

Mandatory properties

The endpoint requires one of these two properties to be specified:

Attribute Type description
resource (Spring resource) the spring resource pointing to the XSLT stylesheet
expression (ServiceMix expression) expression used to dynamically load the stylesheet

Optional properties

Attribute Type description
wsdlResource (Spring resource) 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) 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

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.

<?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>    

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

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.

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

Endpoint properties

Property Name Type Description
configuration net.sf.saxon.Configuration Additional configuration for the Saxon XSL-T/XQuery processor.
copyAttachments boolean Copy attachments into the resulting normalized message. Defaults to <code>true</code>.
copyProperties boolean Copy properties into the resulting normalized message. Defaults to <code>true</code>.
copySubject boolean Copy the security subject into the resulting normalized message. Defaults to <code>true</code>.
endpoint java.lang.String The name of the endpoint.
expression org.apache.servicemix.expression.Expression Expression to dynamically determine the stylesheet to use for processing the exchange.
faultResource org.springframework.core.io.Resource Spring Resource for the XSL-T stylesheet or XQuery file to use for transforming the 'fault' message.
interfaceName javax.xml.namespace.QName The qualified name of the interface exposed by the endpoint.
outResource org.springframework.core.io.Resource Spring Resource for the XSL-T stylesheet or XQuery file to use for transforming the 'out' message.
parameters java.util.Map Add parameter names and values that are available during XSL/XQuery processing.
reload boolean Sets whether the endpoint should reload the resource each time it is used. A value of <code>true</code> will ensure that the resource is not cached which can be useful if the resource is updated regularly and is stored outside of the service unit.
resource org.springframework.core.io.Resource Spring Resource for the XSL-T stylesheet or XQuery file to use.
result java.lang.String The output result type, possible values are dom, bytes, string. Defaults to dom.
service javax.xml.namespace.QName The qualified name of the service the endpoint exposes.
sourceTransformer org.apache.servicemix.jbi.jaxp.SourceTransformer Set a SourceTransformer instance to use for handling XML conversions.
store org.apache.servicemix.store.Store Configure a custom Store implementation to store correlation information. Usually, a store factory is configured instead of a store. Defaults to {@link org.apache.servicemix.store.memory.MemoryStore}.
storeFactory org.apache.servicemix.store.StoreFactory Configure a custom StoreFactory implementation to store correlation information. Defaults to {@link org.apache.servicemix.store.memory.MemoryStoreFactory}.
target org.apache.servicemix.saxon.support.ExchangeTarget Set the target endpoint that is being proxied by the <code>xslt:proxy</code> endpoint.
transformerFactory javax.xml.transform.TransformerFactory Set a transform factory, e.g. for injecting a custom transformer configuration or implementation.
useDomSourceForContent java.lang.Boolean Convert the message body Source into a DOMSource. Defaults to <code>false</true>.
useDomSourceForXslt boolean Convert the XSL-T stylesheet Sources into a DOMSource. Defaults to <code>true</true>.
wsdlResource org.springframework.core.io.Resource Resource referring to the WSDL resource that defines this endpoint.

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 the XSLT stylesheet used to transform the input message
outResource Spring resource the XSLT stylesheet used to transform the output message
faultResource Spring resource the XSLT stylesheet used to transform the fault message
expression ServiceMix expression 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

Optional properties

Attribute Type Description
wsdlResource Spring resource if set, the wsdl will be retrieved from the given (Spring resource)

transformerFactory (defaults to the Saxon implementation) :: TraX TransformerFactory to create transformers

configuration (Saxon configuration)
result

(defaults to dom) :: Allows specifying the output result type, possible values are dom, bytes, string

copyAttachments, copyProperties and copySubject

Endpoint saxon:xquery

The XQuery endpoint can be used to apply a selected XQuery to the input document.

<saxon:xquery service="test:xquery" endpoint="endpoint"
              resource="classpath:query.xq" />

Endpoint properties

Property Name Type Description
configuration net.sf.saxon.Configuration Additional configuration for the Saxon XSL-T/XQuery processor.
copyAttachments boolean Copy attachments into the resulting normalized message. Defaults to <code>true</code>.
copyProperties boolean Copy properties into the resulting normalized message. Defaults to <code>true</code>.
copySubject boolean Copy the security subject into the resulting normalized message. Defaults to <code>true</code>.
endpoint java.lang.String The name of the endpoint.
expression org.apache.servicemix.expression.Expression Expression to dynamically determine the stylesheet to use for processing the exchange.
interfaceName javax.xml.namespace.QName The qualified name of the interface exposed by the endpoint.
outputProperties java.util.Properties Configure serialization properties, in JAXP format, if the result is to be serialized. This parameter can be defaulted to null.
parameters java.util.Map Add parameter names and values that are available during XSL/XQuery processing.
query java.lang.String Configure the XQuery expression to evaluate.
reload boolean Sets whether the endpoint should reload the resource each time it is used. A value of <code>true</code> will ensure that the resource is not cached which can be useful if the resource is updated regularly and is stored outside of the service unit.
resource org.springframework.core.io.Resource Spring Resource for the XSL-T stylesheet or XQuery file to use.
result java.lang.String The output result type, possible values are dom, bytes, string. Defaults to dom.
service javax.xml.namespace.QName The qualified name of the service the endpoint exposes.
sourceTransformer org.apache.servicemix.jbi.jaxp.SourceTransformer Set a SourceTransformer instance to use for handling XML conversions.
wsdlResource org.springframework.core.io.Resource Resource referring to the WSDL resource that defines this endpoint.

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 resource pointing to the XQuery
expression ServiceMix expression expression to dynamically load the xquery

Optional properties

Attribute Type Description
wsdlResource (Spring resource) WSDL describing the endpoint
outputProperties Map Saxon specific output properties
configuration (Saxon configuration) 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

Sample configurations

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

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

Using parameters in the XSL-T stylesheet (saxon:xslt)

You can define a Map of parameters on the saxon:xslt endpoint.

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

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.

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

Inlined XQuery and specific output configuration (saxon:xquery)

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

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

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