| [[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] |
| |