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/03/25 10:25:22 UTC
[1/2] camel git commit: Added camel-flatpack docs to gitbook
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 <an...@gmail.com>
Authored: Fri Mar 25 10:20:44 2016 +0100
Committer: Andrea Cosentino <an...@gmail.com>
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)
[2/2] camel git commit: Added flatpack-dataformat docs to gitbook
Posted by ac...@apache.org.
Added flatpack-dataformat 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/ac7662e5
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/ac7662e5
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/ac7662e5
Branch: refs/heads/master
Commit: ac7662e536a29685f18a3054a30c6d371bb2a272
Parents: 7f6bd60
Author: Andrea Cosentino <an...@gmail.com>
Authored: Fri Mar 25 10:24:40 2016 +0100
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Fri Mar 25 10:24:40 2016 +0100
----------------------------------------------------------------------
.../src/main/docs/flatpack-dataformat.adoc | 107 +++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 108 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/ac7662e5/components/camel-flatpack/src/main/docs/flatpack-dataformat.adoc
----------------------------------------------------------------------
diff --git a/components/camel-flatpack/src/main/docs/flatpack-dataformat.adoc b/components/camel-flatpack/src/main/docs/flatpack-dataformat.adoc
new file mode 100644
index 0000000..d4d526b
--- /dev/null
+++ b/components/camel-flatpack/src/main/docs/flatpack-dataformat.adoc
@@ -0,0 +1,107 @@
+[[FlatpackDataFormat-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.
+
+[[FlatpackDataFormat-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.
+|=======================================================================
+
+[[FlatpackDataFormat-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.
+
+[[FlatpackDataFormat-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>
+-----------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/ac7662e5/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 1e94f8e..6054bc7 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -150,6 +150,7 @@
-->
* Data Formats
+ * [Flatpack](flatpack-dataformat.adoc)
* [XML JSON](xmljson.adoc)
* User Guide