Repository: camel Updated Branches: refs/heads/master d4fa3c55c -> 92ebceef3
CAMEL-9541: component docs Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/92ebceef Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/92ebceef Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/92ebceef Branch: refs/heads/master Commit: 92ebceef3714d0f537fddb38b71288b6067ef5e8 Parents: d4fa3c5 Author: Claus Ibsen <davscl...@apache.org> Authored: Tue Aug 16 14:02:43 2016 +0200 Committer: Claus Ibsen <davscl...@apache.org> Committed: Tue Aug 16 14:02:43 2016 +0200 ---------------------------------------------------------------------- .../src/main/docs/tarfile-dataformat.adoc | 175 +++++++++++++++++++ .../src/main/docs/zipfile-dataformat.adoc | 21 +++ 2 files changed, 196 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/92ebceef/components/camel-tarfile/src/main/docs/tarfile-dataformat.adoc ---------------------------------------------------------------------- diff --git a/components/camel-tarfile/src/main/docs/tarfile-dataformat.adoc b/components/camel-tarfile/src/main/docs/tarfile-dataformat.adoc new file mode 100644 index 0000000..fba4bae --- /dev/null +++ b/components/camel-tarfile/src/main/docs/tarfile-dataformat.adoc @@ -0,0 +1,175 @@ +[[TarFileDataFormat-TarFile]] +Tar File +~~~~~~~~ + +TIP:*Available since Camel 2.18.0* + +The Tar File link:data-format.html[Data Format] is a message compression +and de-compression format. Messages can be marshalled (compressed) to +Tar Files containing a single entry, and Tar Files containing a single +entry can be unmarshalled (decompressed) to the original file contents. + +There is also a aggregation strategy that can +aggregate multiple messages into a single Tar File. + +[[TarFile-Options]] +TarFile Options +^^^^^^^^^^^^^^^ + + +// dataformat options: START +The Tar File dataformat supports 1 options which are listed below. + + + +{% raw %} +[width="100%",cols="2s,1m,1m,6",options="header"] +|======================================================================= +| Name | Default | Java Type | Description +| usingIterator | false | Boolean | If the tar file has more then one entry the setting this option to true allows to work with the splitter EIP to split the data using an iterator in a streaming mode. +|======================================================================= +{% endraw %} +// dataformat options: END + + +[[TarFileDataFormat-Marshal]] +Marshal +^^^^^^^ + +In this example we marshal a regular text/XML payload to a compressed +payload using Tar File compression, and send it to an ActiveMQ queue +called MY_QUEUE. + +[source,java] +----------------------------------------------------------------------- +from("direct:start").marshal().tarFile().to("activemq:queue:MY_QUEUE"); +----------------------------------------------------------------------- + +The name of the Tar entry inside the created Tar File is based on the +incoming `CamelFileName` message header, which is the standard message +header used by the link:file2.html[file component]. Additionally, the +outgoing `CamelFileName` message header is automatically set to the +value of the incoming `CamelFileName` message header, with the ".tar" +suffix. So for example, if the following route finds a file named +"test.txt" in the input directory, the output will be a Tar File named +"test.txt.tar" containing a single Tar entry named "test.txt": + +[source,java] +----------------------------------------------------------------------------------------------- +from("file:input/directory?antInclude=*/.txt").marshal().tarFile().to("file:output/directory"); +----------------------------------------------------------------------------------------------- + +If there is no incoming `CamelFileName` message header (for example, if +the link:file2.html[file component] is not the consumer), then the +message ID is used by default, and since the message ID is normally a +unique generated ID, you will end up with filenames like +`ID-MACHINENAME-2443-1211718892437-1-0.tar`. If you want to override +this behavior, then you can set the value of the `CamelFileName` header +explicitly in your route: + +[source,java] +--------------------------------------------------------------------------------------------------------------------------- +from("direct:start").setHeader(Exchange.FILE_NAME, constant("report.txt")).marshal().tarFile().to("file:output/directory"); +--------------------------------------------------------------------------------------------------------------------------- + +This route would result in a Tar File named "report.txt.tar" in the +output directory, containing a single Tar entry named "report.txt". + +[[TarFileDataFormat-Unmarshal]] +Unmarshal +^^^^^^^^^ + +In this example we unmarshal a Tar File payload from an ActiveMQ queue +called MY_QUEUE to its original format, and forward it for processing to +the `UnTarpedMessageProcessor`. + +[source,java] +----------------------------------------------------------------------------------------------- +from("activemq:queue:MY_QUEUE").unmarshal().tarFile().process(new UnTarpedMessageProcessor()); +----------------------------------------------------------------------------------------------- + +If the Tar File has more then one entry, the usingIterator option of +TarFileDataFormat to be true, and you can use splitter to do the further +work. + +[source,java] +---------------------------------------------------------------------------------------------------- + TarFileDataFormat tarFile = new TarFileDataFormat(); + tarFile.setUsingIterator(true); + from("file:src/test/resources/org/apache/camel/dataformat/tarfile/?consumer.delay=1000&noop=true") + .unmarshal(tarFile) + .split(body(Iterator.class)) + .streaming() + .process(new UnTarpedMessageProcessor()) + .end(); +---------------------------------------------------------------------------------------------------- + +Or you can use the TarSplitter as an expression for splitter directly +like this + +[source,java] +---------------------------------------------------------------------------------------------------- + from("file:src/test/resources/org/apache/camel/dataformat/tarfile?consumer.delay=1000&noop=true") + .split(new TarSplitter()) + .streaming() + .process(new UnTarpedMessageProcessor()) + .end(); +---------------------------------------------------------------------------------------------------- + + +[[TarFileDataFormat-Aggregate]] +Aggregate +^^^^^^^^^ + +INFO:Please note that this aggregation strategy requires eager completion +check to work properly. + +In this example we aggregate all text files found in the input directory +into a single Tar File that is stored in the output directory. + +[source,java] +------------------------------------------------- + from("file:input/directory?antInclude=*/.txt") + .aggregate(new TarAggregationStrategy()) + .constant(true) + .completionFromBatchConsumer() + .eagerCheckCompletion() + .to("file:output/directory"); +------------------------------------------------- + +The outgoing `CamelFileName` message header is created using +java.io.File.createTempFile, with the ".tar" suffix. If you want to +override this behavior, then you can set the value of +the `CamelFileName` header explicitly in your route: + +[source,java] +------------------------------------------------------------ + from("file:input/directory?antInclude=*/.txt") + .aggregate(new TarAggregationStrategy()) + .constant(true) + .completionFromBatchConsumer() + .eagerCheckCompletion() + .setHeader(Exchange.FILE_NAME, constant("reports.tar")) + .to("file:output/directory"); +------------------------------------------------------------ + +[[TarFileDataFormat-Dependencies]] +Dependencies +^^^^^^^^^^^^ + +To use Tar Files in your camel routes you need to add a dependency on +*camel-tarfile* which implements this data format. + +If you use Maven you can 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,xml] +---------------------------------------------------------- +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-tarfile</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +---------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/92ebceef/components/camel-zipfile/src/main/docs/zipfile-dataformat.adoc ---------------------------------------------------------------------- diff --git a/components/camel-zipfile/src/main/docs/zipfile-dataformat.adoc b/components/camel-zipfile/src/main/docs/zipfile-dataformat.adoc index 0f61ea6..0b1e10d 100644 --- a/components/camel-zipfile/src/main/docs/zipfile-dataformat.adoc +++ b/components/camel-zipfile/src/main/docs/zipfile-dataformat.adoc @@ -15,6 +15,27 @@ https://blogs.oracle.com/xuemingshen/entry/zip64_support_for_4g_zipfile[Java Since Camel 2.12.3 there is also a aggregation strategy that can aggregate multiple messages into a single Zip file. +[[ZipFile-Options]] +ZipFile Options +^^^^^^^^^^^^^^^ + + +// dataformat options: START +The Zip File dataformat supports 1 options which are listed below. + + + +{% raw %} +[width="100%",cols="2s,1m,1m,6",options="header"] +|======================================================================= +| Name | Default | Java Type | Description +| usingIterator | false | Boolean | If the zip file has more then one entry the setting this option to true allows to work with the splitter EIP to split the data using an iterator in a streaming mode. +|======================================================================= +{% endraw %} +// dataformat options: END + + + [[ZipFileDataFormat-Marshal]] Marshal ^^^^^^^
