camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acosent...@apache.org
Subject [2/6] camel git commit: Added Xquery-language docs to Gitbook
Date Fri, 09 Sep 2016 09:31:00 GMT
Added Xquery-language 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/a05a41f2
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/a05a41f2
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/a05a41f2

Branch: refs/heads/master
Commit: a05a41f201285499e4269320ecd6e362bfbaa2a8
Parents: fb23833
Author: Andrea Cosentino <ancosen@gmail.com>
Authored: Fri Sep 9 11:30:23 2016 +0200
Committer: Andrea Cosentino <ancosen@gmail.com>
Committed: Fri Sep 9 11:30:42 2016 +0200

----------------------------------------------------------------------
 .../src/main/docs/xquery-language.adoc          | 235 +++++++++++++++++++
 1 file changed, 235 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/a05a41f2/components/camel-saxon/src/main/docs/xquery-language.adoc
----------------------------------------------------------------------
diff --git a/components/camel-saxon/src/main/docs/xquery-language.adoc b/components/camel-saxon/src/main/docs/xquery-language.adoc
new file mode 100644
index 0000000..9b86bfa
--- /dev/null
+++ b/components/camel-saxon/src/main/docs/xquery-language.adoc
@@ -0,0 +1,235 @@
+[[XQuery-XQuery]]
+XQuery
+~~~~~~
+
+Camel supports http://www.w3.org/TR/xquery/[XQuery] to allow an
+link:expression.html[Expression] or link:predicate.html[Predicate] to be
+used in the link:dsl.html[DSL] or link:xml-configuration.html[Xml
+Configuration]. For example you could use XQuery to create an
+link:predicate.html[Predicate] in a link:message-filter.html[Message
+Filter] or as an link:expression.html[Expression] for a
+link:recipient-list.html[Recipient List].
+
+[[XQuery-Options]]
+XQuery Language options
+^^^^^^^^^^^^^^^^^^^^^^^
+
+// language options: START
+The XQuery language supports 3 options which are listed below.
+
+
+
+{% raw %}
+[width="100%",cols="2,1m,1m,6",options="header"]
+|=======================================================================
+| Name | Default | Java Type | Description
+| type |  | String | Sets the class name of the result type (type from output) The default
result type is NodeSet
+| headerName |  | String | Name of header to use as input instead of the message body
+| trim | true | Boolean | Whether to trim the value to remove leading and trailing whitespaces
and line breaks
+|=======================================================================
+{% endraw %}
+// language options: END
+
+[[XQuery-Examples]]
+Examples
+^^^^^^^^
+
+[source,java]
+---------------------------
+from("queue:foo").filter().
+  xquery("//foo").
+  to("queue:bar")
+---------------------------
+
+You can also use functions inside your query, in which case you need an
+explicit type conversion (or you will get a org.w3c.dom.DOMException:
+HIERARCHY_REQUEST_ERR) by passing the Class as a second argument to the
+*xquery()* method.
+
+[source,java]
+-----------------------------------------------------------------------------
+from("direct:start").
+  recipientList().xquery("concat('mock:foo.', /person/@city)", String.class);
+-----------------------------------------------------------------------------
+
+[[XQuery-Variables]]
+Variables
+^^^^^^^^^
+
+The IN message body will be set as the `contextItem`. Besides this these
+Variables is also added as parameters:
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Variable |Type |Description
+
+|exchange |Exchange |The current Exchange
+
+|in.body |Object |The In message's body
+
+|out.body |Object |The OUT message's body (if any)
+
+|in.headers.* |Object |You can access the value of exchange.in.headers with key *foo* by
using
+the variable which name is in.headers.foo
+
+|out.headers.* |Object |You can access the value of exchange.out.headers with key *foo* by
using
+the variable which name is out.headers.foo variable
+
+|*key name* |Object |Any exchange.properties and exchange.in.headers and any additional
+parameters set using `setParameters(Map)`. These parameters is added
+with they own key name, for instance if there is an IN header with the
+key name *foo* then its added as *foo*.
+|=======================================================================
+
+[[XQuery-UsingXMLconfiguration]]
+Using XML configuration
+^^^^^^^^^^^^^^^^^^^^^^^
+
+If you prefer to configure your routes in your link:spring.html[Spring]
+XML file then you can use XPath expressions as follows
+
+[source,xml]
+---------------------------------------------------------------------------------------------------------------
+<beans xmlns="http://www.springframework.org/schema/beans"
+       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xmlns:foo="http://example.com/person"
+       xsi:schemaLocation="
+       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">
+
+  <camelContext id="camel" xmlns="http://activemq.apache.org/camel/schema/spring">
+    <route>
+      <from uri="activemq:MyQueue"/>
+      <filter>
+        <xquery>/foo:person[@name='James']</xquery>
+        <to uri="mqseries:SomeOtherQueue"/>
+      </filter>
+    </route>
+  </camelContext>
+</beans>
+---------------------------------------------------------------------------------------------------------------
+
+Notice how we can reuse the namespace prefixes, *foo* in this case, in
+the XPath expression for easier namespace based XQuery expressions!
+
+When you use functions in your XQuery expression you need an explicit
+type conversion which is done in the xml configuration via the *@type*
+attribute:
+
+[source,xml]
+-------------------------------------------------------------------------------
+    <xquery type="java.lang.String">concat('mock:foo.', /person/@city)</xquery>
+-------------------------------------------------------------------------------
+
+[[XQuery-UsingXQueryastransformation]]
+Using XQuery as transformation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We can do a message translation using transform or setBody in the route,
+as shown below:
+
+[source,java]
+----------------------------------------
+from("direct:start").
+   transform().xquery("/people/person");
+----------------------------------------
+
+Notice that xquery will use DOMResult by default, so if we want to grab
+the value of the person node, using text() we need to tell xquery to use
+String as result type, as shown:
+
+[source,java]
+-------------------------------------------------------------
+from("direct:start").
+   transform().xquery("/people/person/text()", String.class);
+-------------------------------------------------------------
+
+ 
+
+[[XQuery-UsingXQueryasanendpoint]]
+Using XQuery as an endpoint
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes an XQuery expression can be quite large; it can essentally be
+used for link:templating.html[Templating]. So you may want to use an
+link:xquery-endpoint.html[XQuery Endpoint] so you can route using XQuery
+templates.
+
+The following example shows how to take a message of an ActiveMQ queue
+(MyQueue) and transform it using XQuery and send it to MQSeries.
+
+[source,java]
+-------------------------------------------------------------------------
+  <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
+    <route>
+      <from uri="activemq:MyQueue"/>
+      <to uri="xquery:com/acme/someTransform.xquery"/>
+      <to uri="mqseries:SomeOtherQueue"/>
+    </route>
+  </camelContext>
+-------------------------------------------------------------------------
+
+[[XQuery-Examples.1]]
+Examples
+^^^^^^^^
+
+Here is a simple
+http://svn.apache.org/repos/asf/camel/trunk/components/camel-saxon/src/test/java/org/apache/camel/builder/saxon/XQueryFilterTest.java[example]
+using an XQuery expression as a predicate in a
+link:message-filter.html[Message Filter]
+
+This
+http://svn.apache.org/repos/asf/camel/trunk/components/camel-saxon/src/test/java/org/apache/camel/builder/saxon/XQueryWithNamespacesFilterTest.java[example]
+uses XQuery with namespaces as a predicate in a
+link:message-filter.html[Message Filter]
+
+[[XQuery-LearningXQuery]]
+Learning XQuery
+^^^^^^^^^^^^^^^
+
+XQuery is a very powerful language for querying, searching, sorting and
+returning XML. For help learning XQuery try these tutorials
+
+* Mike Kay's http://www.stylusstudio.com/xquery_primer.html[XQuery
+Primer]
+* the W3Schools http://www.w3schools.com/xquery/default.asp[XQuery
+Tutorial]
+
+You might also find the http://www.w3.org/TR/xpath-functions/[XQuery
+function reference] useful
+
+[[XQuery-Loadingscriptfromexternalresource]]
+Loading script from external resource
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Available as of Camel 2.11*
+
+You can externalize the script and have Camel load it from a resource
+such as `"classpath:"`, `"file:"`, or `"http:"`. +
+ This is done using the following syntax: `"resource:scheme:location"`,
+eg to refer to a file on the classpath you can do:
+
+[source,java]
+------------------------------------------------------------------------------
+.setHeader("myHeader").xquery("resource:classpath:myxquery.txt", String.class)
+------------------------------------------------------------------------------
+
+[[XQuery-Dependencies]]
+Dependencies
+^^^^^^^^^^^^
+
+To use XQuery in your camel routes you need to add the a dependency on
+*camel-saxon* which implements the XQuery language.
+
+If you use maven you could just add the following to your pom.xml,
+substituting the version number for the latest & greatest release (see
+link:download.html[the download page for the latest versions]).
+
+[source,java]
+--------------------------------------
+<dependency>
+  <groupId>org.apache.camel</groupId>
+  <artifactId>camel-saxon</artifactId>
+  <version>x.x.x</version>
+</dependency>
+--------------------------------------


Mime
View raw message