Repository: camel Updated Branches: refs/heads/master f929278b0 -> ac7662e53
Added camel-flatpack 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/7f6bd60a Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/7f6bd60a Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/7f6bd60a Branch: refs/heads/master Commit: 7f6bd60ab7eb657038461f4daac393e0348d0437 Parents: f929278 Author: Andrea Cosentino <[email protected]> Authored: Fri Mar 25 10:20:44 2016 +0100 Committer: Andrea Cosentino <[email protected]> Committed: Fri Mar 25 10:20:44 2016 +0100 ---------------------------------------------------------------------- .../camel-flatpack/src/main/docs/flatpack.adoc | 298 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 299 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/7f6bd60a/components/camel-flatpack/src/main/docs/flatpack.adoc ---------------------------------------------------------------------- diff --git a/components/camel-flatpack/src/main/docs/flatpack.adoc b/components/camel-flatpack/src/main/docs/flatpack.adoc new file mode 100644 index 0000000..cd25aa7 --- /dev/null +++ b/components/camel-flatpack/src/main/docs/flatpack.adoc @@ -0,0 +1,298 @@ +[[Flatpack-FlatpackComponent]] +Flatpack Component +~~~~~~~~~~~~~~~~~~ + +The Flatpack component supports fixed width and delimited file parsing +via the http://flatpack.sourceforge.net[FlatPack library]. + + *Notice:* This component only supports consuming from flatpack files to +Object model. You can not (yet) write from Object model to flatpack +format. + +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-flatpack</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +------------------------------------------------------------ + +[[Flatpack-URIformat]] +URI format +^^^^^^^^^^ + +[source,java] +--------------------------------------------------------- +flatpack:[delim|fixed]:flatPackConfig.pzmap.xml[?options] +--------------------------------------------------------- + +Or for a delimited file handler with no configuration file just use + +[source,java] +--------------------------- +flatpack:someName[?options] +--------------------------- + +You can append query options to the URI in the following format, +`?option=value&option=value&...` + +[[Flatpack-URIOptions]] +URI Options +^^^^^^^^^^^ + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Name |Default Value |Description + +|`delimiter` |`,` |The default character delimiter for delimited files. + +|`textQualifier` |`"` |The text qualifier for delimited files. + +|`ignoreFirstRecord` |`true` |Whether the first line is ignored for delimited files (for the column +headers). + +|`splitRows` |`true` |The component can either process each row one by one or the entire +content at once. + +|`allowShortLines` |`false` |*Camel 2.9.7 and 2.10.5 onwards:* Allows for lines to be shorter than +expected and ignores the extra characters. + +|`ignoreExtraColumns` |`false` |*Camel 2.9.7 and 2.10.5 onwards:* Allows for lines to be longer than +expected and ignores the extra characters. +|======================================================================= + +[[Flatpack-Examples]] +Examples +^^^^^^^^ + +* `flatpack:fixed:foo.pzmap.xml` creates a fixed-width endpoint using +the `foo.pzmap.xml` file configuration. +* `flatpack:delim:bar.pzmap.xml` creates a delimited endpoint using the +`bar.pzmap.xml` file configuration. +* `flatpack:foo` creates a delimited endpoint called `foo` with no file +configuration. + +[[Flatpack-MessageHeaders]] +Message Headers +^^^^^^^^^^^^^^^ + +Camel will store the following headers on the IN message: + +[width="100%",cols="50%,50%",options="header",] +|======================================================================= +|Header |Description + +|`camelFlatpackCounter` |The current row index. For `splitRows=false` the counter is the total +number of rows. +|======================================================================= + +[[Flatpack-MessageBody]] +Message Body +^^^^^^^^^^^^ + +The component delivers the data in the IN message as a +`org.apache.camel.component.flatpack.DataSetList` object that has +converters for `java.util.Map` or `java.util.List`. + + Usually you want the `Map` if you process one row at a time +(`splitRows=true`). Use `List` for the entire content +(`splitRows=false`), where each element in the list is a `Map`. + + Each `Map` contains the key for the column name and its corresponding +value. + +For example to get the firstname from the sample below: + +[source,java] +------------------------------------------------ + Map row = exchange.getIn().getBody(Map.class); + String firstName = row.get("FIRSTNAME"); +------------------------------------------------ + +However, you can also always get it as a `List` (even for +`splitRows=true`). The same example: + +[source,java] +--------------------------------------------------- + List data = exchange.getIn().getBody(List.class); + Map row = (Map)data.get(0); + String firstName = row.get("FIRSTNAME"); +--------------------------------------------------- + +[[Flatpack-HeaderandTrailerrecords]] +Header and Trailer records +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The header and trailer notions in Flatpack are supported. However, you +*must* use fixed record IDs: + +* `header` for the header record (must be lowercase) +* `trailer` for the trailer record (must be lowercase) + +The example below illustrates this fact that we have a header and a +trailer. You can omit one or both of them if not needed. + +[source,xml] +--------------------------------------------------------------------------- + <RECORD id="header" startPosition="1" endPosition="3" indicator="HBT"> + <COLUMN name="INDICATOR" length="3"/> + <COLUMN name="DATE" length="8"/> + </RECORD> + + <COLUMN name="FIRSTNAME" length="35" /> + <COLUMN name="LASTNAME" length="35" /> + <COLUMN name="ADDRESS" length="100" /> + <COLUMN name="CITY" length="100" /> + <COLUMN name="STATE" length="2" /> + <COLUMN name="ZIP" length="5" /> + + <RECORD id="trailer" startPosition="1" endPosition="3" indicator="FBT"> + <COLUMN name="INDICATOR" length="3"/> + <COLUMN name="STATUS" length="7"/> + </RECORD> +--------------------------------------------------------------------------- + +[[Flatpack-Usingtheendpoint]] +Using the endpoint +^^^^^^^^^^^^^^^^^^ + +A common use case is sending a file to this endpoint for further +processing in a separate route. For example: + +[source,xml] +----------------------------------------------------------------------- + <camelContext xmlns="http://activemq.apache.org/camel/schema/spring";> + <route> + <from uri="file://someDirectory"/> + <to uri="flatpack:foo"/> + </route> + + <route> + <from uri="flatpack:foo"/> + ... + </route> + </camelContext> +----------------------------------------------------------------------- + +You can also convert the payload of each message created to a `Map` for +easy link:bean-integration.html[Bean Integration] + +[[Flatpack-FlatpackDataFormat]] +Flatpack DataFormat +~~~~~~~~~~~~~~~~~~~ + +The link:flatpack.html[Flatpack] component ships with the Flatpack data +format that can be used to format between fixed width or delimited text +messages to a `List` of rows as `Map`. + +* marshal = from `List<Map<String, Object>>` to `OutputStream` (can be +converted to `String`) +* unmarshal = from `java.io.InputStream` (such as a `File` or `String`) +to a `java.util.List` as an +`org.apache.camel.component.flatpack.DataSetList` instance. + + The result of the operation will contain all the data. If you need to +process each row one by one you can split the exchange, using +link:splitter.html[Splitter]. + +*Notice:* The Flatpack library does currently not support header and +trailers for the marshal operation. + +[[Flatpack-Options]] +Options +^^^^^^^ + +The data format has the following options: + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Option |Default |Description + +|`definition` |`null` |The flatpack pzmap configuration file. Can be omitted in simpler +situations, but its preferred to use the pzmap. + +|`fixed` |`false` |Delimited or fixed. + +|`ignoreFirstRecord` |`true` |Whether the first line is ignored for delimited files (for the column +headers). + +|`textQualifier` |`"` |If the text is qualified with a char such as `"`. + +|`delimiter` |`,` |The delimiter char (could be `;` `,` or similar) + +|`parserFactory` |`null` |Uses the default Flatpack parser factory. + +|`allowShortLines` |`false` |*Camel 2.9.7 and 2.10.5 onwards*: Allows for lines to be shorter than +expected and ignores the extra characters. + +|`ignoreExtraColumns` |`false` |*Camel 2.9.7 and 2.10.5 onwards*: Allows for lines to be longer than +expected and ignores the extra characters. +|======================================================================= + +[[Flatpack-Usage]] +Usage +^^^^^ + +To use the data format, simply instantiate an instance and invoke the +marshal or unmarshal operation in the route builder: + +[source,java] +--------------------------------------------------------------------------- + FlatpackDataFormat fp = new FlatpackDataFormat(); + fp.setDefinition(new ClassPathResource("INVENTORY-Delimited.pzmap.xml")); + ... + from("file:order/in").unmarshal(df).to("seda:queue:neworder"); +--------------------------------------------------------------------------- + +The sample above will read files from the `order/in` folder and +unmarshal the input using the Flatpack configuration file +`INVENTORY-Delimited.pzmap.xml` that configures the structure of the +files. The result is a `DataSetList` object we store on the SEDA queue. + +[source,java] +----------------------------------------------------------------------------------- +FlatpackDataFormat df = new FlatpackDataFormat(); +df.setDefinition(new ClassPathResource("PEOPLE-FixedLength.pzmap.xml")); +df.setFixed(true); +df.setIgnoreFirstRecord(false); + +from("seda:people").marshal(df).convertBodyTo(String.class).to("jms:queue:people"); +----------------------------------------------------------------------------------- + +In the code above we marshal the data from a Object representation as a +`List` of rows as `Maps`. The rows as `Map` contains the column name as +the key, and the the corresponding value. This structure can be created +in Java code from e.g. a processor. We marshal the data according to the +Flatpack format and convert the result as a `String` object and store it +on a JMS queue. + +[[Flatpack-Dependencies]] +Dependencies +^^^^^^^^^^^^ + +To use Flatpack in your camel routes you need to add the a dependency on +*camel-flatpack* which implements this data format. + +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-flatpack</artifactId> + <version>x.x.x</version> +</dependency> +----------------------------------------- + +[[Flatpack-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/7f6bd60a/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 0e254b5..1e94f8e 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -128,6 +128,7 @@ * [Eventadmin](eventadmin.adoc) * [Exec](exec.adoc) * [Facebook](facebook.adoc) + * [Flatpack](flatpack.adoc) * [Ironmq](ironmq.adoc) * [JMS](jms.adoc) * [JMX](jmx.adoc)
