db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j..@apache.org
Subject svn commit: r331887 - in /db/derby/site/trunk: build/site/papers/JDBCImplementation.html src/documentation/content/xdocs/papers/JDBCImplementation.html
Date Tue, 08 Nov 2005 20:55:54 GMT
Author: jta
Date: Tue Nov  8 12:55:52 2005
New Revision: 331887

URL: http://svn.apache.org/viewcvs?rev=331887&view=rev
Log:
DERBY-500 Applied Sunitha Kambhampati's Derby web site patch for 
          http://db.apache.org/derby/papers/JDBCImplementation.html . 

Modified:
    db/derby/site/trunk/build/site/papers/JDBCImplementation.html
    db/derby/site/trunk/src/documentation/content/xdocs/papers/JDBCImplementation.html

Modified: db/derby/site/trunk/build/site/papers/JDBCImplementation.html
URL: http://svn.apache.org/viewcvs/db/derby/site/trunk/build/site/papers/JDBCImplementation.html?rev=331887&r1=331886&r2=331887&view=diff
==============================================================================
--- db/derby/site/trunk/build/site/papers/JDBCImplementation.html (original)
+++ db/derby/site/trunk/build/site/papers/JDBCImplementation.html Tue Nov  8 12:55:52 2005
@@ -214,6 +214,14 @@
 </ul>
 </li>
 <li>
+<a href="#Java.sql.PreparedStatement">Java.sql.PreparedStatement</a>
+<ul class="minitoc">
+<li>
+<a href="#setAsciiStream%2CsetBinaryStream%2CsetCharacterStream">setAsciiStream,setBinaryStream,setCharacterStream</a>
+</li>
+</ul>
+</li>
+<li>
 <a href="#Java.sql.ResultSet">Java.sql.ResultSet</a>
 <ul class="minitoc">
 <li>
@@ -342,21 +350,30 @@
 <p>Behavior Clarification</p>
 <p>CONCUR_UPDATABLE concurrency is supported for FORWARD ONLY ResultSet types only.</p>
 </div>
-<a name="N1006C"></a><a name="Java.sql.ResultSet"></a>
+<a name="N1006C"></a><a name="Java.sql.PreparedStatement"></a>
+<h2 class="boxed">Java.sql.PreparedStatement</h2>
+<div class="section">
+<a name="N10070"></a><a name="setAsciiStream%2CsetBinaryStream%2CsetCharacterStream"></a>
+<h3 class="boxed">setAsciiStream,setBinaryStream,setCharacterStream</h3>
+<p>Behavior Clarification</p>
+<p>In Derby, the stream must have the exact amount of data as the length argument,
otherwise an exception with the following message 'Input Stream did not have exact amount
of data as the requested length' is thrown.</p>
+<p>Stream parameter values are not re-used. The JDBC 3.0 specification says in the
last paragraph of 13.2.2 that parameters are re-used but nothing special about streams. However
javadoc for java.sql.PreparedStatement.clearParamters() says 'In general, parameter values
remain in force for repeated use of a statement'. Maybe 'in general' can be interpreted to
mean 'except for streams'. Stream parameter values are not re-used and if a stream is re-used,
the statement execution will fail with 'Stream has already been read and end-of-file reached
and cannot be re-used.'.</p>
+</div>
+<a name="N1007A"></a><a name="Java.sql.ResultSet"></a>
 <h2 class="boxed">Java.sql.ResultSet</h2>
 <div class="section">
 <p>Support for data conversion using the getXXX() methods matches Table B-6 in the
[JDBC3], with some extensions described below.</p>
 <p>Extension</p>
 <p>If the value column is null, then generally any getXXX method can be used to fetch
the null value and a null or a representation of zero will be returned and a subsequent call
to wasNull() will return true. It is not recommended that applications take advantage of this
liberal conversion of SQL NULL values, use of a getXXX() method that works against NULL and
non-NULL values is strongly recommended.</p>
-<a name="N10076"></a><a name="deleteRow%28%29"></a>
+<a name="N10084"></a><a name="deleteRow%28%29"></a>
 <h3 class="boxed">deleteRow()</h3>
 <p>Behavior Clarification</p>
 <p>After deleteRow, ResultSet will be positioned right before the next row for FORWARD
