<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="stream"
    xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Stream Support</title>

  <section id="stream-intro">
    <title>Introduction</title>
    <para>
    In many cases application data is obtained from a stream. It is <emphasis>not</emphasis> recommended to send a reference to a Stream as a message payload to a consumer. Instead messages are created from data that is read from an input stream and message payloads are written to an output stream one by one.
    </para>
  </section>

<section id="stream-reading">
  <title>Reading from streams</title>
  <para>
    Spring Integration provides two adapters for streams. Both <classname>ByteStreamReadingMessageSource</classname> and
    <classname>CharacterStreamReadingMessageSource</classname> implement <interfacename>MessageSource</interfacename>.
  By configuring one of these within a channel-adapter element, the polling period can be configured,
    and the Message Bus can automatically detect and schedule them. The byte stream version requires an
    <classname>InputStream</classname>, and the character stream version requires a <classname>Reader</classname> as
    the single constructor argument. The <classname>ByteStreamReadingMessageSource</classname> also accepts the 'bytesPerMessage'
    property to determine how many bytes it will attempt to read into each <interfacename>Message</interfacename>. The
  default value is 1024
    <programlisting language="xml"><![CDATA[<bean class="org.springframework.integration.stream.ByteStreamReadingMessageSource">
  <constructor-arg ref="someInputStream"/>
  <property name="bytesPerMessage" value="2048"/>
</bean>

<bean class="org.springframework.integration.stream.CharacterStreamReadingMessageSource">
  <constructor-arg ref="someReader"/>
</bean>]]>
    </programlisting>
  </para>
</section>

  <section id="stream-writing">
    <title>Writing to streams</title>
  <para>
    For target streams, there are also two implementations: <classname>ByteStreamWritingMessageHandler</classname> and
      <classname>CharacterStreamWritingMessageHandler</classname>. Each requires a single constructor argument -
      <classname>OutputStream</classname> for byte streams or <classname>Writer</classname> for character streams,
      and each provides a second constructor that adds the optional 'bufferSize'. Since both of these
      ultimately implement the <interfacename>MessageHandler</interfacename> interface, they can be referenced from a
      <emphasis>channel-adapter</emphasis> configuration as described in more detail in
      <xref linkend="channel-adapter"/>.
    <programlisting language="xml"><![CDATA[<bean class="org.springframework.integration.stream.ByteStreamWritingMessageHandler">
  <constructor-arg ref="someOutputStream"/>
  <constructor-arg value="1024"/>
</bean>

<bean class="org.springframework.integration.stream.CharacterStreamWritingMessageHandler">
  <constructor-arg ref="someWriter"/>
</bean>]]>
  </programlisting>
    </para>
  </section>



  <section id="stream-namespace">
    <title>Stream namespace support</title>
  <para>
    To reduce the configuration needed for stream related channel adapters there is a namespace defined. The following schema locations are needed to use it.
    <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/integration/stream"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:beans="http://www.springframework.org/schema/beans"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
      http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
      http://www.springframework.org/schema/integration/stream
      http://www.springframework.org/schema/integration/stream/spring-integration-stream-2.0.xsd">]]></programlisting>
  </para>
    <para>
    To configure the inbound channel adapter the following code snippet shows the different configuration options that are supported.
    <programlisting language="xml"><![CDATA[<stdin-channel-adapter id="adapterWithDefaultCharset"/>

<stdin-channel-adapter id="adapterWithProvidedCharset" charset="UTF-8"/>]]></programlisting>
    </para>
    <para>
    To configure the outbound channel adapter you can use the namespace support as well. The following code snippet shows the different configuration for an outbound channel adapters.
    <programlisting language="xml"><![CDATA[<stdout-channel-adapter id="stdoutAdapterWithDefaultCharset" channel="testChannel"/>

<stdout-channel-adapter id="stdoutAdapterWithProvidedCharset" charset="UTF-8" channel="testChannel"/>

<stderr-channel-adapter id="stderrAdapter" channel="testChannel"/>

<stdout-channel-adapter id="newlineAdapter" append-newline="true" channel="testChannel"/>
    ]]></programlisting>
    </para>
  </section>
</chapter>
