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/05 19:50:57 UTC
svn commit: r682832 - /db/derby/docs/branches/10.4/src/ref/
Author: chaase3
Date: Tue Aug 5 10:50:57 2008
New Revision: 682832
URL: http://svn.apache.org/viewvc?rev=682832&view=rev
Log:
DERBY-3409: Remove JDBC 2.0-specific topics from Reference Manual and merge implementation notes as needed
Merged DERBY-3409-2.diff to 10.4 docs branch from trunk revision 653913.
Removed:
db/derby/docs/branches/10.4/src/ref/rrefjdbc2_0summary.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc52637.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc59162.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc66688.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc71949.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc77156.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc80004.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc99392.dita
Modified:
db/derby/docs/branches/10.4/src/ref/refderby.ditamap
db/derby/docs/branches/10.4/src/ref/rrefjavsqlprst.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc20485.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc23502.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc29874.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc40794.dita
db/derby/docs/branches/10.4/src/ref/rrefjdbc96386.dita
Modified: db/derby/docs/branches/10.4/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/ref/refderby.ditamap?rev=682832&r1=682831&r2=682832&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/ref/refderby.ditamap (original)
+++ db/derby/docs/branches/10.4/src/ref/refderby.ditamap Tue Aug 5 10:50:57 2008
@@ -510,22 +510,6 @@
</topicref>
</topicref>
</topicref>
-<topicref collection-type="family" href="rrefjdbc2_0summary.dita" navtitle="JDBC 2.0 features">
-<topicref href="rrefjdbc52637.dita" navtitle="java.sql.CallableStatement interface: supported JDBC 2.0 methods">
-</topicref>
-<topicref href="rrefjdbc80004.dita" navtitle="java.sql.Connection interface: supported JDBC 2.0 methods">
-</topicref>
-<topicref href="rrefjdbc66688.dita" navtitle="java.sql.DatabaseMetaData interface: supported JDBC 2.0 methods">
-</topicref>
-<topicref href="rrefjdbc99392.dita" navtitle="java.sql.PreparedStatement interface: supported JDBC 2.0 methods">
-</topicref>
-<topicref href="rrefjdbc77156.dita" navtitle="java.sql.ResultSet interface: supported JDBC 2.0 methods">
-</topicref>
-<topicref href="rrefjdbc71949.dita" navtitle="java.sql.ResultSetMetaData interface: supported JDBC 2.0 methods">
-</topicref>
-<topicref href="rrefjdbc59162.dita" navtitle="java.sql.Statement interface: supported JDBC 2.0 methods">
-</topicref>
-</topicref>
<topicref href="rrefjdbc87220.dita" navtitle="java.sql.BatchUpdateException class">
</topicref>
<topicref href="rrefjdbcjsr169.dita" navtitle="JDBC Package for Connected Device Configuration/Foundation Profile
Modified: db/derby/docs/branches/10.4/src/ref/rrefjavsqlprst.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/ref/rrefjavsqlprst.dita?rev=682832&r1=682831&r2=682832&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/ref/rrefjavsqlprst.dita (original)
+++ db/derby/docs/branches/10.4/src/ref/rrefjavsqlprst.dita Tue Aug 5 10:50:57 2008
@@ -33,15 +33,15 @@
<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 JDBC 1.2 provides. These three streams are:
+the three types of streams that the JDBC API provides. These three streams are:
<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 2.0 and JDBC 3.0 require that you specify the length of the
+</ul></p><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 1.5 or earlier. If your application
-runs on JDK 1.6, then <ph conref="../conrefs.dita#prod/productshortname"></ph> exposes
+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
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
Modified: db/derby/docs/branches/10.4/src/ref/rrefjdbc20485.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/ref/rrefjdbc20485.dita?rev=682832&r1=682831&r2=682832&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/ref/rrefjdbc20485.dita (original)
+++ db/derby/docs/branches/10.4/src/ref/rrefjdbc20485.dita Tue Aug 5 10:50:57 2008
@@ -25,23 +25,8 @@
</metadata></prolog>
<refbody>
<section><p><ph conref="../conrefs.dita#prod/productshortname"></ph> supports
-all the JDBC 1.2 methods of <i>CallableStatement</i>: <ul>
-<li><i>getBoolean()</i></li>
-<li><i>getByte()</i></li>
-<li><i>getBytes()</i></li>
-<li><i>getDate()</i></li>
-<li><i>getDouble()</i></li>
-<li><i>getFloat()</i></li>
-<li><i>getInt()</i></li>
-<li><i>getLong()</i></li>
-<li><i>getObject()</i></li>
-<li><i>getShort()</i></li>
-<li><i>getString()</i></li>
-<li><i>getTime()</i></li>
-<li><i>getTimestamp()</i></li>
-<li><i>registerOutParamter()</i></li>
-<li><i>wasNull()</i></li>
-</ul></p></section>
+all methods of <i>CallableStatement</i> except <i>setBlob</i>, <i>getBlob</i>,
+<i>setClob</i>, and <i>getClob</i>.</p></section>
</refbody>
</reference>
Modified: db/derby/docs/branches/10.4/src/ref/rrefjdbc23502.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/ref/rrefjdbc23502.dita?rev=682832&r1=682831&r2=682832&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/ref/rrefjdbc23502.dita (original)
+++ db/derby/docs/branches/10.4/src/ref/rrefjdbc23502.dita Tue Aug 5 10:50:57 2008
@@ -30,10 +30,67 @@
positioned updates and deletes to operate against the row the underlying cursor
is on, and not the current row of the <i>ResultSet</i>.<indexterm>Cursors<indexterm>pre-fetching
affecting</indexterm></indexterm></p></section>
-<section><p><ph conref="../conrefs.dita#prod/productshortname"></ph> provides
-all the required JDBC 1.2 type conversions of the <i>getXXX</i> methods.</p></section>
<section><p>JDBC does not define the sort of rounding to use for <i>ResultSet.getBigDecimal</i>. <ph
conref="../conrefs.dita#prod/productshortname"></ph> uses <i>java.math.BigDecimal.ROUND_HALF_DOWN</i>.</p></section>
+<table frame="all"><title>Implementation Notes on <i>ResultSet</i> Methods</title>
+<tgroup cols="3" colsep="1" rowsep="1"><colspec colname="1" colnum="1" colwidth="13*"/>
+<colspec colname="2" colnum="2" colwidth="36*"/><colspec colname="3" colnum="3"
+colwidth="51*"/>
+<thead>
+<row>
+<entry align="left" colname="1" valign="bottom">Returns</entry>
+<entry align="left" colname="2" valign="bottom">Signature</entry>
+<entry align="left" colname="3" valign="bottom">Implementation Notes</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry colname="1"><i>void</i></entry>
+<entry colname="2"><i>deleteRow()</i></entry>
+<entry colname="3">After the row is deleted, the <i>ResultSet</i> object will
+be positioned before the next row. Before issuing any methods other
+than close on the <i>ResultSet</i> object, the program will need to
+reposition the <i>ResultSet</i> object.</entry>
+</row>
+<row>
+<entry colname="1"><i>int</i></entry>
+<entry colname="2"><i>getConcurrency()</i></entry>
+<entry colname="3">If the Statement object has <i>CONCUR_READ_ONLY</i> concurrency,
+then this method will return <i>ResultSet.CONCUR_READ_ONLY</i>. But if the
+Statement object has <i>CONCUR_UPDATABLE</i> concurrency, then the return
+value will depend on whether the underlying language <i>ResultSet</i> is updatable
+or not. If the language <i>ResultSet</i> is updatable, then <i>getConcurrency()</i> will
+return <i>ResultSet.CONCUR_UPDATABLE</i>. If the language <i>ResultSet</i> is not
+updatable, then <i>getConcurrency()</i> will return <i>ResultSet.CONCUR_READ_ONLY</i>.</entry>
+</row>
+<row>
+<entry colname="1"><i>boolean</i></entry>
+<entry colname="2"><i>rowDeleted()</i></entry>
+<entry colname="3">For forward-only result sets this method always returns <i>false</i>, for
+scrollable result sets it returns <i>true</i> if the row has been deleted, via result set or positioned delete.</entry>
+</row>
+<row>
+<entry colname="1"><i>boolean</i></entry>
+<entry colname="2"><i>rowInserted()</i></entry>
+<entry colname="3">Always returns <i>false</i>.</entry>
+</row>
+<row>
+<entry colname="1"><i>boolean</i></entry>
+<entry colname="2"><i>rowUpdated()</i></entry>
+<entry colname="3">For forward-only result sets this method always returns <i>false</i>, for
+scrollable result sets it returns <i>true</i> if the row has been updated, via result set or positioned update.</entry>
+</row>
+<row>
+<entry colname="1"><i>void</i></entry>
+<entry colname="2"><i>updateRow()</i></entry>
+<entry colname="3">After the row is updated, the <i>ResultSet</i> object will be
+positioned before the next row. Before issuing any methods other than close
+on the <i>ResultSet</i> object, the program will need to reposition the <i>ResultSet</i>
+object.</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
</refbody>
</reference>
Modified: db/derby/docs/branches/10.4/src/ref/rrefjdbc29874.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/ref/rrefjdbc29874.dita?rev=682832&r1=682831&r2=682832&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/ref/rrefjdbc29874.dita (original)
+++ db/derby/docs/branches/10.4/src/ref/rrefjdbc29874.dita Tue Aug 5 10:50:57 2008
@@ -25,7 +25,7 @@
</metadata></prolog>
<refbody>
<section><p><ph conref="../conrefs.dita#prod/productshortname"></ph> provides
-all the required JDBC 1.2 type conversions and additionally allows use of
+all the required JDBC type conversions and additionally allows use of
the individual <i>setXXX</i> methods for each type as if a <i>setObject(Value,
JDBCTypeCode)</i> invocation were made. </p></section>
<section><p>This means that <i>setString</i> can be used for any built-in
Modified: db/derby/docs/branches/10.4/src/ref/rrefjdbc40794.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/ref/rrefjdbc40794.dita?rev=682832&r1=682831&r2=682832&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/ref/rrefjdbc40794.dita (original)
+++ db/derby/docs/branches/10.4/src/ref/rrefjdbc40794.dita Tue Aug 5 10:50:57 2008
@@ -24,17 +24,9 @@
</metadata></prolog>
<refbody>
<section><p><ph conref="../conrefs.dita#prod/productshortname"></ph> does
-not implement the JDBC 1.2 <i>setEscapeProcessing</i> method of <i>java.sql.Statement</i>.
-In addition, the following optional methods raise "Feature not
-supported" exceptions:
-</p>
-<ul>
-<li><i>cancel( )</i></li>
-<li><i>execute( java.lang.String, int[] )</i></li>
-<li><i>execute( java.lang.String, String[] )</i></li>
-<li><i>executeUpdate( java.lang.String, int[] )</i></li>
-<li><i>executeUpdate( java.lang.String, String[] )</i></li>
-</ul>
+not implement the <i>setEscapeProcessing</i> method of <i>java.sql.Statement</i>.
+In addition, the <i>cancel</i> method raises a "Feature not supported"
+exception.</p>
</section>
</refbody>
</reference>
Modified: db/derby/docs/branches/10.4/src/ref/rrefjdbc96386.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/branches/10.4/src/ref/rrefjdbc96386.dita?rev=682832&r1=682831&r2=682832&view=diff
==============================================================================
--- db/derby/docs/branches/10.4/src/ref/rrefjdbc96386.dita (original)
+++ db/derby/docs/branches/10.4/src/ref/rrefjdbc96386.dita Tue Aug 5 10:50:57 2008
@@ -25,58 +25,50 @@
</keywords>
</metadata></prolog>
<refbody>
-<section><p>In JDBC 2.0, <i>java.sql.Blob</i> is the mapping for the SQL BLOB
+<section><p>In the JDBC API, <i>java.sql.Blob</i> is the mapping for the SQL BLOB
(binary large object) type; <i>java.sql.Clob</i> is the mapping for the SQL
-CLOB (character large object) type.</p></section>
-<section><p>java.sql.Blob and java.sql.Clob provide a logical pointer to the
-large object rather than a complete copy of the objects. <ph conref="../conrefs.dita#prod/productshortname"></ph> processes
-only one data page into memory at a time. The whole BLOB does not need to
-be processed and stored in memory just to access the first few bytes of the
-LOB object</p></section>
-<section><p><ph conref="../conrefs.dita#prod/productshortname"></ph> now supports
-the built-in BLOB or CLOB data types. <ph conref="../conrefs.dita#prod/productshortname"></ph> also
-provides the following support for these data types: <ul>
-<li><b>BLOB Features</b> <ph conref="../conrefs.dita#prod/productshortname"></ph> supports
-the <i>java.sql.Blob</i> interface and the BLOB-related methods listed in <i><xref
-href="rrefjdbc99392.dita#rrefjdbc99392"></xref></i> and <i><xref href="rrefjdbc77156.dita#rrefjdbc77156"></xref></i>.
-The <i>getBlob</i> methods of <i>CallableStatement</i> are not implemented.</li>
-<li><b>CLOB Features</b> <ph conref="../conrefs.dita#prod/productshortname"></ph> supports
-the java.sql.Clob interface and the CLOB-related methods listed in <i><xref href="rrefjdbc99392.dita#rrefjdbc99392"></xref></i> and <i><xref
-href="rrefjdbc77156.dita#rrefjdbc77156"></xref></i>. The <i>getClob</i> methods
-of <i>CallableStatement</i> procedures are not implemented.</li>
-</ul></p></section>
-<section><p>To use the java.sql.Blob and java.sql.Clob features: <ul>
-<li>Use the SQL BLOB type for storage; LONG VARCHAR FOR BIT DATA, BINARY,
-and VARCHAR FOR BIT DATA types also work.</li>
-<li>Use the SQL CLOB type for storage; LONG VARCHAR, CHAR, and VARCHAR types
-also work.</li>
-<li>Use the <i>getBlob</i> or <i>getClob</i> methods on the <i>java.sql.ResultSet</i> interface
-to retrieve a <i>BLOB</i> or <i>CLOB</i> handle to the underlying data.</li>
-<li>You cannot call static methods on any LOB-columns.</li>
+CLOB (character large object) type. BLOB and CLOB objects are collectively
+referred to as LOBs (large objects).</p></section>
+<section><p>The <ph conref="../conrefs.dita#prod/productshortname"></ph>
+implementation of the <i>java.sql.Blob</i> and <i>java.sql.Clob</i> interfaces
+is LOCATOR-based, meaning that the implementation provides a logical pointer to
+a LOB rather than a complete copy of the object. Also,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> does not materialize a
+LOB when you use the BLOB or CLOB data type. You can, however, call methods on
+a <i>java.sql.Blob</i> and <i>java.sql.Clob</i> object to materialize it
+(that is, to retrieve the entire object or parts of it).</p></section>
+<section><p><ph conref="../conrefs.dita#prod/productshortname"></ph> implements
+all of the methods for these interfaces except for the <i>setBlob</i>,
+<i>getBlob</i>, <i>setClob</i>, and <i>getClob</i> methods of the
+<i>CallableStatement</i> interface.</p></section>
+<section><p>To use the <i>java.sql.Blob</i> and <i>java.sql.Clob</i> features: <ul>
+<li>Use the SQL BLOB type for columns which hold very large binary values.</li>
+<li>Use the SQL CLOB type for columns which hold very large string values.</li>
+<li>Use the <i>getBlob</i> and <i>getClob</i> methods of the
+<i>java.sql.ResultSet</i> interface to retrieve a LOB using its locator.
+You can then materialize all or part of the LOB by calling <i>Blob</i> and
+<i>Clob</i> methods. Alternatively, you can call the <i>ResultSet.getBytes</i>
+method to materialize a BLOB, and you can call the <i>ResultSet.getString</i>
+method to materialize a CLOB.</li>
</ul></p></section>
-<section><p>In addition, casting between strings and BLOBs is not recommended
-because casting is platform and database dependent. </p></section>
-<section><p><ph conref="../conrefs.dita#prod/productshortname"></ph> uses
-unicode strings (2 byte characters), while other database products may use
-ASCII characters (1 byte per character). If various codepages are used, each
-character might need several bytes. A larger BLOB type might be necessary
-to accommodate a normal string in <ph conref="../conrefs.dita#prod/productshortname"></ph>.
-You should use CLOB types for storing strings. </p></section>
-<section><p><b>Restrictions on BLOB, CLOB, (LOB-types):</b> <ul>
-<li>LOB-types cannot be compared for equality(=) and non-equality(!=, <>. </li>
-<li>LOB-typed values are not order-able, so <, <=, >, >= tests
+<section><p>Casting between strings and BLOBs is not recommended
+because casting is platform- and database-dependent. </p></section>
+<section><p>As with other character datatypes,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> treats CLOBs as unicode
+strings and writes them to disk using UTF8 encoding. With a Java database like
+<ph conref="../conrefs.dita#prod/productshortname"></ph>, you do not need to
+worry about character sets and codepages.</p></section>
+<section><title>Restrictions on BLOB and CLOB objects (LOB-types)</title><p><ul>
+<li>LOB-types cannot be compared for equality (=) and non-equality (!=, <>).</li>
+<li>LOB-typed values are not orderable, so <, <=, >, >= tests
are not supported.</li>
<li>LOB-types cannot be used in indices or as primary key columns.</li>
-<li>DISTINCT, GROUP BY, ORDER BY clauses are also prohibited on LOB-types. </li>
+<li>DISTINCT, GROUP BY, and ORDER BY clauses are also prohibited on LOB-types.</li>
<li>LOB-types cannot be involved in implicit casting as other base-types.</li>
</ul></p></section>
-<section><p><ph conref="../conrefs.dita#prod/productshortname"></ph> implements
-all of the methods for these JDBC 2.0 interfaces except for the set and get
-methods in <i>CallableStatement</i> interface.</p></section>
-<section><p><b>Recommendations:</b> Because the lifespan of a <i>java.sql.Blob</i> or <i>java.sql.Clob</i> ends
+<section><p><b>Recommendation:</b> Because the lifespan of a <i>java.sql.Blob</i> or <i>java.sql.Clob</i> ends
when the transaction commits, turn off auto-commit with the <i>java.sql.Blob</i> or <i>java.sql.Clob</i> features.</p></section>
-<section><p> <table frame="all" pgwide="1"><title>JDBC 2.0 java.sql.Blob Methods
-Supported</title>
+<table frame="all"><title>Implementation Notes on <i>java.sql.Blob</i> Methods</title>
<tgroup cols="3" colsep="1" rowsep="1"><colspec colname="1" colnum="1" colwidth="13*"/>
<colspec colname="2" colnum="2" colwidth="32*"/><colspec colname="3" colnum="3"
colwidth="55*"/>
@@ -89,11 +81,6 @@
</thead>
<tbody>
<row>
-<entry colname="1"><i>InputStream</i></entry>
-<entry colname="2"><i>getBinaryStream()</i></entry>
-<entry colname="3"></entry>
-</row>
-<row>
<entry colname="1"><i>byte[]</i></entry>
<entry colname="2"><i>getBytes(long pos, int length)</i></entry>
<entry colname="3">Exceptions are raised if <i>pos</i> < 1, if <i>pos</i> is
@@ -101,11 +88,6 @@
</row>
<row>
<entry colname="1"><i>long</i></entry>
-<entry colname="2"><i>length()</i></entry>
-<entry colname="3"></entry>
-</row>
-<row>
-<entry colname="1"><i>long</i></entry>
<entry colname="2"><i>position(byte[] pattern, long start)</i></entry>
<entry colname="3">Exceptions are raised if <i>pattern</i> == null, if <i>start</i> <
1, or if <i>pattern</i> is an array of length 0. </entry>
@@ -119,8 +101,8 @@
</row>
</tbody>
</tgroup>
-</table> <table frame="all" pgwide="1"><title>JDBC 2.0 java.sql.Clob Methods
-Supported</title>
+</table>
+<table frame="all"><title>Implementation Notes on <i>java.sql.Clob</i> Methods</title>
<tgroup cols="3" colsep="1" rowsep="1"><colspec colname="1" colnum="1" colwidth="14*"/>
<colspec colname="2" colnum="2" colwidth="36*"/><colspec colname="3" colnum="3"
colwidth="50*"/>
@@ -133,16 +115,6 @@
</thead>
<tbody>
<row>
-<entry colname="1"><i>InputStream</i></entry>
-<entry colname="2"><i>getAsciiStream()</i></entry>
-<entry colname="3"></entry>
-</row>
-<row>
-<entry colname="1"><i>Reader</i></entry>
-<entry colname="2"><i>getCharacterStream()</i></entry>
-<entry colname="3"></entry>
-</row>
-<row>
<entry colname="1"><i>String</i></entry>
<entry colname="2"><i>getSubString(long pos, int length)</i></entry>
<entry colname="3">Exceptions are raised if <i>pos</i> < 1, if <i>pos</i> is
@@ -150,11 +122,6 @@
</row>
<row>
<entry colname="1"><i>long</i></entry>
-<entry colname="2"><i>length()</i></entry>
-<entry colname="3"></entry>
-</row>
-<row>
-<entry colname="1"><i>long</i></entry>
<entry colname="2"><i>position(Clob searchstr, long start) </i></entry>
<entry colname="3">Exceptions are raised if <i>searchStr</i> == null or <i>start</i> <
1, if <i>searchStr </i>has length 0, or if an exception is thrown when trying
@@ -168,6 +135,6 @@
</row>
</tbody>
</tgroup>
-</table></p></section>
+</table>
</refbody>
</reference>