OPENJPA-1248: User manual improvements related to LOB streaming.

git-svn-id: https://svn.apache.org/repos/asf/openjpa/trunk@889946 13f79535-47bb-0310-9956-ffa450edef68

openjpa-project/src/doc/manual/jpa_overview_mapping.xml

@@ -2827,6 +2827,12 @@ The implementation will serialize the Java value if needed.
 The equivalent XML element is <literal>lob</literal>, which has no children or
 attributes.
                 </para>
+                <note>
+                    <para>
+OpenJPA also supports LOB streaming. See <xref linkend="ref_guide_streamsupport"/> in
+the Reference Guide for details.
+                    </para>
+                </note>
             </section>
             <section id="jpa_overview_mapping_enum">
                 <title>

openjpa-project/src/doc/manual/ref_guide_mapping.xml

@@ -2792,33 +2792,54 @@ em.persist(o1);
         </section>
         <section id="ref_guide_streamsupport">
             <title>
-              Stream LOB Support
+                LOB Streaming
             </title>
-              <indexterm zone="ref_guide_streamsupport">
-                  <primary>
-                      stream support
-                  </primary>
-              </indexterm>
-              <indexterm zone="ref_guide_streamsupport">
-                  <primary>
-                      stream lob support
-                  </primary>
-              </indexterm>
-              <para>
-Since the 1.1.0 release Apache OpenJPA added support for Streams. This feature
-makes it possible to stream large amounts of data into and out of fields in
-objects managed by OpenJPA without ever holding all the data in memory at the
-same time.
-              </para>
-              <para>
-To persist a stream, use the 
+            <indexterm zone="ref_guide_streamsupport">
+                <primary>
+                    lob streaming
+                </primary>
+            </indexterm>
+            <para>
+Apart from handling LOBs in a standard JPA manner
+(<classname>LOB</classname> annotation and <literal>lob</literal> XML element),
+OpenJPA supports LOB streaming. This feature
+makes it possible to stream large amounts of data into and out of persistent
+field without ever holding all the data in memory at the same time.
+            </para>
+            <para>
+LOB streaming is supported on the following databases.
+            </para>
+            <itemizedlist>
+                <listitem>
+                    <para>
+MySQL
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+Oracle
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+PostgreSQL
+                    </para>
+                </listitem>
+            </itemizedlist>
+            <para>
+See <xref linkend="supported_databases"/> for possible database-specific
+restrictions.
+            </para>
+            <para>
+To persist a stream, apply the 
 <ulink url="../javadoc/org/apache/openjpa/persistence/Persistent.html">
 <classname>org.apache.openjpa.persistence.Persistent</classname></ulink> 
-annotation.
-              </para>
+annotation to either <classname>java.io.InputStream</classname> or
+<classname>java.io.Reader</classname> field.
+            </para>
             <example id="ref_guide_streamsupport_example">
                 <title>
-                    Showing annotated InputStream
+                    Annotated InputStream and Reader
                 </title>
 <programlisting>
 @Entity
@@ -2826,6 +2847,9 @@ public class Employee {
     ...
     @Persistent
     private InputStream photoStream;
+
+    @Persistent
+    private Reader photoDescription;
     ...
 } 
 </programlisting>

openjpa-project/src/doc/manual/supported_databases.xml

@@ -1238,6 +1238,13 @@ PostgreSQL cannot store very low and very high dates.
 Empty string/char values are stored as NULL.
                     </para>
                 </listitem>
+                <listitem>
+                    <para>
+Persistent fields of type <classname>java.io.Reader</classname> are not
+supported when using
+<link linkend="ref_guide_streamsupport">LOB streaming</link>.
+                    </para>
+                </listitem>
             </itemizedlist>
         </section>
     </section>