You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by ch...@apache.org on 2008/08/26 22:18:38 UTC
svn commit: r689203 - in /db/derby/docs/trunk/src/ref: crefjavbclobnot.dita
rrefjavsqlprst.dita rrefjavsqlrssc.dita
Author: chaase3
Date: Tue Aug 26 13:18:37 2008
New Revision: 689203
URL: http://svn.apache.org/viewvc?rev=689203&view=rev
Log:
DERBY-1932: Reference Manual updates - JDBC Reference section
Reference Manual: Modified 3 topics in the JDBC Reference section of the manual.
Patch: DERBY-1932.diff
Modified:
db/derby/docs/trunk/src/ref/crefjavbclobnot.dita
db/derby/docs/trunk/src/ref/rrefjavsqlprst.dita
db/derby/docs/trunk/src/ref/rrefjavsqlrssc.dita
Modified: db/derby/docs/trunk/src/ref/crefjavbclobnot.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/crefjavbclobnot.dita?rev=689203&r1=689202&r2=689203&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/crefjavbclobnot.dita (original)
+++ db/derby/docs/trunk/src/ref/crefjavbclobnot.dita Tue Aug 26 13:18:37 2008
@@ -40,15 +40,15 @@
<li><i>getClob</i></li>
<li><i>getAsciiStream</i></li>
<li><i>getBinaryStream</i></li>
-<li><i>getUnicodeStream</i></li>
+<li><i>getCharacterStream</i></li>
</ul></p>
<p>These methods share the same underlying stream; calling more than one
of these methods on the same column could result in undefined behavior.
-For example: <codeblock expanse="column"><b>ResultSet rs = s.executeQuery("SELECT text FROM CLOBS WHERE i = 1");
-while (rs.next()) {
- aclob=rs.getClob(1);
- ip = rs.getAsciiStream(1);
-}</b></codeblock></p>
+For example: <codeblock> ResultSet rs = s.executeQuery("SELECT text FROM CLOBS WHERE i = 1");
+ while (rs.next()) {
+ aclob = rs.getClob(1);
+ ip = rs.getAsciiStream(1);
+ }</codeblock></p>
<p>The streams that handle long-columns are not thread safe. This means that
if a user chooses to open multiple threads and access the stream from each
thread, the resulting behavior is undefined. </p>
Modified: db/derby/docs/trunk/src/ref/rrefjavsqlprst.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefjavsqlprst.dita?rev=689203&r1=689202&r2=689203&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefjavsqlprst.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefjavsqlprst.dita Tue Aug 26 13:18:37 2008
@@ -25,6 +25,7 @@
columns<indexterm>as IN parameters to prepared statement</indexterm></indexterm>
<indexterm>setBinaryStream</indexterm><indexterm>setAsciiStream</indexterm>
<indexterm>setUnicodeStream</indexterm><indexterm>Unicode<indexterm>setUnicodeStream</indexterm></indexterm>
+<indexterm>setCharacterStream</indexterm>
</keywords>
</metadata></prolog>
<refbody>
@@ -32,20 +33,29 @@
and the database.</p></section>
<section><p>JDBC allows an IN parameter to be set to a Java input stream for
passing in large amounts of data in smaller chunks. When the statement is
-run, the JDBC driver makes repeated calls to this input stream.<ph conref="../conrefs.dita#prod/productshortname"></ph> supports
-the three types of streams that the JDBC API provides. These three streams are:
+run, the JDBC driver makes repeated calls to this input stream.
+<ph conref="../conrefs.dita#prod/productshortname"></ph> supports
+the following JDBC stream methods for <i>PreparedStatement</i> objects:
<ul>
<li><i>setBinaryStream</i> <p>Use for streams that contain uninterpreted bytes</p></li>
<li><i>setAsciiStream</i> <p>Use for streams that contain ASCII characters</p></li>
-<li><i>setUnicodeStream</i> <p>Use for streams that contain Unicode characters</p></li>
-</ul></p><p>JDBC 3.0 requires that you specify the length of the
-stream and <ph conref="../conrefs.dita#prod/productshortname"></ph> enforces
+<li><i>setCharacterStream</i> <p>Use for streams that contain characters</p></li>
+</ul></p>
+<note><ph conref="../conrefs.dita#prod/productshortname"></ph> does not support
+the <i>setNCharacterStream</i> method or the deprecated <i>setUnicodeStream</i>
+method.</note>
+<p>JDBC 3.0 requires that you specify the length of the
+stream, and <ph conref="../conrefs.dita#prod/productshortname"></ph> enforces
this requirement if your application runs on JDK 5 or earlier. If your application
-runs on JDK 6, then <ph conref="../conrefs.dita#prod/productshortname"></ph> exposes
+runs on JDK 6, <ph conref="../conrefs.dita#prod/productshortname"></ph> exposes
a JDBC 4.0 implementation, which lets you use the streaming interfaces without
-having to specify the stream length. The stream object passed to these three
-methods can be either a standard Java stream object or the user's own subclass
-that implements the standard <i>java.io.InputStream</i> interface.</p><p>According
+having to specify the stream length. The stream object passed to
+<i>setBinaryStream</i> and <i>setAsciiStream</i> can be either a standard Java
+stream object or the user's own subclass that implements the standard
+<i>java.io.InputStream</i> interface. The object passed to
+<i>setCharacterStream</i> must be a subclass of the abstract
+<i>java.io.Reader</i> class.</p>
+<p>According
to the JDBC standard, streams can be stored only in columns with the data
types shown in the following table.<table frame="all" id="jdbc25312"><title>Streamable
JDBC Data Types</title>
@@ -58,7 +68,7 @@
<entry colname="1">Column Data Type </entry>
<entry colname="colspec0">Corresponding Java Type</entry>
<entry colname="2">AsciiStream</entry>
-<entry colname="3">UnicodeStream</entry>
+<entry colname="3">CharacterStream</entry>
<entry colname="4">BinaryStream</entry>
</row>
</thead>
@@ -68,32 +78,32 @@
<entry colname="colspec0">java.sql.Clob</entry>
<entry colname="2">x</entry>
<entry colname="3">x</entry>
-<entry colname="4"></entry>
+<entry colname="4"> </entry>
</row>
<row>
<entry colname="1">CHAR</entry>
-<entry colname="colspec0"></entry>
+<entry colname="colspec0"> </entry>
<entry colname="2">x</entry>
<entry colname="3">x</entry>
-<entry colname="4"></entry>
+<entry colname="4"> </entry>
</row>
<row>
<entry colname="1">VARCHAR</entry>
-<entry colname="colspec0"></entry>
+<entry colname="colspec0"> </entry>
<entry colname="2">x</entry>
<entry colname="3">x</entry>
-<entry colname="4"></entry>
+<entry colname="4"> </entry>
</row>
<row>
<entry colname="1">LONGVARCHAR</entry>
-<entry colname="colspec0"></entry>
+<entry colname="colspec0"> </entry>
<entry colname="2">X</entry>
<entry colname="3">X</entry>
-<entry colname="4"></entry>
+<entry colname="4"> </entry>
</row>
<row>
<entry colname="1">BINARY</entry>
-<entry colname="colspec0"></entry>
+<entry colname="colspec0"> </entry>
<entry colname="2">x</entry>
<entry colname="3">x</entry>
<entry colname="4">x</entry>
@@ -107,14 +117,14 @@
</row>
<row>
<entry colname="1">VARBINARY</entry>
-<entry colname="colspec0"></entry>
+<entry colname="colspec0"> </entry>
<entry colname="2">x</entry>
<entry colname="3">x</entry>
<entry colname="4">x</entry>
</row>
<row>
<entry colname="1">LONGVARBINARY</entry>
-<entry colname="colspec0"></entry>
+<entry colname="colspec0"> </entry>
<entry colname="2">x</entry>
<entry colname="3">x</entry>
<entry colname="4">X</entry>
@@ -123,28 +133,31 @@
</tgroup>
</table></p><note><ul>
<li>A large X indicates the preferred target data type for the type of stream.
-See <xref href="rrefjdbc20377.dita#rrefjdbc20377/jdbc31241"></xref></li>
-<li>If the stream is stored in a column of a type other than LONG VARCHAR
+See <xref href="rrefjdbc20377.dita#rrefjdbc20377/jdbc31241"></xref>.</li>
+<li>For applications using the client driver, if the stream is stored in a column of a type other than LONG VARCHAR
or LONG VARCHAR FOR BIT DATA, the entire stream must be able to fit into memory
at one time. Streams stored in LONG VARCHAR and LONG VARCHAR FOR BIT DATA
columns do not have this limitation.</li>
<li>Streams cannot be stored in columns of the other built-in data types or
columns of user-defined data types. </li>
</ul></note></section>
-<example><title>Example</title><p>The following example shows how a user can
-store a streamed <i>java.io.File</i> in a LONG VARCHAR column: <codeblock>Statement s = conn.createStatement();
-s.executeUpdate("CREATE TABLE atable (a INT, b LONG VARCHAR)");
-conn.commit();
-java.io.File file = new java.io.File("derby.txt");
-int fileLength = (int) file.length();
-<b>// first, create an input stream</b>
-java.io.InputStream fin = new java.io.FileInputStream(file);
-PreparedStatement ps = conn.prepareStatement(
- "INSERT INTO atable VALUES (?, ?)");
-ps.setInt(1, 1);
-<b>// set the value of the input parameter to the input stream</b>
-ps.setAsciiStream(2, fin, fileLength);
-ps.execute();
-conn.commit();</codeblock></p></example>
+<example><title>Example</title><p>The following code fragment shows how a user can
+store a streamed <i>java.io.File</i> in a LONG VARCHAR column: <codeblock> Statement s = conn.createStatement();
+ s.executeUpdate("CREATE TABLE atable (a INT, b LONG VARCHAR)");
+ conn.commit();
+
+ java.io.File file = new java.io.File("derby.txt");
+ int fileLength = (int) file.length();
+
+ <b>// create an input stream</b>
+ java.io.InputStream fin = new java.io.FileInputStream(file);
+ PreparedStatement ps = conn.prepareStatement(
+ "INSERT INTO atable VALUES (?, ?)");
+ ps.setInt(1, 1);
+
+ <b>// set the value of the input parameter to the input stream</b>
+ ps.setAsciiStream(2, fin, fileLength);
+ ps.execute();
+ conn.commit();</codeblock></p></example>
</refbody>
</reference>
Modified: db/derby/docs/trunk/src/ref/rrefjavsqlrssc.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefjavsqlrssc.dita?rev=689203&r1=689202&r2=689203&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefjavsqlrssc.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefjavsqlrssc.dita Tue Aug 26 13:18:37 2008
@@ -28,35 +28,35 @@
<refbody>
<section><p>If the underlying object is itself an <i>OutputStream</i> class, <i>getBinaryStream</i> returns
the object directly.</p></section>
-<section><p><indexterm>getAsciiStream</indexterm><indexterm>getUnicodeStream</indexterm><indexterm>getBinaryStream</indexterm>To
+<section><p><indexterm>getAsciiStream</indexterm><indexterm>getCharacterStream</indexterm><indexterm>getBinaryStream</indexterm>To
get a field from the <i>ResultSet</i> using streaming columns, you can use
the <i>getXXXStream</i> methods if the type supports it. See <xref href="rrefjavsqlprst.dita#rrefjavsqlprst/jdbc25312"></xref> for
a list of types that support the various streams. (See also <xref href="rrefjdbc20377.dita#rrefjdbc20377/jdbc31241"></xref>.)</p></section>
<section><p>You can retrieve data from one of the supported data type columns
as a stream, whether or not it was stored as a stream.</p></section>
-<section><p>The following example shows how a user can retrieve a LONG VARCHAR
-column as a stream: <codeblock expanse="column"><b><ph>// retrieve data as a stream</ph>
-ResultSet rs = s.executeQuery("SELECT b FROM atable");
-while (rs.next()) {
- <ph>// use a java.io.InputStream to get the data</ph>
- java.io.InputStream ip = rs.getAsciiStream(1);
- <ph>// process the stream--this is just a generic way to</ph>
- <ph>// print the data</ph>
- int c;
- int columnSize = 0;
- byte[] buff = new byte[128];
- for (;;) {
- int size = ip.read(buff);
- if (size == -1)
- break;
- columnSize += size;
- String chunk = new String(buff, 0, size);
- System.out.print(chunk);
+<section><p>The following code fragment shows how a user can retrieve a LONG VARCHAR
+column as a stream: <codeblock> <b>// retrieve data as a stream</b>
+ ResultSet rs = s.executeQuery("SELECT b FROM atable");
+ while (rs.next()) {
+ <b>// use a java.io.InputStream to get the data</b>
+ java.io.InputStream ip = rs.getAsciiStream(1);
+
+ <b>// process the stream--this is just a generic way to
+ // print the data</b>
+ int columnSize = 0;
+ byte[] buff = new byte[128];
+ for (;;) {
+ int size = ip.read(buff);
+ if (size == -1)
+ break;
+ columnSize += size;
+ String chunk = new String(buff, 0, size);
+ System.out.print(chunk);
+ }
}
-}
-rs.close();
-s.close();
-conn.commit();</b></codeblock></p></section>
+ rs.close();
+ s.close();
+ conn.commit();</codeblock></p></section>
</refbody>
</reference>