camel git commit: CAMEL-9541: component docs

[da...@apache.org]

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 <da...@apache.org>
Authored: Tue Aug 16 14:02:43 2016 +0200
Committer: Claus Ibsen <da...@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
 ^^^^^^^