Added camel-univocity-parsers 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/36ce0418 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/36ce0418 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/36ce0418 Branch: refs/heads/master Commit: 36ce0418384f6022d5d992ca9d410f628a92fb95 Parents: 963acd6 Author: Andrea Cosentino <anco...@gmail.com> Authored: Thu Jun 9 09:25:59 2016 +0200 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Thu Jun 9 09:25:59 2016 +0200 ---------------------------------------------------------------------- .../src/main/docs/univocity-parsers.adoc | 282 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 2 +- 2 files changed, 283 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/36ce0418/components/camel-univocity-parsers/src/main/docs/univocity-parsers.adoc ---------------------------------------------------------------------- diff --git a/components/camel-univocity-parsers/src/main/docs/univocity-parsers.adoc b/components/camel-univocity-parsers/src/main/docs/univocity-parsers.adoc new file mode 100644 index 0000000..c982727 --- /dev/null +++ b/components/camel-univocity-parsers/src/main/docs/univocity-parsers.adoc @@ -0,0 +1,282 @@ +[[uniVocity-parsersformats-uniVocity-parsers]] +Univocity-parsers Data-format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*Available as of Camel 2.15.0* + +This link:data-format.html[Data +Format] uses http://www.univocity.com/pages/about-parsers[uniVocity-parsers] +for reading and writing 3 kinds of tabular data text files: + +* CSV (Comma Separated Values), where the values are separated by a +symbol (usually a comma) +* fixed-width, where the values have known sizes +* TSV (Tabular Separated Values), where the fields are separated by a +tabulation + +Thus there are 3 data formats based on uniVocity-parsers. + +If you use Maven you can just add the following to your pom.xml, +substituting the version number for the latest and greatest release +(see https://cwiki.apache.org/confluence/display/CAMEL/Download[the +download page for the latest versions]). + +[source,xml] +---------------------------------------------------- +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-univocity-parsers</artifactId> + <version>x.x.x</version> +</dependency> +---------------------------------------------------- + +[[uniVocity-parsersformats-Options]] +Options +^^^^^^^ + +Most configuration options of the uniVocity-parsers are available in the +data formats. If you want more information about a particular option, +please refer to their +http://www.univocity.com/pages/parsers-documentation[documentation +page]. + +The 3 data formats share common options and have dedicated ones, this +section presents them all. + +[[uniVocity-parsersformats-Commonoptionssharedbyallthedataformats]] +Common options, shared by all the data formats +++++++++++++++++++++++++++++++++++++++++++++++ + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Parameter name |Type |Description + +|`nullValue` |`String` |The string representation of a `null` value. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `null`. + +|`skipEmptyLines` |`Boolean` |Whether or not the empty lines must be ignored. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `true`. + +|`ignoreTrailingWhitespaces` |`Boolean` |Whether or not the trailing white spaces must ignored. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `true`. + +|`ignoreLeadingWhitespaces` |`Boolean` |Whether or not the leading white spaces must be ignored. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `true`. + +|`headersDisabled` |`boolean` |Whether or not the headers are disabled. When defined, this option +explicitly sets the headers as `null` which indicates that there is no +header. This option is `false` by default. + +|`headers` |`String[]` |The headers to use. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `null`. + +|`headersExtractionEnabled` |`Boolean` |Whether or not the header must be read in the first line of the test +document. This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `false`. + +|`numberOfRecordsToRead` |`Integer` |The maximum number of record to read. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `-1`. + +|`emptyValue` |`String` |The String representation of an empty value. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `""`. + +|`lineSeparator` |`String` |The line separator of the files. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is the platform line separator. + +|`normalizedLineSeparator` |`Character` |The normalized line separator of the files. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `"\n"`. + +|`comment` |`Character` |The comment symbol. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `'#'`. + +|`lazyLoad` |`boolean` |Whether the unmarshalling should produce an iterator that reads the +lines on the fly or if all the lines must be read at one. +This option is `false` by default. + +|`asMap` |`boolean` |Whether the unmarshalling should produce maps for the lines values +instead of lists. It requires to have header (either defined or +collected). This options is `false` by default. +|======================================================================= + +[[uniVocity-parsersformats-CSVformatoptions]] +CSV format options +++++++++++++++++++ + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Parameter name |Type |Description + +|`quoteAllFields` |`Boolean` |Whether or not all values must be quoted when writing them. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `false`. + +|`quote` |`Character` |The quote symbol. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is '"'. + +|`quoteEscape` |`Character` |The quote escape symbol. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `'"'`. + +|`delimiter` |`Character` |The delimiter of values. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `','`. +|======================================================================= + +[[uniVocity-parsersformats-Fixed-widthformatoptions]] +Fixed-width format options +++++++++++++++++++++++++++ + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Parameter name |Type |Description + +|`fieldLengths` |`int[]` |This options is required and defines the length of each values + +|`skipTrailingCharsUntilNewline` |`Boolean` |Whether or not the trailing characters until new line must be ignored. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `false`. + +|`recordEndsOnNewLine` |`Boolean` |Whether or not the record ends on new line. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `false`. + +|`padding` |`Character` |The padding character. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `' '` (space). +|======================================================================= + +[[uniVocity-parsersformats-TSVformatoptions]] +TSV format options +++++++++++++++++++ + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Parameter name |Type |Description + +|`escapeChar` |`Character` |The escape character. +This option is `null` by default. When `null`, it uses the default +uniVocity-parser value which is `'\'`. +|======================================================================= + +[[uniVocity-parsersformats-Marshallingusages]] +Marshalling usages +^^^^^^^^^^^^^^^^^^ + +The marshalling accepts either: + +* A list of maps (L`ist<Map<String, ?>>`), one for each line +* A single map (`Map<String, ?>`), for a single line + +Any other body will throws an exception. + +[[uniVocity-parsersformats-Usageexample:marshallingaMapintoCSVformat]] +Usage example: marshalling a Map into CSV format +++++++++++++++++++++++++++++++++++++++++++++++++ + +[source,xml] +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +<route> + <from uri="direct:input"/> + <marshal> + <univocity-csv/> + </marshal> + <to uri="mock:result"/> +</route> +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ + +[[uniVocity-parsersformats-Usageexample:marshallingaMapintofixed-widthformat]] +Usage example: marshalling a Map into fixed-width format +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +[source,xml] +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +<route> + <from uri="direct:input"/> + <marshal> + <univocity-fixed padding="_"> + <univocity-header length="5"/> + <univocity-header length="5"/> + <univocity-header length="5"/> + </univocity-fixed> + </marshal> + <to uri="mock:result"/> +</route> +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ + +[[uniVocity-parsersformats-Usageexample:marshallingaMapintoTSVformat]] +Usage example: marshalling a Map into TSV format +++++++++++++++++++++++++++++++++++++++++++++++++ + +[source,xml] +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +<route> + <from uri="direct:input"/> + <marshal> + <univocity-tsv/> + </marshal> + <to uri="mock:result"/> +</route> +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ + +[[uniVocity-parsersformats-Unmarshallingusages]] +Unmarshalling usages +^^^^^^^^^^^^^^^^^^^^ + +The unmarshalling uses an `InputStream` in order to read the data. + +Each row produces either: + +* a list with all the values in it (`asMap` option with `false`); +* A map with all the values indexed by the +headers (`asMap` option with `true`). + +All the rows can either: + +* be collected at once into a list (`lazyLoad` option with `false`); +* be read on the fly using an iterator (`lazyLoad` option with `true`). + +[[uniVocity-parsersformats-UsageexampleunmarshallingaCSVformatintomapswithautomaticheaders]] +Usage example: unmarshalling a CSV format into maps with automatic headers +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +[source,xml] +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +<route> + <from uri="direct:input"/> + <unmarshal> + <univocity-csv headerExtractionEnabled="true" asMap="true"/> + </unmarshal> + <to uri="mock:result"/> +</route> +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ + +[[uniVocity-parsersformats-Usageexampleunmarshallingafixed-widthformatintolists]] +Usage example: unmarshalling a fixed-width format into lists +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +[source,xml] +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +<route> + <from uri="direct:input"/> + <unmarshal> + <univocity-fixed> + <univocity-header length="5"/> + <univocity-header length="5"/> + <univocity-header length="5"/> + </univocity-fixed> + </unmarshal> + <to uri="mock:result"/> +</route> +------------------------------------------------------------------------------------------------------------------------------------------------------------------------ + http://git-wip-us.apache.org/repos/asf/camel/blob/36ce0418/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 259b937..69c9b18 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -293,7 +293,7 @@ * [Syslog](syslog.adoc) * [SOAP](soap.adoc) * [Tagsoup](tagsoup.adoc) - * [YAML](yaml.adoc) + * [Univocity Parsers](univocity-parsers.adoc) * [XML JSON](xmljson.adoc) * [YAML](yaml.adoc)
