components/camel-stream/src/main/docs/stream-component.adoc

= Stream Component
:doctitle: Stream
:shortname: stream
:artifactid: camel-stream
:description: Read from system-in and write to system-out and system-err streams.
:since: 1.3
:supportlevel: Stable
:tabs-sync-option:
:component-header: Both producer and consumer are supported
:core:

*Since Camel {since}*

*{component-header}*

The Stream component provides access to the `System.in`, `System.out`
and `System.err` streams as well as allowing streaming of file.

Maven users will need to add the following dependency to their `pom.xml`
for this component:

[source,xml]
------------------------------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-stream</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
------------------------------------------------------------

== URI format

-----------------------
stream:in[?options]
stream:out[?options]
stream:err[?options]
stream:header[?options]
stream:file?fileName=/foo/bar.txt
stream:http?httpUrl=http:myserver:8080/data
-----------------------

If the `stream:header` URI is specified, the `stream` header is used to
find the stream to write to. This option is available only for stream
producers (that is, it cannot appear in `from()`).


// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
include::partial$component-endpoint-headers.adoc[]
// component options: END


== Usage

=== Message content

The Stream component supports either `String` or `byte[]` for writing
to streams. Just add either `String` or `byte[]` content to the
`message.in.body`. Messages sent to the *stream:* producer in binary
mode are not followed by the newline character (as opposed to the
`String` messages). Message with `null` body will not be appended to the
output stream. +
 The special `stream:header` URI is used for custom output streams. Just
add a `java.io.OutputStream` object to `message.in.header` in the key
`header`. +
 See samples for an example.

== Examples

In the following sample we route messages from the `direct:in` endpoint
to the `System.out` stream:

[tabs]
====
Java::
+
[source,java]
----
from("direct:in").to("stream:out");
----

XML::
+
[source,xml]
----
<route>
  <from uri="direct:in"/>
  <to uri="stream:out"/>
</route>
----

YAML::
+
[source,yaml]
----
- route:
    from:
      uri: direct:in
      steps:
        - to:
            uri: stream:out
----
====

The following sample demonstrates how the header type can be used to
determine which stream to use. In the sample we use our own output
stream, `MyOutputStream`.

The following sample demonstrates how to continuously read a file stream
(analogous to the UNIX `tail` command):

[tabs]
====
Java::
+
[source,java]
----
from("stream:file?fileName=/server/logs/server.log&scanStream=true&scanStreamDelay=1000")
    .to("bean:logService?method=parseLogLine");
----

XML::
+
[source,xml]
----
<route>
  <from uri="stream:file?fileName=/server/logs/server.log&amp;scanStream=true&amp;scanStreamDelay=1000"/>
  <to uri="bean:logService?method=parseLogLine"/>
</route>
----

YAML::
+
[source,yaml]
----
- route:
    from:
      uri: stream:file
      parameters:
        fileName: /server/logs/server.log
        scanStream: true
        scanStreamDelay: 1000
      steps:
        - to:
            uri: bean:logService
            parameters:
              method: parseLogLine
----
====

If you want to re-load the file if it roll over/rewritten then you should also turn on the `fileWatcher` and `retry` options.

[tabs]
====
Java::
+
[source,java]
----
from("stream:file?fileName=/server/logs/server.log&scanStream=true&scanStreamDelay=1000&retry=true&fileWatcher=true")
    .to("bean:logService?method=parseLogLine");
----

XML::
+
[source,xml]
----
<route>
  <from uri="stream:file?fileName=/server/logs/server.log&amp;scanStream=true&amp;scanStreamDelay=1000&amp;retry=true&amp;fileWatcher=true"/>
  <to uri="bean:logService?method=parseLogLine"/>
</route>
----

YAML::
+
[source,yaml]
----
- route:
    from:
      uri: stream:file
      parameters:
        fileName: /server/logs/server.log
        scanStream: true
        scanStreamDelay: 1000
        retry: true
        fileWatcher: true
      steps:
        - to:
            uri: bean:logService
            parameters:
              method: parseLogLine
----
====

=== Reading HTTP server side streaming

The camel-stream component has basic support for connecting to a remote HTTP server and read streaming data
(chunk of data separated by new-line).

[tabs]
====
Java::
+
[source,java]
----
from("stream:http?scanStream=true&httpUrl=http://localhost:8500")
  .to("log:input");
----

XML::
+
[source,xml]
----
<route>
  <from uri="stream:http?scanStream=true&amp;httpUrl=http://localhost:8500"/>
  <to uri="log:input"/>
</route>
----

YAML::
+
[source,yaml]
----
- route:
    from:
      uri: stream:http
      parameters:
        scanStream: true
        httpUrl: "http://localhost:8500"
      steps:
        - to:
            uri: log:input
----
====