You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by mt...@apache.org on 2010/05/31 20:32:57 UTC
svn commit: r949826 - in
/openjpa/branches/1.3.x/openjpa-project/src/doc/manual:
jpa_overview_mapping.xml ref_guide_mapping.xml supported_databases.xml
Author: mtylenda
Date: Mon May 31 18:32:57 2010
New Revision: 949826
URL: http://svn.apache.org/viewvc?rev=949826&view=rev
Log:
OPENJPA-1248: Documentation updates for LOB streaming.
Modified:
openjpa/branches/1.3.x/openjpa-project/src/doc/manual/jpa_overview_mapping.xml
openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_mapping.xml
openjpa/branches/1.3.x/openjpa-project/src/doc/manual/supported_databases.xml
Modified: openjpa/branches/1.3.x/openjpa-project/src/doc/manual/jpa_overview_mapping.xml
URL: http://svn.apache.org/viewvc/openjpa/branches/1.3.x/openjpa-project/src/doc/manual/jpa_overview_mapping.xml?rev=949826&r1=949825&r2=949826&view=diff
==============================================================================
--- openjpa/branches/1.3.x/openjpa-project/src/doc/manual/jpa_overview_mapping.xml (original)
+++ openjpa/branches/1.3.x/openjpa-project/src/doc/manual/jpa_overview_mapping.xml Mon May 31 18:32:57 2010
@@ -2809,6 +2809,12 @@ The implementation will serialize the Ja
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>
Modified: openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_mapping.xml
URL: http://svn.apache.org/viewvc/openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_mapping.xml?rev=949826&r1=949825&r2=949826&view=diff
==============================================================================
--- openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_mapping.xml (original)
+++ openjpa/branches/1.3.x/openjpa-project/src/doc/manual/ref_guide_mapping.xml Mon May 31 18:32:57 2010
@@ -2490,7 +2490,7 @@ version is 8.3-603)
</listitem>
<listitem>
<para>
-SQLServer 2005
+SQL Server 2005
</para>
</listitem>
</itemizedlist>
@@ -2781,33 +2781,59 @@ 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>
+In addition to 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>
+ <listitem>
+ <para>
+SQL Server
+ </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
@@ -2815,6 +2841,9 @@ public class Employee {
...
@Persistent
private InputStream photoStream;
+
+ @Persistent
+ private Reader photoDescription;
...
}
</programlisting>
Modified: openjpa/branches/1.3.x/openjpa-project/src/doc/manual/supported_databases.xml
URL: http://svn.apache.org/viewvc/openjpa/branches/1.3.x/openjpa-project/src/doc/manual/supported_databases.xml?rev=949826&r1=949825&r2=949826&view=diff
==============================================================================
--- openjpa/branches/1.3.x/openjpa-project/src/doc/manual/supported_databases.xml (original)
+++ openjpa/branches/1.3.x/openjpa-project/src/doc/manual/supported_databases.xml Mon May 31 18:32:57 2010
@@ -708,7 +708,7 @@ Using the Sun JDBC-ODBC bridge to connec
</title>
<example id="example_props_sqlserver">
<title>
- Example properties for Microsoft SQLServer
+ Example properties for Microsoft SQL Server
</title>
<programlisting>
openjpa.ConnectionDriverName: com.microsoft.sqlserver.jdbc.SQLServerDriver
@@ -771,6 +771,13 @@ generated values with SQL Server you sho
GenerationType.TABLE, or GenerationType.AUTO.
</para>
</listitem>
+ <listitem>
+ <para>
+The use of <link linkend="ref_guide_streamsupport">LOB streaming</link> is limited.
+When reading LOB data from the database, the Microsoft SQL Server driver will
+actually load all the data into memory at the same time.
+ </para>
+ </listitem>
</itemizedlist>
</section>
</section>
@@ -892,6 +899,13 @@ the connection, or an exception will be
to any value greater than zero will enable streaming result sets.
</para>
</listitem>
+ <listitem>
+ <para>
+The use of <link linkend="ref_guide_streamsupport">LOB streaming</link> is limited.
+When reading LOB data from the database, the MySQL JDBC driver will actually
+load all the data into memory at the same time.
+ </para>
+ </listitem>
</itemizedlist>
</section>
</section>
@@ -976,6 +990,26 @@ Floats and doubles may lose precision wh
CLOB columns cannot be used in queries.
</para>
</listitem>
+ <listitem>
+ <para>
+The use of LOBs with persistent attributes of a streaming data type (e.g.
+<literal>java.io.InputStream</literal> or <literal>java.io.Reader</literal>) may
+require the same connection to be used over the life of the transaction or
+entity manager. If the same connection is not used for persistent operations
+a <literal>java.io.IOException</literal> with message <literal>Closed Connection
+</literal> may result. The OpenJPA property <literal>openjpa.ConnectionRetainMode</literal>
+can be used to control how OpenJPA uses datastore connections. See
+<xref linkend="ref_guide_dbsetup_retain"/> for details.
+ <example id="dbsupport_oracle_retain_connection">
+ <title>
+ Property to retain connection over the lifetime of the entity manager
+ </title>
+<programlisting>
+openjpa.ConnectionRetainMode: always
+</programlisting>
+ </example>
+ </para>
+ </listitem>
</itemizedlist>
</section>
</section>
@@ -1041,6 +1075,13 @@ PostgreSQL cannot store very low and ver
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>