ONLY updatable ResultSets.</p>
-<a name="N1007E"></a><a name="updateRow%28%29"></a>
+<a name="N1008C"></a><a name="updateRow%28%29"></a>
 <h3 class="boxed">updateRow()</h3>
 <p>Behavior Clarification</p>
 <p>After updateRow, ResultSet will be positioned right before the next row for FORWARD
ONLY updatable ResultSets.</p>
-<a name="N10086"></a><a name="GetAsciiStream%28%29"></a>
+<a name="N10094"></a><a name="GetAsciiStream%28%29"></a>
 <h3 class="boxed">GetAsciiStream()</h3>
 <p>Behavior Clarification</p>
 <p>An ASCII character is defined as an eight bit character (range 0x00 to 0xff), see
CHAR() function definition by [JDBC3] in appendix C.2.</p>
@@ -374,11 +391,11 @@
 </li>
 </ul>
 <p>This method is not recommended to use in Derby.<br>Because Derby handles characters
as unicode internally , there is no advantage in using this method .</p>
-<a name="N100A0"></a><a name="GetBinaryStream%28%29"></a>
+<a name="N100AE"></a><a name="GetBinaryStream%28%29"></a>
 <h3 class="boxed">GetBinaryStream()</h3>
 <p>Extensions</p>
 <p>On Types.BLOB columns returns a stream with identical contents to that returned
by getBlob().getBinaryStream() on the same column if the BLOB value is not NULL. If the BLOB
value is NULL then null is returned.</p>
-<a name="N100A8"></a><a name="GetCharacterStream%28%29"></a>
+<a name="N100B6"></a><a name="GetCharacterStream%28%29"></a>
 <h3 class="boxed">GetCharacterStream()</h3>
 <p>Behavior Clarification</p>
 <p>For binary types (Types.BINARY, Types.VARBINARY, and Types.LONGVARBINARY, Types.BLOB)
getString() the value is converted to a stream of characters as though it is encoded using
UTF-16BE.</p>
@@ -393,7 +410,7 @@
 <p>On Types.BLOB columns supported with conversion as a binary type.</p>
 </li>
 </ul>
-<a name="N100BA"></a><a name="GetString%28%29"></a>
+<a name="N100C8"></a><a name="GetString%28%29"></a>
 <h3 class="boxed">GetString()</h3>
 <p>Behavior Clarification</p>
 <p>For binary types (Types.BINARY, Types.VARBINARY, and Types.LONGVARBINARY, Types.BLOB)
getString() returns String containing a two character hexadecimal representation for every
byte in a non-null value.&nbsp; The two characters are in the range &lsquo;0&rsquo;
&ndash; &lsquo;9&rsquo; and &lsquo;a&rsquo; &ndash; &lsquo;f&rsquo;.
For NULL values, null is returned. Note, that this String does not match the contents of the
stream returned by getAsciiStream or getCharacterStream on the same column.</p>
@@ -408,10 +425,10 @@
 <p>On Types.BLOB columns supported with conversion as a binary type.</p>
 </li>
 </ul>
-<a name="N100CC"></a><a name="GetUnicodeStream%28%29"></a>
+<a name="N100DA"></a><a name="GetUnicodeStream%28%29"></a>
 <h3 class="boxed">GetUnicodeStream()</h3>
 <p>Not implemented, deprecated by [JDBC3].</p>
-<a name="N100D2"></a><a name="Examples"></a>
+<a name="N100E0"></a><a name="Examples"></a>
 <h3 class="boxed">Examples</h3>
 <p>Binary Column</p>
 <p>If a binary column has been set with the Java byte array containing fours bytes,
byte[] data = {0x34, 0x87, 0xc2, 0x1f} then:</p>
@@ -440,43 +457,43 @@
 </ul>
 </div>
 </div>
-<a name="N100EF"></a><a name="java.sql.Blob"></a>
+<a name="N100FD"></a><a name="java.sql.Blob"></a>
 <h2 class="boxed">java.sql.Blob</h2>
 <div class="section">
-<a name="N100F3"></a><a name="getBytes%28int+pos%2C+int+length%29"></a>
+<a name="N10101"></a><a name="getBytes%28int+pos%2C+int+length%29"></a>
 <h3 class="boxed">getBytes(int pos, int length)</h3>
 <p>Behavior Clarification</p>
 <p>If the pos (position) argument is greater than the length of the BLOB then an exception
