Repository: camel Updated Branches: refs/heads/master 7602c20ea -> 60e042ae7
Added camel-stax 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/8a4dc407 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/8a4dc407 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/8a4dc407 Branch: refs/heads/master Commit: 8a4dc407f872c9bb7066be855c3ee97bc9717568 Parents: 7602c20 Author: Andrea Cosentino <anco...@gmail.com> Authored: Wed Jun 8 15:32:34 2016 +0200 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Wed Jun 8 15:32:34 2016 +0200 ---------------------------------------------------------------------- components/camel-stax/src/main/docs/stax.adoc | 219 +++++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 220 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/8a4dc407/components/camel-stax/src/main/docs/stax.adoc ---------------------------------------------------------------------- diff --git a/components/camel-stax/src/main/docs/stax.adoc b/components/camel-stax/src/main/docs/stax.adoc new file mode 100644 index 0000000..4467f38 --- /dev/null +++ b/components/camel-stax/src/main/docs/stax.adoc @@ -0,0 +1,219 @@ +[[StAX-StAXComponent]] +StAX Component +~~~~~~~~~~~~~~ + +*Available as of Camel 2.9* + +The StAX component allows messages to be process through a SAX +http://download.oracle.com/javase/6/docs/api/org/xml/sax/ContentHandler.html[ContentHandler]. + +Another feature of this component is to allow to iterate over JAXB +records using StAX, for example using the link:splitter.html[Splitter] +EIP. + +Maven users will need to add the following dependency to their `pom.xml` +for this component: + +[source,xml] +------------------------------------------------------------ +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-stax</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +------------------------------------------------------------ + +[[StAX-URIformat]] +URI format +^^^^^^^^^^ + +[source,java] +-------------------------- +stax:content-handler-class +-------------------------- + +example: + +[source,java] +----------------------------------- +stax:org.superbiz.FooContentHandler +----------------------------------- + +From *Camel 2.11.1* onwards you can lookup a +`org.xml.sax.ContentHandler` bean from the link:registry.html[Registry] +using the # syntax as shown: + +[source,java] +--------------- +stax:#myHandler +--------------- + +[[Stax-Options]] +Options +~~~~~~~ + + +// component options: START +The StAX component has no options. +// component options: END + + + +// endpoint options: START +The StAX component supports 3 endpoint options which are listed below: + +{% raw %} +[width="100%",cols="2s,1,1m,1m,5",options="header"] +|======================================================================= +| Name | Group | Default | Java Type | Description +| contentHandlerClass | producer | | String | *Required* The FQN class name for the ContentHandler implementation to use. +| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange +| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported). +|======================================================================= +{% endraw %} +// endpoint options: END + + +[[StAX-UsageofacontenthandlerasStAXparser]] +Usage of a content handler as StAX parser +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The message body after the handling is the handler itself. + +Here an example: + +[source,java] +-------------------------------------------------------------------------------------------------------- +from("file:target/in") + .to("stax:org.superbiz.handler.CountingHandler") + // CountingHandler implements org.xml.sax.ContentHandler or extends org.xml.sax.helpers.DefaultHandler + .process(new Processor() { + @Override + public void process(Exchange exchange) throws Exception { + CountingHandler handler = exchange.getIn().getBody(CountingHandler.class); + // do some great work with the handler + } + }); +-------------------------------------------------------------------------------------------------------- + +[[StAX-IterateoveracollectionusingJAXBandStAX]] +Iterate over a collection using JAXB and StAX +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +First we suppose you have JAXB objects. + +For instance a list of records in a wrapper object: + +[source,java] +------------------------------------------------- +import java.util.ArrayList; +import java.util.List; +import javax.xml.bind.annotation.XmlAccessType; +import javax.xml.bind.annotation.XmlAccessorType; +import javax.xml.bind.annotation.XmlElement; +import javax.xml.bind.annotation.XmlRootElement; + +@XmlAccessorType(XmlAccessType.FIELD) +@XmlRootElement(name = "records") +public class Records { + @XmlElement(required = true) + protected List<Record> record; + + public List<Record> getRecord() { + if (record == null) { + record = new ArrayList<Record>(); + } + return record; + } +} +------------------------------------------------- + +and + +[source,java] +--------------------------------------------------------- +import javax.xml.bind.annotation.XmlAccessType; +import javax.xml.bind.annotation.XmlAccessorType; +import javax.xml.bind.annotation.XmlAttribute; +import javax.xml.bind.annotation.XmlType; + +@XmlAccessorType(XmlAccessType.FIELD) +@XmlType(name = "record", propOrder = { "key", "value" }) +public class Record { + @XmlAttribute(required = true) + protected String key; + + @XmlAttribute(required = true) + protected String value; + + public String getKey() { + return key; + } + + public void setKey(String key) { + this.key = key; + } + + public String getValue() { + return value; + } + + public void setValue(String value) { + this.value = value; + } +} +--------------------------------------------------------- + +Then you get a XML file to process: + +[source,xml] +------------------------------------------------------- +<?xml version="1.0" encoding="UTF-8" standalone="yes"?> +<records> + <record value="v0" key="0"/> + <record value="v1" key="1"/> + <record value="v2" key="2"/> + <record value="v3" key="3"/> + <record value="v4" key="4"/> + <record value="v5" key="5"/> +</record> +------------------------------------------------------- + +The StAX component provides an `StAXBuilder` which can be used when +iterating XML elements with the Camel link:splitter.html[Splitter] + +[source,java] +------------------------------------------ +from("file:target/in") + .split(stax(Record.class)).streaming() + .to("mock:records"); +------------------------------------------ + +Where `stax` is a static method on +`org.apache.camel.component.stax.StAXBuilder` which you can static +import in the Java code. The stax builder is by default namespace aware +on the XMLReader it uses. From *Camel 2.11.1* onwards you can turn this +off by setting the boolean parameter to false, as shown below: + +[source,java] +------------------------------------------------- +from("file:target/in") + .split(stax(Record.class, false)).streaming() + .to("mock:records"); +------------------------------------------------- + +[[StAX-ThepreviousexamplewithXMLDSL]] +The previous example with XML DSL ++++++++++++++++++++++++++++++++++ + +The example above could be implemented as follows in XML DSL + +[[StAX-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/8a4dc407/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 6f2d196..c1c2329 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -258,6 +258,7 @@ * [SQL](sql.adoc) * [SQL-Stored](sql-stored.adoc) * [SSH](ssh.adoc) + * [StAX](stax.adoc) * [Telegram](telegram.adoc) * [Twitter](twitter.adoc) * [Websocket](websocket.adoc)
