|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
*/ |
|
|
|
package javax.sql.rowset; |
|
|
|
import java.sql.*; |
|
import javax.sql.*; |
|
import javax.naming.*; |
|
import java.io.*; |
|
import java.math.*; |
|
import org.xml.sax.*; |
|
|
|
/** |
|
* The standard interface that all implementations of a {@code WebRowSet} |
|
* must implement. |
|
* |
|
* <h2>1.0 Overview</h2> |
|
* The {@code WebRowSetImpl} provides the standard |
|
* reference implementation, which may be extended if required. |
|
* <P> |
|
* The standard WebRowSet XML Schema definition is available at the following |
|
* URI: |
|
* <ul> |
|
* <li> |
|
* <a href="http://xmlns.jcp.org/xml/ns//jdbc/webrowset.xsd">http://xmlns.jcp.org/xml/ns//jdbc/webrowset.xsd</a> |
|
* </li> |
|
* </ul> |
|
* It describes the standard XML document format required when describing a |
|
* {@code RowSet} object in XML and must be used be all standard implementations |
|
* of the {@code WebRowSet} interface to ensure interoperability. In addition, |
|
* the {@code WebRowSet} schema uses specific SQL/XML Schema annotations, |
|
* thus ensuring greater cross |
|
* platform interoperability. This is an effort currently under way at the ISO |
|
* organization. The SQL/XML definition is available at the following URI: |
|
* <ul> |
|
* <li> |
|
* <a href="http://standards.iso.org/iso/9075/2002/12/sqlxml.xsd">http://standards.iso.org/iso/9075/2002/12/sqlxml.xsd</a> |
|
* </li> |
|
* </ul> |
|
* The schema definition describes the internal data of a {@code RowSet} object |
|
* in three distinct areas: |
|
* <UL> |
|
* <li>properties - These properties describe the standard synchronization |
|
* provider properties in addition to the more general {@code RowSet} properties. |
|
* </li> |
|
* <li>metadata - This describes the metadata associated with the tabular structure governed by a |
|
* {@code WebRowSet} object. The metadata described is closely aligned with the |
|
* metadata accessible in the underlying {@code java.sql.ResultSet} interface. |
|
* </li> |
|
* <li>data - This describes the original data (the state of data since the |
|
* last population |
|
* or last synchronization of the {@code WebRowSet} object) and the current |
|
* data. By keeping track of the delta between the original data and the current data, |
|
* a {@code WebRowSet} maintains the ability to synchronize changes |
|
* in its data back to the originating data source. |
|
* </li> |
|
* </ul> |
|
* |
|
* <h2>2.0 WebRowSet States</h2> |
|
* The following sections demonstrates how a {@code WebRowSet} implementation |
|
* should use the XML Schema to describe update, insert, and delete operations |
|
* and to describe the state of a {@code WebRowSet} object in XML. |
|
* |
|
* <h2>2.1 State 1 - Outputting a {@code WebRowSet} Object to XML</h2> |
|
* In this example, a {@code WebRowSet} object is created and populated with a simple 2 column, |
|
* 5 row table from a data source. Having the 5 rows in a {@code WebRowSet} object |
|
* makes it possible to describe them in XML. The |
|
* metadata describing the various standard JavaBeans properties as defined |
|
* in the RowSet interface plus the standard properties defined in |
|
* the {@code CachedRowSet} interface |
|
* provide key details that describe WebRowSet |
|
* properties. Outputting the WebRowSet object to XML using the standard |
|
* {@code writeXml} methods describes the internal properties as follows: |
|
* <PRE> |
|
* {@code |
|
* <properties> |
|
* <command>select co1, col2 from test_table</command> |
|
* <concurrency>1</concurrency> |
|
* <datasource/> |
|
* <escape-processing>true</escape-processing> |
|
* <fetch-direction>0</fetch-direction> |
|
* <fetch-size>0</fetch-size> |
|
* <isolation-level>1</isolation-level> |
|
* <key-columns/> |
|
* <map/> |
|
* <max-field-size>0</max-field-size> |
|
* <max-rows>0</max-rows> |
|
* <query-timeout>0</query-timeout> |
|
* <read-only>false</read-only> |
|
* <rowset-type>TRANSACTION_READ_UNCOMMITTED</rowset-type> |
|
* <show-deleted>false</show-deleted> |
|
* <table-name/> |
|
* <url>jdbc:thin:oracle</url> |
|
* <sync-provider> |
|
* <sync-provider-name>.com.rowset.provider.RIOptimisticProvider</sync-provider-name> |
|
* <sync-provider-vendor>Oracle Corporation</sync-provider-vendor> |
|
* <sync-provider-version>1.0</sync-provider-name> |
|
* <sync-provider-grade>LOW</sync-provider-grade> |
|
* <data-source-lock>NONE</data-source-lock> |
|
* </sync-provider> |
|
* </properties> |
|
* } </PRE> |
|
* The meta-data describing the make up of the WebRowSet is described |
|
* in XML as detailed below. Note both columns are described between the |
|
* {@code column-definition} tags. |
|
* <PRE> |
|
* {@code |
|
* <metadata> |
|
* <column-count>2</column-count> |
|
* <column-definition> |
|
* <column-index>1</column-index> |
|
* <auto-increment>false</auto-increment> |
|
* <case-sensitive>true</case-sensitive> |
|
* <currency>false</currency> |
|
* <nullable>1</nullable> |
|
* <signed>false</signed> |
|
* <searchable>true</searchable> |
|
* <column-display-size>10</column-display-size> |
|
* <column-label>COL1</column-label> |
|
* <column-name>COL1</column-name> |
|
* <schema-name/> |
|
* <column-precision>10</column-precision> |
|
* <column-scale>0</column-scale> |
|
* <table-name/> |
|
* <catalog-name/> |
|
* <column-type>1</column-type> |
|
* <column-type-name>CHAR</column-type-name> |
|
* </column-definition> |
|
* <column-definition> |
|
* <column-index>2</column-index> |
|
* <auto-increment>false</auto-increment> |
|
* <case-sensitive>false</case-sensitive> |
|
* <currency>false</currency> |
|
* <nullable>1</nullable> |
|
* <signed>true</signed> |
|
* <searchable>true</searchable> |
|
* <column-display-size>39</column-display-size> |
|
* <column-label>COL2</column-label> |
|
* <column-name>COL2</column-name> |
|
* <schema-name/> |
|
* <column-precision>38</column-precision> |
|
* <column-scale>0</column-scale> |
|
* <table-name/> |
|
* <catalog-name/> |
|
* <column-type>3</column-type> |
|
* <column-type-name>NUMBER</column-type-name> |
|
* </column-definition> |
|
* </metadata> |
|
* }</PRE> |
|
* Having detailed how the properties and metadata are described, the following details |
|
* how the contents of a {@code WebRowSet} object is described in XML. Note, that |
|
* this describes a {@code WebRowSet} object that has not undergone any |
|
* modifications since its instantiation. |
|
* A {@code currentRow} tag is mapped to each row of the table structure that the |
|
* {@code WebRowSet} object provides. A {@code columnValue} tag may contain |
|
* either the {@code stringData} or {@code binaryData} tag, according to |
|
* the SQL type that |
|
* the XML value is mapping back to. The {@code binaryData} tag contains data in the |
|
* Base64 encoding and is typically used for {@code BLOB} and {@code CLOB} type data. |
|
* <PRE> |
|
* {@code |
|
* <data> |
|
* <currentRow> |
|
* <columnValue> |
|
* firstrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 1 |
|
* </columnValue> |
|
* </currentRow> |
|
* <currentRow> |
|
* <columnValue> |
|
* secondrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 2 |
|
* </columnValue> |
|
* </currentRow> |
|
* <currentRow> |
|
* <columnValue> |
|
* thirdrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 3 |
|
* </columnValue> |
|
* </currentRow> |
|
* <currentRow> |
|
* <columnValue> |
|
* fourthrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 4 |
|
* </columnValue> |
|
* </currentRow> |
|
* </data> |
|
* }</PRE> |
|
* <h2>2.2 State 2 - Deleting a Row</h2> |
|
* Deleting a row in a {@code WebRowSet} object involves simply moving to the row |
|
* to be deleted and then calling the method {@code deleteRow}, as in any other |
|
* {@code RowSet} object. The following |
|
* two lines of code, in which <i>wrs</i> is a {@code WebRowSet} object, delete |
|
* the third row. |
|
* <PRE> |
|
* wrs.absolute(3); |
|
* wrs.deleteRow(); |
|
* </PRE> |
|
* The XML description shows the third row is marked as a {@code deleteRow}, |
|
* which eliminates the third row in the {@code WebRowSet} object. |
|
* <PRE> |
|
* {@code |
|
* <data> |
|
* <currentRow> |
|
* <columnValue> |
|
* firstrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 1 |
|
* </columnValue> |
|
* </currentRow> |
|
* <currentRow> |
|
* <columnValue> |
|
* secondrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 2 |
|
* </columnValue> |
|
* </currentRow> |
|
* <deleteRow> |
|
* <columnValue> |
|
* thirdrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 3 |
|
* </columnValue> |
|
* </deleteRow> |
|
* <currentRow> |
|
* <columnValue> |
|
* fourthrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 4 |
|
* </columnValue> |
|
* </currentRow> |
|
* </data> |
|
*} </PRE> |
|
* <h2>2.3 State 3 - Inserting a Row</h2> |
|
* A {@code WebRowSet} object can insert a new row by moving to the insert row, |
|
* calling the appropriate updater methods for each column in the row, and then |
|
* calling the method {@code insertRow}. |
|
* <PRE> |
|
* {@code |
|
* wrs.moveToInsertRow(); |
|
* wrs.updateString(1, "fifththrow"); |
|
* wrs.updateString(2, "5"); |
|
* wrs.insertRow(); |
|
* }</PRE> |
|
* The following code fragment changes the second column value in the row just inserted. |
|
* Note that this code applies when new rows are inserted right after the current row, |
|
* which is why the method {@code next} moves the cursor to the correct row. |
|
* Calling the method {@code acceptChanges} writes the change to the data source. |
|
* |
|
* <PRE> |
|
* {@code wrs.moveToCurrentRow(); |
|
* wrs.next(); |
|
* wrs.updateString(2, "V"); |
|
* wrs.acceptChanges(); |
|
* }</PRE> |
|
* Describing this in XML demonstrates where the Java code inserts a new row and then |
|
* performs an update on the newly inserted row on an individual field. |
|
* <PRE> |
|
* {@code |
|
* <data> |
|
* <currentRow> |
|
* <columnValue> |
|
* firstrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 1 |
|
* </columnValue> |
|
* </currentRow> |
|
* <currentRow> |
|
* <columnValue> |
|
* secondrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 2 |
|
* </columnValue> |
|
* </currentRow> |
|
* <currentRow> |
|
* <columnValue> |
|
* newthirdrow |
|
* </columnValue> |
|
* <columnValue> |
|
* III |
|
* </columnValue> |
|
* </currentRow> |
|
* <insertRow> |
|
* <columnValue> |
|
* fifthrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 5 |
|
* </columnValue> |
|
* <updateValue> |
|
* V |
|
* </updateValue> |
|
* </insertRow> |
|
* <currentRow> |
|
* <columnValue> |
|
* fourthrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 4 |
|
* </columnValue> |
|
* </currentRow> |
|
* </date> |
|
*} </PRE> |
|
* <h2>2.4 State 4 - Modifying a Row</h2> |
|
* Modifying a row produces specific XML that records both the new value and the |
|
* value that was replaced. The value that was replaced becomes the original value, |
|
* and the new value becomes the current value. The following |
|
* code moves the cursor to a specific row, performs some modifications, and updates |
|
* the row when complete. |
|
* <PRE> |
|
*{@code |
|
* wrs.absolute(5); |
|
* wrs.updateString(1, "new4thRow"); |
|
* wrs.updateString(2, "IV"); |
|
* wrs.updateRow(); |
|
* }</PRE> |
|
* In XML, this is described by the {@code modifyRow} tag. Both the original and new |
|
* values are contained within the tag for original row tracking purposes. |
|
* <PRE> |
|
* {@code |
|
* <data> |
|
* <currentRow> |
|
* <columnValue> |
|
* firstrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 1 |
|
* </columnValue> |
|
* </currentRow> |
|
* <currentRow> |
|
* <columnValue> |
|
* secondrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 2 |
|
* </columnValue> |
|
* </currentRow> |
|
* <currentRow> |
|
* <columnValue> |
|
* newthirdrow |
|
* </columnValue> |
|
* <columnValue> |
|
* III |
|
* </columnValue> |
|
* </currentRow> |
|
* <currentRow> |
|
* <columnValue> |
|
* fifthrow |
|
* </columnValue> |
|
* <columnValue> |
|
* 5 |
|
* </columnValue> |
|
* </currentRow> |
|
* <modifyRow> |
|
* <columnValue> |
|
* fourthrow |
|
* </columnValue> |
|
* <updateValue> |
|
* new4thRow |
|
* </updateValue> |
|
* <columnValue> |
|
* 4 |
|
* </columnValue> |
|
* <updateValue> |
|
* IV |
|
* </updateValue> |
|
* </modifyRow> |
|
* </data> |
|
* }</PRE> |
|
* |
|
* @see javax.sql.rowset.JdbcRowSet |
|
* @see javax.sql.rowset.CachedRowSet |
|
* @see javax.sql.rowset.FilteredRowSet |
|
* @see javax.sql.rowset.JoinRowSet |
|
* @since 1.5 |
|
*/ |
|
|
|
public interface WebRowSet extends CachedRowSet { |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
*/ |
|
public void readXml(java.io.Reader reader) throws SQLException; |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
*/ |
|
public void readXml(java.io.InputStream iStream) throws SQLException, IOException; |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
*/ |
|
public void writeXml(ResultSet rs, java.io.Writer writer) throws SQLException; |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
*/ |
|
public void writeXml(ResultSet rs, java.io.OutputStream oStream) throws SQLException, IOException; |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
*/ |
|
public void writeXml(java.io.Writer writer) throws SQLException; |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
*/ |
|
public void writeXml(java.io.OutputStream oStream) throws SQLException, IOException; |
|
|
|
|
|
|
|
|
|
*/ |
|
public static String PUBLIC_XML_SCHEMA = |
|
"--//Oracle Corporation//XSD Schema//EN"; |
|
|
|
|
|
|
|
|
|
*/ |
|
public static String SCHEMA_SYSTEM_ID = "http://java.sun.com/xml/ns/jdbc/webrowset.xsd"; |
|
} |