is thrown. This matches the semantics of the SQL SUBSTR function.</p>
-<a name="N100FB"></a><a name="position%28byte+pattern%2C+int+start%29+and+position%28Blob+pattern%2C+int+start%29"></a>
+<a name="N10109"></a><a name="position%28byte+pattern%2C+int+start%29+and+position%28Blob+pattern%2C+int+start%29"></a>
 <h3 class="boxed">position(byte pattern, int start) and position(Blob pattern, int
start)</h3>
 <p>Behavior Clarification</p>
 <p>If the pattern argument has length zero, then the value of start argument will be
returned. This matches the semantics of the SQL LOCATE function.</p>
 </div>
-<a name="N10103"></a><a name="java.sql.Clob"></a>
+<a name="N10111"></a><a name="java.sql.Clob"></a>
 <h2 class="boxed">java.sql.Clob</h2>
 <div class="section">
-<a name="N10107"></a><a name="getSubString%28int+pos%2C+int+length%29"></a>
+<a name="N10115"></a><a name="getSubString%28int+pos%2C+int+length%29"></a>
 <h3 class="boxed">getSubString(int pos, int length)</h3>
 <p>Behavior Clarification</p>
 <p>If the pos (position) argument is greater than the length of the CLOB then an exception
is thrown. This matches the semantics of the SQL SUBSTR function.</p>
-<a name="N1010F"></a><a name="position%28String+searchstr%2C+int+start%29+and"></a>
+<a name="N1011D"></a><a name="position%28String+searchstr%2C+int+start%29+and"></a>
 <h3 class="boxed">position(String searchstr, int start) andposition(Clob searchstr,
int start)</h3>
 <p>Behavior Clarification</p>
 <p>If the searchstr argument has length zero (the empty string), then the value of
start argument will be returned. This matches the semantics of the SQL LOCATE function.</p>
 </div>
-<a name="N10119"></a><a name="Date+Handling"></a>
+<a name="N10127"></a><a name="Date+Handling"></a>
 <h2 class="boxed">Date Handling</h2>
 <div class="section">
-<a name="N1011D"></a><a name="Derby+SQL+DATE"></a>
+<a name="N1012B"></a><a name="Derby+SQL+DATE"></a>
 <h3 class="boxed">Derby SQL DATE</h3>
 <p>Derby&rsquo;s SQL DATE type represents a date in the form yyyy-mm-dd with no
associated time zone information.</p>
-<a name="N10123"></a><a name="java.sql.Date"></a>
+<a name="N10131"></a><a name="java.sql.Date"></a>
 <h4>java.sql.Date</h4>
 <p>A JDBC Date (java.sql.Date) by definition represents a point in time on a given
date in a given time zone.</p>
 <p>[JDBC3] intends that the point in time for a java.sql.Date object is 00:00 (midnight),
but this is not enforced by the class.</p>
 <p>JDBC drivers are required to return java.sql.Date objects that are normalized to
00:00 according to the required time zone.</p>
 <p>Applications are expected to pass in java.sql.Date instances that are normalized
to 00:00 (see section 18.1.1 of [TUTORIAL3]).</p>
-<a name="N1012F"></a><a name="Conversion+of+a+JDBC+java.sql.Date+to+a+Derby+DATE+value"></a>
+<a name="N1013D"></a><a name="Conversion+of+a+JDBC+java.sql.Date+to+a+Derby+DATE+value"></a>
 <h4>Conversion of a JDBC java.sql.Date to a Derby DATE value</h4>
 <ol>
 <li>
@@ -507,7 +524,7 @@
 </ol>
 <p>Derby does not require that the application&rsquo;s java.sql.Date value is normalized
to 00:00 according to the required time zone.</p>
 <p>In both cases no time zone information is stored with the SQL DATE value.</p>
-<a name="N10157"></a><a name="Conversion+of+a+Derby+DATE+value+to+a+JDBC+java.sql.Date"></a>
+<a name="N10165"></a><a name="Conversion+of+a+Derby+DATE+value+to+a+JDBC+java.sql.Date"></a>
 <h4>Conversion of a Derby DATE value to a JDBC java.sql.Date</h4>
 <ol>
 <li>
@@ -533,7 +550,7 @@
 </ul>
 </li>
 </ol>
-<a name="N10170"></a><a name="Conversion+of+a+string+type+to+a+JDBC+java.sql.Date"></a>
+<a name="N1017E"></a><a name="Conversion+of+a+string+type+to+a+JDBC+java.sql.Date"></a>
 <h4>Conversion of a string type to a JDBC java.sql.Date</h4>
 <p>Three different date formats are built into Derby.</p>
 <div style="margin-left: 2em">
