2802N/A * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * The standard interface that all implementations of a <code>WebRowSet</code> 0N/A * <h3>1.0 Overview</h3> 0N/A * The <code>WebRowSetImpl</code> provides the standard 0N/A * reference implementation, which may be extended if required. 0N/A * The standard WebRowSet XML Schema definition is available at the following 0N/A * It describes the standard XML document format required when describing a 0N/A * <code>RowSet</code> object in XML and must be used be all standard implementations 0N/A * of the <code>WebRowSet</code> interface to ensure interoperability. In addition, 0N/A * the <code>WebRowSet</code> schema uses specific SQL/XML Schema annotations, 0N/A * thus ensuring greater cross 0N/A * platform inter-operability. This is an effort currently under way at the ISO 0N/A * organization. The SQL/XML definition is available at the following URI: 0N/A * The schema definition describes the internal data of a <code>RowSet</code> object 0N/A * in three distinct areas: 0N/A * <li><b>properties</b></li> 0N/A * These properties describe the standard synchronization provider properties in 0N/A * addition to the more general <code>RowSet</code> properties. 0N/A * <li><b>metadata</b></li> 0N/A * This describes the metadata associated with the tabular structure governed by a 0N/A * <code>WebRowSet</code> object. The metadata described is closely aligned with the 0N/A * metadata accessible in the underlying <code>java.sql.ResultSet</code> interface. 0N/A * <li><b>data</b></li> 0N/A * This describes the original data (the state of data since the last population 0N/A * or last synchronization of the <code>WebRowSet</code> object) and the current 0N/A * data. By keeping track of the delta between the original data and the current data, 0N/A * a <code>WebRowSet</code> maintains 0N/A * the ability to synchronize changes in its data back to the originating data source. 0N/A * <h3>2.0 WebRowSet States</h3> 0N/A * The following sections demonstrates how a <code>WebRowSet</code> implementation 0N/A * should use the XML Schema to describe update, insert, and delete operations 0N/A * and to describe the state of a <code>WebRowSet</code> object in XML. 0N/A * <h4>2.1 State 1 - Outputting a <code>WebRowSet</code> Object to XML</h3> 0N/A * In this example, a <code>WebRowSet</code> object is created and populated with a simple 2 column, 0N/A * 5 row table from a data source. Having the 5 rows in a <code>WebRowSet</code> object 0N/A * makes it possible to describe them in XML. The 0N/A * metadata describing the various standard JavaBeans properties as defined 0N/A * in the RowSet interface plus the standard properties defined in 0N/A * the <code>CachedRowSet</code><sup><font size=-2>TM</font></sup> interface 0N/A * provide key details that describe WebRowSet 0N/A * properties. Outputting the WebRowSet object to XML using the standard 0N/A * <code>writeXml</code> methods describes the internal properties as follows: 0N/A * <<font color=red>properties</font>> 0N/A * <<font color=red>command</font>>select co1, col2 from test_table<<font color=red>/command</font>> 0N/A * <<font color=red>concurrency</font>>1<<font color=red>/concurrency</font>> 0N/A * <<font color=red>datasource/</font>> 0N/A * <<font color=red>escape-processing</font>>true<<font color=red>/escape-processing</font>> 0N/A * <<font color=red>fetch-direction</font>>0<<font color=red>/fetch-direction</font>> 0N/A * <<font color=red>fetch-size</font>>0<<font color=red>/fetch-size</font>> 0N/A * <<font color=red>isolation-level</font>>1<<font color=red>/isolation-level</font>> 0N/A * <<font color=red>key-columns/</font>> 0N/A * <<font color=red>map/</font>> 0N/A * <<font color=red>max-field-size</font>>0<<font color=red>/max-field-size</font>> 0N/A * <<font color=red>max-rows</font>>0<<font color=red>/max-rows</font>> 0N/A * <<font color=red>query-timeout</font>>0<<font color=red>/query-timeout</font>> 0N/A * <<font color=red>read-only</font>>false<<font color=red>/read-only</font>> 0N/A * <<font color=red>rowset-type</font>>TRANSACTION_READ_UNCOMMITED<<font color=red>/rowset-type</font>> 0N/A * <<font color=red>show-deleted</font>>false<<font color=red>/show-deleted</font>> 0N/A * <<font color=red>table-name/</font>> 0N/A * <<font color=red>url</font>>jdbc:thin:oracle<<font color=red>/url</font>> 0N/A * <<font color=red>sync-provider</font>> 0N/A * <<font color=red>sync-provider-name</font>>.com.rowset.provider.RIOptimisticProvider<<font color=red>/sync-provider-name</font>> 2802N/A * <<font color=red>sync-provider-vendor</font>>Oracle Corporation<<font color=red>/sync-provider-vendor</font>> 0N/A * <<font color=red>sync-provider-version</font>>1.0<<font color=red>/sync-provider-name</font>> 0N/A * <<font color=red>sync-provider-grade</font>>LOW<<font color=red>/sync-provider-grade</font>> 0N/A * <<font color=red>data-source-lock</font>>NONE<<font color=red>/data-source-lock</font>> 0N/A * <<font color=red>/sync-provider</font>> 0N/A * <<font color=red>/properties</font>> 0N/A * The meta-data describing the make up of the WebRowSet is described 0N/A * in XML as detailed below. Note both columns are described between the 0N/A * <code>column-definition</code> tags. 0N/A * <<font color=red>metadata</font>> 0N/A * <<font color=red>column-count</font>>2<<font color=red>/column-count</font>> 0N/A * <<font color=red>column-definition</font>> 0N/A * <<font color=red>column-index</font>>1<<font color=red>/column-index</font>> 0N/A * <<font color=red>auto-increment</font>>false<<font color=red>/auto-increment</font>> 0N/A * <<font color=red>case-sensitive</font>>true<<font color=red>/case-sensitive</font>> 0N/A * <<font color=red>currency</font>>false<<font color=red>/currency</font>> 0N/A * <<font color=red>nullable</font>>1<<font color=red>/nullable</font>> 0N/A * <<font color=red>signed</font>>false<<font color=red>/signed</font>> 0N/A * <<font color=red>searchable</font>>true<<font color=red>/searchable</font>> 0N/A * <<font color=red>column-display-size</font>>10<<font color=red>/column-display-size</font>> 0N/A * <<font color=red>column-label</font>>COL1<<font color=red>/column-label</font>> 0N/A * <<font color=red>column-name</font>>COL1<<font color=red>/column-name</font>> 0N/A * <<font color=red>schema-name/</font>> 0N/A * <<font color=red>column-precision</font>>10<<font color=red>/column-precision</font>> 0N/A * <<font color=red>column-scale</font>>0<<font color=red>/column-scale</font>> 0N/A * <<font color=red>table-name/</font>> 0N/A * <<font color=red>catalog-name/</font>> 0N/A * <<font color=red>column-type</font>>1<<font color=red>/column-type</font>> 0N/A * <<font color=red>column-type-name</font>>CHAR<<font color=red>/column-type-name</font>> 0N/A * <<font color=red>/column-definition</font>> 0N/A * <<font color=red>column-definition</font>> 0N/A * <<font color=red>column-index</font>>2<<font color=red>/column-index</font>> 0N/A * <<font color=red>auto-increment</font>>false<<font color=red>/auto-increment</font>> 0N/A * <<font color=red>case-sensitive</font>>false<<font color=red>/case-sensitive</font>> 0N/A * <<font color=red>currency</font>>false<<font color=red>/currency</font>> 0N/A * <<font color=red>nullable</font>>1<<font color=red>/nullable</font>> 0N/A * <<font color=red>signed</font>>true<<font color=red>/signed</font>> 0N/A * <<font color=red>searchable</font>>true<<font color=red>/searchable</font>> 0N/A * <<font color=red>column-display-size</font>>39<<font color=red>/column-display-size</font>> 0N/A * <<font color=red>column-label</font>>COL2<<font color=red>/column-label</font>> 0N/A * <<font color=red>column-name</font>>COL2<<font color=red>/column-name</font>> 0N/A * <<font color=red>schema-name/</font>> 0N/A * <<font color=red>column-precision</font>>38<<font color=red>/column-precision</font>> 0N/A * <<font color=red>column-scale</font>>0<<font color=red>/column-scale</font>> 0N/A * <<font color=red>table-name/</font>> 0N/A * <<font color=red>catalog-name/</font>> 0N/A * <<font color=red>column-type</font>>3<<font color=red>/column-type</font>> 0N/A * <<font color=red>column-type-name</font>>NUMBER<<font color=red>/column-type-name</font>> 0N/A * <<font color=red>/column-definition</font>> 0N/A * <<font color=red>/metadata</font>> 0N/A * Having detailed how the properties and metadata are described, the following details 0N/A * how the contents of a <code>WebRowSet</code> object is described in XML. Note, that 0N/A * this describes a <code>WebRowSet</code> object that has not undergone any 0N/A * modifications since its instantiation. 0N/A * A <code>currentRow</code> tag is mapped to each row of the table structure that the 0N/A * <code>WebRowSet</code> object provides. A <code>columnValue</code> tag may contain 0N/A * either the <code>stringData</code> or <code>binaryData</code> tag, according to 0N/A * the XML value is mapping back to. The <code>binaryData</code> tag contains data in the 0N/A * Base64 encoding and is typically used for <code>BLOB</code> and <code>CLOB</code> type data. 0N/A * <<font color=red>data</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>/data</font>> 0N/A * <h4>2.2 State 2 - Deleting a Row</h4> 0N/A * Deleting a row in a <code>WebRowSet</code> object involves simply moving to the row 0N/A * to be deleted and then calling the method <code>deleteRow</code>, as in any other 0N/A * <code>RowSet</code> object. The following 0N/A * two lines of code, in which <i>wrs</i> is a <code>WebRowSet</code> object, delete 0N/A * The XML description shows the third row is marked as a <code>deleteRow</code>, 0N/A * which eliminates the third row in the <code>WebRowSet</code> object. 0N/A * <<font color=red>data</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>deleteRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/deleteRow</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>/data</font>> 0N/A * <h4>2.3 State 3 - Inserting a Row</h4> 0N/A * A <code>WebRowSet</code> object can insert a new row by moving to the insert row, 0N/A * calling the appropriate updater methods for each column in the row, and then 0N/A * calling the method <code>insertRow</code>. 0N/A * wrs.moveToInsertRow(); 0N/A * wrs.updateString(1, "fifththrow"); 0N/A * wrs.updateString(2, "5"); 0N/A * The following code fragment changes the second column value in the row just inserted. 0N/A * Note that this code applies when new rows are inserted right after the current row, 0N/A * which is why the method <code>next</code> moves the cursor to the correct row. 0N/A * Calling the method <code>acceptChanges</code> writes the change to the data source. 0N/A * wrs.moveToCurrentRow(); 0N/A * wrs.updateString(2, "V"); 0N/A * wrs.acceptChanges(); 0N/A * Describing this in XML demonstrates where the Java code inserts a new row and then 0N/A * performs an update on the newly inserted row on an individual field. 0N/A * <<font color=red>data</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>insertRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>updateValue</font>> 0N/A * <<font color=red>/updateValue</font>> 0N/A * <<font color=red>/insertRow</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>/date</font>> 0N/A * <h4>2.4 State 4 - Modifying a Row</h4> 0N/A * Modifying a row produces specific XML that records both the new value and the 0N/A * value that was replaced. The value that was replaced becomes the original value, 0N/A * and the new value becomes the current value. The following 0N/A * code moves the cursor to a specific row, performs some modifications, and updates 0N/A * the row when complete. 0N/A * wrs.updateString(1, "new4thRow"); 0N/A * wrs.updateString(2, "IV"); 0N/A * In XML, this is described by the <code>modifyRow</code> tag. Both the original and new 0N/A * values are contained within the tag for original row tracking purposes. 0N/A * <<font color=red>data</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>currentRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>/currentRow</font>> 0N/A * <<font color=red>modifyRow</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>updateValue</font>> 0N/A * <<font color=red>/updateValue</font>> 0N/A * <<font color=red>columnValue</font>> 0N/A * <<font color=red>/columnValue</font>> 0N/A * <<font color=red>updateValue</font>> 0N/A * <<font color=red>/updateValue</font>> 0N/A * <<font color=red>/modifyRow</font>> 0N/A * <<font color=red>/data</font>> 0N/A * @see javax.sql.rowset.JdbcRowSet 0N/A * @see javax.sql.rowset.CachedRowSet 0N/A * @see javax.sql.rowset.FilteredRowSet 0N/A * @see javax.sql.rowset.JoinRowSet 0N/A * Reads a <code>WebRowSet</code> object in its XML format from the given 0N/A * <code>Reader</code> object. 0N/A * @param reader the <code>java.io.Reader</code> stream from which this 0N/A * <code>WebRowSet</code> object will be populated 0N/A * @throws SQLException if a database access error occurs 0N/A * Reads a stream based XML input to populate this <code>WebRowSet</code> 0N/A * @param iStream the <code>java.io.InputStream</code> from which this 0N/A * <code>WebRowSet</code> object will be populated 0N/A * @throws SQLException if a data source access error occurs 0N/A * @throws IOException if an IO exception occurs 0N/A * Populates this <code>WebRowSet</code> object with 0N/A * the contents of the given <code>ResultSet</code> object and writes its 0N/A * data, properties, and metadata 0N/A * to the given <code>Writer</code> object in XML format. 0N/A * NOTE: The <code>WebRowSet</code> cursor may be moved to write out the 0N/A * contents to the XML data source. If implemented in this way, the cursor <b>must</b> 0N/A * be returned to its position just prior to the <code>writeXml()</code> call. 0N/A * @param rs the <code>ResultSet</code> object with which to populate this 0N/A * <code>WebRowSet</code> object 0N/A * @param writer the <code>java.io.Writer</code> object to write to. 0N/A * @throws SQLException if an error occurs writing out the rowset 0N/A * contents in XML format 0N/A * Populates this <code>WebRowSet</code> object with 0N/A * the contents of the given <code>ResultSet</code> object and writes its 0N/A * data, properties, and metadata 0N/A * to the given <code>OutputStream</code> object in XML format. 0N/A * NOTE: The <code>WebRowSet</code> cursor may be moved to write out the 0N/A * contents to the XML data source. If implemented in this way, the cursor <b>must</b> 0N/A * be returned to its position just prior to the <code>writeXml()</code> call. 0N/A * @param rs the <code>ResultSet</code> object with which to populate this 0N/A * <code>WebRowSet</code> object 0N/A * @param oStream the <code>java.io.OutputStream</code> to write to 0N/A * @throws SQLException if a data source access error occurs 0N/A * @throws IOException if a IO exception occurs 0N/A * Writes the data, properties, and metadata for this <code>WebRowSet</code> object 0N/A * to the given <code>Writer</code> object in XML format. 0N/A * @param writer the <code>java.io.Writer</code> stream to write to 0N/A * @throws SQLException if an error occurs writing out the rowset 0N/A * Writes the data, properties, and metadata for this <code>WebRowSet</code> object 0N/A * to the given <code>OutputStream</code> object in XML format. 0N/A * @param oStream the <code>java.io.OutputStream</code> stream to write to 0N/A * @throws SQLException if a data source access error occurs 0N/A * @throws IOException if a IO exception occurs 0N/A * The public identifier for the XML Schema definition that defines the XML 0N/A * tags and their valid values for a <code>WebRowSet</code> implementation. 2802N/A "--//Oracle Corporation//XSD Schema//EN";
0N/A * The URL for the XML Schema definition file that defines the XML tags and 0N/A * their valid values for a <code>WebRowSet</code> implementation.