You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/06/23 08:41:16 UTC
[2/2] camel git commit: Added Xslt component docs to Gitbook
Added Xslt component docs to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/fd256485
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/fd256485
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/fd256485
Branch: refs/heads/master
Commit: fd256485dc766a57f375f434f9c5d016e49425a8
Parents: 49b843f
Author: Andrea Cosentino <an...@gmail.com>
Authored: Thu Jun 23 10:40:41 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Thu Jun 23 10:40:41 2016 +0200
----------------------------------------------------------------------
camel-core/src/main/docs/xslt.adoc | 410 ++++++++++++++++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 411 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/fd256485/camel-core/src/main/docs/xslt.adoc
----------------------------------------------------------------------
diff --git a/camel-core/src/main/docs/xslt.adoc b/camel-core/src/main/docs/xslt.adoc
new file mode 100644
index 0000000..8fb1e00
--- /dev/null
+++ b/camel-core/src/main/docs/xslt.adoc
@@ -0,0 +1,410 @@
+[[XSLT-XSLT]]
+XSLT
+~~~~
+
+The *xslt:* component allows you to process a message using an
+http://www.w3.org/TR/xslt[XSLT] template. This can be ideal when using
+link:templating.html[Templating] to generate respopnses for requests.
+
+[[XSLT-URIformat]]
+URI format
+^^^^^^^^^^
+
+[source,java]
+---------------------------
+xslt:templateName[?options]
+---------------------------
+
+Where *templateName* is the classpath-local URI of the template to
+invoke; or the complete URL of the remote template. Refer to the
+http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/core/io/DefaultResourceLoader.html[Spring
+Documentation for more detail of the URI syntax]
+
+You can append query options to the URI in the following format,
+`?option=value&option=value&...`
+
+Here are some example URIs
+
+URI
+
+Description
+
+[source,java]
+-----------------------------
+xslt:com/acme/mytransform.xsl
+-----------------------------
+
+refers to the file com/acme/mytransform.xsl on the classpath
+
+[source,java]
+------------------------
+xslt:file:///foo/bar.xsl
+------------------------
+
+refers to the file /foo/bar.xsl
+
+[source,java]
+-----------------------------------
+xslt:http://acme.com/cheese/foo.xsl
+-----------------------------------
+
+refers to the remote http resource
+
+Maven users will need to add the following dependency to their `pom.xml`
+for this component when using *Camel 2.8* or older:
+
+[source,xml]
+------------------------------------------------------------
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-spring</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel core version -->
+</dependency>
+------------------------------------------------------------
+
+From Camel 2.9 onwards the link:xslt.html[XSLT] component is provided
+directly in the camel-core.
+
+[[XSLT-Options]]
+Options
+^^^^^^^
+
+// component options: START
+// component options: END
+
+// endpoint options: START
+// endpoint options: END
+
+[[XSLT-UsingXSLTendpoints]]
+Using XSLT endpoints
+^^^^^^^^^^^^^^^^^^^^
+
+For example you could use something like
+
+[source,java]
+--------------------------------------
+from("activemq:My.Queue").
+ to("xslt:com/acme/mytransform.xsl");
+--------------------------------------
+
+To use an XSLT template to formulate a response for a message for InOut
+message exchanges (where there is a `JMSReplyTo` header).
+
+If you want to use InOnly and consume the message and send it to another
+destination you could use the following route:
+
+[source,java]
+--------------------------------------
+from("activemq:My.Queue").
+ to("xslt:com/acme/mytransform.xsl").
+ to("activemq:Another.Queue");
+--------------------------------------
+
+[[XSLT-GettingParametersintotheXSLTtoworkwith]]
+Getting Parameters into the XSLT to work with
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, all headers are added as parameters which are available in
+the XSLT. +
+ To do this you will need to declare the parameter so it is then
+_useable_.
+
+[source,xml]
+-------------------------------------------------------------------
+<setHeader headerName="myParam"><constant>42</constant></setHeader>
+<to uri="xslt:MyTransform.xsl"/>
+-------------------------------------------------------------------
+
+And the XSLT just needs to declare it at the top level for it to be
+available:
+
+[source,xml]
+------------------------------
+<xsl: ...... >
+
+ <xsl:param name="myParam"/>
+
+ <xsl:template ...>
+------------------------------
+
+[[XSLT-SpringXMLversions]]
+Spring XML versions
+^^^^^^^^^^^^^^^^^^^
+
+To use the above examples in Spring XML you would use something like
+
+[source,xml]
+-----------------------------------------------------------------------
+ <camelContext xmlns="http://activemq.apache.org/camel/schema/spring">
+ <route>
+ <from uri="activemq:My.Queue"/>
+ <to uri="xslt:org/apache/camel/spring/processor/example.xsl"/>
+ <to uri="activemq:Another.Queue"/>
+ </route>
+ </camelContext>
+-----------------------------------------------------------------------
+
+There is a
+http://svn.apache.org/repos/asf/camel/trunk/components/camel-spring/src/test/java/org/apache/camel/spring/processor/XsltTest.java[test
+case] along with
+http://svn.apache.org/repos/asf/camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/processor/XsltTest-context.xml[its
+Spring XML] if you want a concrete example.
+
+[[XSLT-Usingxsl:include]]
+Using xsl:include
+^^^^^^^^^^^^^^^^^
+
+*Camel 2.2 or older* +
+ If you use xsl:include in your XSL files then in Camel 2.2 or older it
+uses the default `javax.xml.transform.URIResolver` which means it can
+only lookup files from file system, and its does that relative from the
+JVM starting folder.
+
+For example this include:
+
+[source,xml]
+----------------------------------------
+<xsl:include href="staff_template.xsl"/>
+----------------------------------------
+
+Will lookup the `staff_tempkalte.xsl` file from the starting folder
+where the application was started.
+
+*Camel 2.3 or newer* +
+ Now Camel provides its own implementation of `URIResolver` which allows
+Camel to load included files from the classpath and more intelligent
+than before.
+
+For example this include:
+
+[source,xml]
+----------------------------------------
+<xsl:include href="staff_template.xsl"/>
+----------------------------------------
+
+Will now be located relative from the starting endpoint, which for
+example could be:
+
+[source,java]
+----------------------------------------------------------------------
+.to("xslt:org/apache/camel/component/xslt/staff_include_relative.xsl")
+----------------------------------------------------------------------
+
+Which means Camel will locate the file in the *classpath* as
+`org/apache/camel/component/xslt/staff_template.xsl`. +
+ This allows you to use xsl include and have xsl files located in the
+same folder such as we do in the example
+`org/apache/camel/component/xslt`.
+
+You can use the following two prefixes `classpath:` or `file:` to
+instruct Camel to look either in classpath or file system. If you omit
+the prefix then Camel uses the prefix from the endpoint configuration.
+If that neither has one, then classpath is assumed.
+
+You can also refer back in the paths such as
+
+[source,java]
+-----------------------------------------------------
+ <xsl:include href="../staff_other_template.xsl"/>
+-----------------------------------------------------
+
+Which then will resolve the xsl file under `org/apache/camel/component`.
+
+[[XSLT-Usingxsl:includeanddefaultprefix]]
+Using xsl:include and default prefix
+++++++++++++++++++++++++++++++++++++
+
+When using xsl:include such as:
+
+[source,xml]
+----------------------------------------
+<xsl:include href="staff_template.xsl"/>
+----------------------------------------
+
+Then in Camel 2.10.3 and older, then Camel will use "classpath:" as the
+default prefix, and load the resource from the classpath. This works for
+most cases, but if you configure the starting resource to load from
+file,
+
+[source,java]
+----------------------------------------------------
+.to("xslt:file:etc/xslt/staff_include_relative.xsl")
+----------------------------------------------------
+
+.. then you would have to prefix all your includes with "file:" as well.
+
+[source,xml]
+---------------------------------------------
+<xsl:include href="file:staff_template.xsl"/>
+---------------------------------------------
+
+From Camel 2.10.4 onwards we have made this easier as Camel will use the
+prefix from the endpoint configuration as the default prefix. So from
+Camel 2.10.4 onwards you can do:
+
+[source,xml]
+----------------------------------------
+<xsl:include href="staff_template.xsl"/>
+----------------------------------------
+
+Which will load the staff_template.xsl resource from the file system, as
+the endpoint was configured with "file:" as prefix. +
+ You can still though explicit configure a prefix, and then mix and
+match. And have both file and classpath loading. But that would be
+unusual, as most people either use file or classpath based resources.
+
+[[XSLT-UsingSaxonextensionfunctions]]
+Using Saxon extension functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since Saxon 9.2, writing extension functions has been supplemented by a
+new mechanism, referred to
+as�http://www.saxonica.com/html/documentation/extensibility/integratedfunctions[integrated
+extension functions]�you can now easily use camel:
+
+�
+
+-�Java example:
+
+[source,java]
+---------------------------------------------------------------------------------------------------------------------------------
+SimpleRegistry registry = new SimpleRegistry();
+registry.put("function1", new MyExtensionFunction1());
+registry.put("function2", new MyExtensionFunction2());
+
+CamelContext context = new DefaultCamelContext(registry);
+context.addRoutes(new RouteBuilder() {
+ @Override
+ public void configure() throws Exception {
+ from("direct:start")
+ .to("xslt:org/apache/camel/component/xslt/extensions/extensions.xslt?saxonExtensionFunctions=#function1,#function2");
+ }
+});
+---------------------------------------------------------------------------------------------------------------------------------
+
+�
+
+Spring example:
+
+[source,xml]
+-----------------------------------------------------------------------------------------------------------------------------
+<camelContext xmlns="http://camel.apache.org/schema/spring">
+ <route>
+ <from uri="direct:extensions"/>
+ <to uri="xslt:org/apache/camel/component/xslt/extensions/extensions.xslt?saxonExtensionFunctions=#function1,#function2"/>
+ </route>
+</camelContext>
+
+
+<bean id="function1" class="org.apache.camel.component.xslt.extensions.MyExtensionFunction1"/>
+<bean id="function2" class="org.apache.camel.component.xslt.extensions.MyExtensionFunction2"/>
+-----------------------------------------------------------------------------------------------------------------------------
+
+�
+
+�
+
+[[XSLT-Dynamicstylesheets]]
+Dynamic stylesheets
+^^^^^^^^^^^^^^^^^^^
+
+To provide a dynamic stylesheet at runtime you can define a dynamic URI.
+See�link:how-to-use-a-dynamic-uri-in-to.html[How to use a dynamic URI in
+to()] for more information.
+
+*Available as of Camel 2.9 (removed in 2.11.4, 2.12.3 and 2.13.0)* +
+ Camel provides the `CamelXsltResourceUri` header which you can use to
+define a stylesheet to use instead of what is configured on the endpoint
+URI. This allows you to provide a dynamic stylesheet at runtime.
+
+[[XSLT-Accessingwarnings,errorsandfatalErrorsfromXSLTErrorListener]]
+Accessing warnings, errors and fatalErrors from XSLT ErrorListener
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Available as of Camel 2.14*
+
+From Camel 2.14 onwards, any warning/error or fatalError is stored on
+the current Exchange as a property with the
+keys�`Exchange.XSLT_ERROR`,�`Exchange.XSLT_FATAL_ERROR`,
+or�`Exchange.XSLT_WARNING` which allows end users to get hold of any
+errors happening during transformation.
+
+For example in the stylesheet below, we want to terminate if a staff has
+an empty dob field. And to include a custom error message using
+xsl:message.
+
+[source,java]
+---------------------------------------------------------------------------------------
+ <xsl:template match="/">
+ <html>
+ <body>
+ <xsl:for-each select="staff/programmer">
+ <p>Name: <xsl:value-of select="name"/><br />
+ <xsl:if test="dob=''">
+ <xsl:message terminate="yes">Error: DOB is an empty string!</xsl:message>
+ </xsl:if>
+ </p>
+ </xsl:for-each>
+ </body>
+ </html>
+ </xsl:template>
+---------------------------------------------------------------------------------------
+
+This information is not available on the Exchange stored as an Exception
+that contains the message in the `getMessage()` method on the exception.
+The exception is stored on the Exchange as a warning with the
+key�`Exchange.XSLT_WARNING.`
+
+[[XSLT-NotesonusingXSLTandJavaVersions]]
+Notes on using XSLT and Java Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here are some observations from Sameer, a Camel user, which he kindly
+shared with us:
+
+________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
+In case anybody faces issues with the XSLT endpoint please review these
+points.
+
+I was trying to use an xslt endpoint for a simple transformation from
+one xml to another using a simple xsl. The output xml kept appearing
+(after the xslt processor in the route) with outermost xml tag with no
+content within.
+
+No explanations show up in the DEBUG logs. On the TRACE logs however I
+did find some error/warning indicating that the XMLConverter bean could
+no be initialized.
+
+After a few hours of cranking my mind, I had to do the following to get
+it to work (thanks to some posts on the users forum that gave some
+clue):
+
+\1. Use the transformerFactory option in the route
+`("xslt:my-transformer.xsl?transformerFactory=tFactory")` with the
+`tFactory` bean having bean defined in the spring context for
+`class="org.apache.xalan.xsltc.trax.TransformerFactoryImpl"`. +
+ 2. Added the Xalan jar into my maven pom.
+
+My guess is that the default xml parsing mechanism supplied within the
+JDK (I am using 1.6.0_03) does not work right in this context and does
+not throw up any error either. When I switched to Xalan this way it
+works. This is not a Camel issue, but might need a mention on the xslt
+component page.
+
+Another note, jdk 1.6.0_03 ships with JAXB 2.0 while Camel needs 2.1.
+One workaround is to add the 2.1 jar to the `jre/lib/endorsed` directory
+for the jvm or as specified by the container.
+
+Hope this post saves newbie Camel riders some time.
+________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
+
+[[XSLT-SeeAlso]]
+See Also
+^^^^^^^^
+
+* link:configuring-camel.html[Configuring Camel]
+* link:component.html[Component]
+* link:endpoint.html[Endpoint]
+* link:getting-started.html[Getting Started]
+
http://git-wip-us.apache.org/repos/asf/camel/blob/fd256485/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index b06a254..0f3e099 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -97,6 +97,7 @@
* [Timer](timer.adoc)
* [Validator](validator.adoc)
* [VM](vm.adoc)
+ * [Xslt](xslt.adoc)
* Components
* [Async Http Client (AHC)](ahc.adoc)