@@ -551,16 +568,16 @@
 </div>
 <p>If the format of the string matches one of the built in formats then a conversion
to a java.sql.Date matches that of a SQL DATE value with value yyyy-mm-dd.</p>
 <p>If the string does not match any of the built in formats Derby attempts to use the
Java locale specific parser to interpret the string as a date.</p>
-<a name="N10186"></a><a name="Derby+SQL+TIME"></a>
+<a name="N10194"></a><a name="Derby+SQL+TIME"></a>
 <h3 class="boxed">Derby SQL TIME</h3>
 <p>Derby&rsquo;s SQL TIME type represents a time of day in the form hh:mm:ss with
no associated time zone information.</p>
-<a name="N1018C"></a><a name="java.sql.Time"></a>
+<a name="N1019A"></a><a name="java.sql.Time"></a>
 <h4>java.sql.Time</h4>
 <p>A JDBC Time (java.sql.Time) by definition represents a point in time on an unspecified
day in a given time zone.</p>
 <p>Java.sql.Time extends java.util.date, so it includes a date. [JDBC3] intends that
the date stored in a java.sql.Time be Jan 1 1970, but this is not enforced by the class.</p>
 <p>JDBC drivers are required to return java.sql.Time objects that are normalized to
Jan. 1 1970 according to the required time zone.</p>
 <p>Applications are expected to pass in java.sql.Time instances that are normalized
to Jan. 1 1970.</p>
-<a name="N10198"></a><a name="Conversion+of+a+JDBC+java.sql.Time+to+a+Derby+TIME+value"></a>
+<a name="N101A6"></a><a name="Conversion+of+a+JDBC+java.sql.Time+to+a+Derby+TIME+value"></a>
 <h4>Conversion of a JDBC java.sql.Time to a Derby TIME value</h4>
 <ol>
 <li>
@@ -591,7 +608,7 @@
 </ol>
 <p>Derby does not require that the application&rsquo;s java.sql.Time value be normalized
to Jan 1 1970 according to the required time zone.</p>
 <p>In both cases no time zone information is stored with the SQL TIME value.</p>
-<a name="N101C0"></a><a name="Conversion+of+a+Derby+TIME+value+to+a+JDBC+java.sql.Time"></a>
+<a name="N101CE"></a><a name="Conversion+of+a+Derby+TIME+value+to+a+JDBC+java.sql.Time"></a>
 <h4>Conversion of a Derby TIME value to a JDBC java.sql.Time</h4>
 <ol>
 <li>
@@ -617,7 +634,7 @@
 </ul>
 </li>
 </ol>
-<a name="N101D9"></a><a name="Conversion+of+a+string+type+to+a+JDBC+java.sql.Time"></a>
+<a name="N101E7"></a><a name="Conversion+of+a+string+type+to+a+JDBC+java.sql.Time"></a>
 <h4>Conversion of a string type to a JDBC java.sql.Time</h4>
 <p>Three different time formats are built into Derby:</p>
 <div style="margin-left: 2em">
@@ -635,13 +652,13 @@
 </div>
 <p>If the format of the string matches one of the built in formats then a conversion
to a java.sql.Time matches that of a SQL TIME value with value hh:mm:ss.</p>
 <p>If the string does not match any of the built in formats Derby attempts to use the
Java locale specific parser to interpret the string as a date.</p>
-<a name="N101EF"></a><a name="Derby+SQL+TIMESTAMP"></a>
+<a name="N101FD"></a><a name="Derby+SQL+TIMESTAMP"></a>
 <h3 class="boxed">Derby SQL TIMESTAMP</h3>
 <p>Derby&rsquo;s SQL TIMESTAMP type represents a time of day in the form yyyy-mm-dd
hh:mm:ss.fffffffff (nanosecond granularity) with no associated time zone information.</p>
-<a name="N101F5"></a><a name="java.sql.Timestamp"></a>
+<a name="N10203"></a><a name="java.sql.Timestamp"></a>
 <h4>java.sql.Timestamp</h4>
 <p>A JDBC Timestamp (java.sql.Timestamp) by definition represents a point in time,
