Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id A9F8C200B38 for ; Thu, 23 Jun 2016 10:41:17 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id A8780160A58; Thu, 23 Jun 2016 08:41:17 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 9E48B160A59 for ; Thu, 23 Jun 2016 10:41:16 +0200 (CEST) Received: (qmail 72350 invoked by uid 500); 23 Jun 2016 08:41:15 -0000 Mailing-List: contact commits-help@camel.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@camel.apache.org Delivered-To: mailing list commits@camel.apache.org Received: (qmail 72268 invoked by uid 99); 23 Jun 2016 08:41:15 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 23 Jun 2016 08:41:15 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id A58FCE943A; Thu, 23 Jun 2016 08:41:15 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: acosentino@apache.org To: commits@camel.apache.org Date: Thu, 23 Jun 2016 08:41:16 -0000 Message-Id: <6b632d7176474bb1b7b97c9dda5666aa@git.apache.org> In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [2/2] camel git commit: Added Xslt component docs to Gitbook archived-at: Thu, 23 Jun 2016 08:41:17 -0000 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 Authored: Thu Jun 23 10:40:41 2016 +0200 Committer: Andrea Cosentino 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] +------------------------------------------------------------ + + org.apache.camel + camel-spring + x.x.x + + +------------------------------------------------------------ + +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] +------------------------------------------------------------------- +42 + +------------------------------------------------------------------- + +And the XSLT just needs to declare it at the top level for it to be +available: + +[source,xml] +------------------------------ + + + + + +------------------------------ + +[[XSLT-SpringXMLversions]] +Spring XML versions +^^^^^^^^^^^^^^^^^^^ + +To use the above examples in Spring XML you would use something like + +[source,xml] +----------------------------------------------------------------------- + + + + + + + +----------------------------------------------------------------------- + +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] +---------------------------------------- + +---------------------------------------- + +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] +---------------------------------------- + +---------------------------------------- + +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] +----------------------------------------------------- + +----------------------------------------------------- + +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] +---------------------------------------- + +---------------------------------------- + +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] +--------------------------------------------- + +--------------------------------------------- + +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] +---------------------------------------- + +---------------------------------------- + +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] +----------------------------------------------------------------------------------------------------------------------------- + + + + + + + + + + +----------------------------------------------------------------------------------------------------------------------------- + +  + +  + +[[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] +--------------------------------------------------------------------------------------- + + + + +

Name:
+ + Error: DOB is an empty string! + +

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