camel git commit: Added camel-exec docs to gitbook

[ac...@apache.org]

Repository: camel
Updated Branches:
  refs/heads/master b7bd23c2e -> a6d943932


Added camel-exec 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/a6d94393
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/a6d94393
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/a6d94393

Branch: refs/heads/master
Commit: a6d943932e738d9832c5d563604f9d02187a4547
Parents: b7bd23c
Author: Andrea Cosentino <an...@gmail.com>
Authored: Tue Mar 15 16:33:05 2016 +0100
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Tue Mar 15 16:33:05 2016 +0100

----------------------------------------------------------------------
 components/camel-exec/src/main/docs/exec.adoc | 261 +++++++++++++++++++++
 docs/user-manual/en/SUMMARY.md                |   1 +
 2 files changed, 262 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/a6d94393/components/camel-exec/src/main/docs/exec.adoc
----------------------------------------------------------------------
diff --git a/components/camel-exec/src/main/docs/exec.adoc b/components/camel-exec/src/main/docs/exec.adoc
new file mode 100644
index 0000000..a81a33b
--- /dev/null
+++ b/components/camel-exec/src/main/docs/exec.adoc
@@ -0,0 +1,261 @@
+[[Exec-Execcomponent]]
+Exec component
+~~~~~~~~~~~~~~
+
+*Available in Camel 2.3*
+
+The `exec` component can be used to execute system commands.
+
+[[Exec-Dependencies]]
+Dependencies
+^^^^^^^^^^^^
+
+Maven users need to add the following dependency to their `pom.xml`
+
+[source,xml]
+-------------------------------------
+<dependency>
+  <groupId>org.apache.camel</groupId>
+  <artifactId>camel-exec</artifactId>
+  <version>${camel-version}</version>
+</dependency>
+-------------------------------------
+
+where `${camel-version`} must be replaced by the actual version of Camel
+(2.3.0 or higher).
+
+[[Exec-URIformat]]
+URI format
+^^^^^^^^^^
+
+[source,xml]
+---------------------------
+exec://executable[?options]
+---------------------------
+
+where `executable` is the name, or file path, of the system command that
+will be executed. If executable name is used (e.g. `exec:java`), the
+executable must in the system path.
+
+[[Exec-URIoptions]]
+URI options
+^^^^^^^^^^^
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+|Name |Default value |Description
+|`args` |`null` |The arguments of the executable. The arguments may be one or many +
+ whitespace-separated tokens, that can be quoted with `"` - e.g.
+`args="arg 1" arg2` will use two arguments `arg 1` and `arg2`. To
+include the quotes use `""` - e.g. `args=""arg 1"" arg2` will use the
+arguments `"arg 1"` and `arg2`.
+
+|`workingDir` |`null` |The directory in which the command should be executed. If `null`, the
+working directory of the current process will be used.
+
+|`timeout` |`Long.MAX_VALUE` |The timeout, in milliseconds, after which the executable should be
+terminated. If execution has not completed within the timeout, the
+component will send a termination request.
+
+|`outFile` |`null` |The name of a file, created by the executable, that should be considered
+as its output. If no `outFile` is set, the standard output (stdout) of
+the executable will be used instead.
+
+|`binding` |a `DefaultExecBinding` instance |A reference to a `org.apache.commons.exec.ExecBinding` in the
+http://camel.apache.org/registry.html[Registry].
+
+|`commandExecutor` |a `DefaultCommandExecutor` instance |A reference to a `org.apache.commons.exec.ExecCommandExecutor` in the
+http://camel.apache.org/registry.html[Registry] that customizes the
+command execution. The default command executor utilizes the
+http://commons.apache.org/exec/[commons-exec library], which adds a
+shutdown hook for every executed command.
+
+|`useStderrOnEmptyStdout` |`false` |A boolean indicating that when `stdout` is empty, this component will
+populate the Camel Message Body with `stderr`. This behavior is disabled
+(`false`) by default.
+|=======================================================================
+
+[[Exec-Messageheaders]]
+Message headers
+^^^^^^^^^^^^^^^
+
+The supported headers are defined in
+`org.apache.camel.component.exec.ExecBinding`.
+
+[width="100%",cols="10%,10%,10%,70%",options="header",]
+|=======================================================================
+|Name |Type |Message |Description
+
+|`ExecBinding.EXEC_COMMAND_EXECUTABLE` |`String` |`in` |The name of the system command that will be executed. Overrides
+`executable` in the URI.
+
+|`ExecBinding.EXEC_COMMAND_ARGS` |`java.util.List<String>` |`in` |Command-line arguments to pass to the executed process. The arguments
+are used literally - no quoting is applied. Overrides any existing
+`args` in the URI.
+
+|`ExecBinding.EXEC_COMMAND_ARGS` |`String`| `in` |*Camel 2.5:* The arguments of the executable as a Single string where
+each argument is whitespace separated (see `args` in URI option). The
+arguments are used literally, no quoting is applied. Overrides any
+existing `args` in the URI.
+
+|`ExecBinding.EXEC_COMMAND_OUT_FILE` |`String` |`in` |The name of a file, created by the executable, that should be considered
+as its output. Overrides any existing `outFile` in the URI.
+
+|`ExecBinding.EXEC_COMMAND_TIMEOUT` |`long` |`in` |The timeout, in milliseconds, after which the executable should be
+terminated. Overrides any existing `timeout` in the URI.
+
+|`ExecBinding.EXEC_COMMAND_WORKING_DIR` |`String` |`in` |The directory in which the command should be executed. Overrides any
+existing `workingDir` in the URI.
+
+|`ExecBinding.EXEC_EXIT_VALUE` |`int` |`out` |The value of this header is the _exit value_ of the executable. Non-zero
+exit values typically indicate abnormal termination. Note that the exit
+value is OS-dependent.
+
+|`ExecBinding.EXEC_STDERR` |`java.io.InputStream` |`out` |The value of this header points to the standard error stream (stderr) of
+the executable. If no stderr is written, the value is `null`.
+
+|`ExecBinding.EXEC_USE_STDERR_ON_EMPTY_STDOUT` |`boolean` |`in` |Indicates that when `stdout` is empty, this component will populate the
+Camel Message Body with `stderr`. This behavior is disabled (`false`) by
+default.
+|=======================================================================
+
+[[Exec-Messagebody]]
+Message body
+^^^^^^^^^^^^
+
+If the `Exec` component receives an `in` message body that is
+convertible to `java.io.InputStream`, it is used to feed input to the
+executable via its stdin. After execution,
+http://camel.apache.org/exchange.html[the message body] is the result of
+the execution,- that is, an
+`org.apache.camel.components.exec.ExecResult` instance containing the
+stdout, stderr, exit value, and out file. This component supports the
+following `ExecResult` http://camel.apache.org/type-converter.html[type
+converters] for convenience:
+
+[width="100%",cols="50%,50%",options="header",]
+|=======================================================================
+|From |To
+
+|`ExecResult` |`java.io.InputStream`
+
+|`ExecResult` |`String`
+
+|`ExecResult` |`byte []`
+
+|`ExecResult` |`org.w3c.dom.Document`
+|=======================================================================
+
+If an out file is specified (in the endpoint via `outFile` or the
+message headers via `ExecBinding.EXEC_COMMAND_OUT_FILE`), converters
+will return the content of the out file. If no out file is used, then
+this component will convert the stdout of the process to the target
+type. For more details, please refer to the link:exec.html[usage
+examples] below.
+
+[[Exec-Usageexamples]]
+Usage examples
+^^^^^^^^^^^^^^
+
+[[Exec-Executingwordcount]]
+Executing word count (Linux)
+++++++++++++++++++++++++++++
+
+The example below executes `wc` (word count, Linux) to count the words
+in file `/usr/share/dict/words`. The word count (output) is written to
+the standard output stream of `wc`.
+
+[source,java]
+--------------------------------------------------------------------------------------
+from("direct:exec")
+.to("exec:wc?args=--words /usr/share/dict/words")
+.process(new Processor() {
+     public void process(Exchange exchange) throws Exception {
+       // By default, the body is ExecResult instance
+       assertIsInstanceOf(ExecResult.class, exchange.getIn().getBody());
+       // Use the Camel Exec String type converter to convert the ExecResult to String
+       // In this case, the stdout is considered as output
+       String wordCountOutput = exchange.getIn().getBody(String.class);
+       // do something with the word count
+     }
+});
+--------------------------------------------------------------------------------------
+
+[[Exec-Executingjava]]
+Executing `java`
+++++++++++++++++
+
+The example below executes `java` with 2 arguments: `-server` and
+`-version`, provided that `java` is in the system path.
+
+[source,java]
+--------------------------------------
+from("direct:exec")
+.to("exec:java?args=-server -version")
+--------------------------------------
+
+The example below executes `java` in `c:\temp` with 3 arguments:
+`-server`, `-version` and the sytem property `user.name`.
+
+[source,java]
+----------------------------------------------------------------------------------------------------
+from("direct:exec")
+.to("exec:c:/program files/jdk/bin/java?args=-server -version -Duser.name=Camel&workingDir=c:/temp")
+----------------------------------------------------------------------------------------------------
+
+[[Exec-ExecutingAntscripts]]
+Executing Ant scripts
++++++++++++++++++++++
+
+The following example executes http://ant.apache.org/[Apache Ant]
+(Windows only) with the build file `CamelExecBuildFile.xml`, provided
+that `ant.bat` is in the system path, and that `CamelExecBuildFile.xml`
+is in the current directory.
+
+[source,java]
+--------------------------------------------------
+from("direct:exec")
+.to("exec:ant.bat?args=-f CamelExecBuildFile.xml")
+--------------------------------------------------
+
+In the next example, the `ant.bat` command redirects its output to
+`CamelExecOutFile.txt` with `-l`. The file `CamelExecOutFile.txt` is
+used as the out file with `outFile=CamelExecOutFile.txt`. The example
+assumes that `ant.bat` is in the system path, and that
+`CamelExecBuildFile.xml` is in the current directory.
+
+[source,java]
+-------------------------------------------------------------------------------------------------------
+from("direct:exec")
+.to("exec:ant.bat?args=-f CamelExecBuildFile.xml -l CamelExecOutFile.txt&outFile=CamelExecOutFile.txt")
+.process(new Processor() {
+     public void process(Exchange exchange) throws Exception {
+        InputStream outFile = exchange.getIn().getBody(InputStream.class);
+        assertIsInstanceOf(InputStream.class, outFile);
+        // do something with the out file here
+     }
+  });
+-------------------------------------------------------------------------------------------------------
+
+[[Exec-Executingecho]]
+Executing `echo` (Windows)
+++++++++++++++++++++++++++
+
+Commands such as `echo` and `dir` can be executed only with the command
+interpreter of the operating system. This example shows how to execute
+such a command - `echo` - in Windows.
+
+[source,java]
+----------------------------------------------------------
+from("direct:exec").to("exec:cmd?args=/C echo echoString")
+----------------------------------------------------------
+
+[[Exec-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/a6d94393/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index ed0d028..95b8866 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -125,6 +125,7 @@
     * [ElasticSearch](elasticsearch.adoc)
     * [Elsql](elsql.adoc)
     * [Eventadmin](eventadmin.adoc)
+    * [Exec](exec.adoc)
     * [Ironmq](ironmq.adoc)
     * [JMS](jms.adoc)
     * [Metrics](metrics.adoc)