with nanosecond resolution, in a given time zone.</p>
-<a name="N101FB"></a><a name="Conversion+of+a+JDBC+java.sql.Timestamp+to+a+Derby+TIMESTAMP+value"></a>
+<a name="N10209"></a><a name="Conversion+of+a+JDBC+java.sql.Timestamp+to+a+Derby+TIMESTAMP+value"></a>
 <h4>Conversion of a JDBC java.sql.Timestamp to a Derby TIMESTAMP value</h4>
 <ol>
 <li>
@@ -670,7 +687,7 @@
 </ul>
 </li>
 </ol>
-<a name="N10227"></a><a name="Conversion+of+a+Derby+TIMESTAMP+value+to+a+JDBC+java.sql.Timestamp"></a>
+<a name="N10235"></a><a name="Conversion+of+a+Derby+TIMESTAMP+value+to+a+JDBC+java.sql.Timestamp"></a>
 <h4>Conversion of a Derby TIMESTAMP value to a JDBC java.sql.Timestamp</h4>
 <ol>
 <li>
@@ -696,7 +713,7 @@
 </ul>
 </li>
 </ol>
-<a name="N10240"></a><a name="Conversion+of+a+string+type+to+a+JDBC+java.sql.Timestamp"></a>
+<a name="N1024E"></a><a name="Conversion+of+a+string+type+to+a+JDBC+java.sql.Timestamp"></a>
 <h4>Conversion of a string type to a JDBC java.sql.Timestamp</h4>
 <p>Two different timestamp formats are built into Derby:</p>
 <div style="margin-left: 2em">
@@ -713,7 +730,7 @@
 <p>If the format of the string matches one of the built in formats then a conversion
to a java.sql.Timestamp matches that of a SQL TIMESTAMP value with value yyyy-mm-dd hh:mm:ss.ffffff.</p>
 <p>If the string does not match any of the built in formats Derby attempts to use the
Java locale specific parser to interpret the string as a date.</p>
 <p>
-<em>Last Updated: April 1, 2005</em>
+<em>Last Updated: November 8, 2005</em>
 </p>
 </div>
 </div>

Modified: db/derby/site/trunk/src/documentation/content/xdocs/papers/JDBCImplementation.html
URL: http://svn.apache.org/viewcvs/db/derby/site/trunk/src/documentation/content/xdocs/papers/JDBCImplementation.html?rev=331887&r1=331886&r2=331887&view=diff
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/papers/JDBCImplementation.html (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/papers/JDBCImplementation.html Tue
Nov  8 12:55:52 2005
@@ -43,6 +43,14 @@
 <P>Behavior Clarification</P>
 <P>CONCUR_UPDATABLE concurrency is supported for 
 FORWARD ONLY ResultSet types only.</P>
+<H1>Java.sql.PreparedStatement</H1>
+
+<H2>setAsciiStream,setBinaryStream,setCharacterStream</h2>
+
+<P>Behavior Clarification</P>
+<PThe stream passed in must have exact data as the length argument. This is standard behavior,
 references  [TUTORIAL3] - JDBC API Tutorial and Reference, Third Edition. ISBN 0321173848
http://java.sun.com/developer/Books/jdbc/Fisher/index.html Chapter 25, Page 664 - setBinaryStream
of PreparedStatement   "length - ... Note that if the stream contains more or less bytes than
are specified in length, an exception is thrown"</P>
+<P>In Derby, the stream must have the exact  amount of data as the length argument,
otherwise an exception with the following message 'Input Stream did not have exact amount
of data as the requested length' is thrown.</P>
+<P>Stream parameter values are not re-used.  The JDBC 3.0 specification says in the
last paragraph of 13.2.2  that parameters are re-used  but nothing special about streams.
However javadoc for java.sql.PreparedStatement.clearParamters() says 'In general, parameter
values remain in force for repeated use of a statement'.  Maybe 'in general' can be interpreted
to mean 'except for streams'.   Stream parameter values are not re-used and if a stream is
re-used, the statement execution will fail with 'Stream has already been read and end-of-file
reached and cannot be re-used.'.</P>
 
 <H1>Java.sql.ResultSet</H1>
 
@@ -485,6 +493,6 @@
 attempts to use the Java locale specific parser to interpret the
 string as a date. 
 </P>
-<P><EM>Last Updated: April 1, 2005</EM></P>
+<P><EM>Last Updated: November 8, 2005</EM></P>
 </BODY>
 </HTML>



Mime
View raw message