* The standard WebRowSet XML Schema definition is available at the following * URI: *
* 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: * * The schema definition describes the internal data of a {@code RowSet} object * in three distinct areas: *
* {@code
*
* select co1, col2 from test_table
* 1
* true
* 0
* 0
* 1
* 0
* 0
* 0
* false
* TRANSACTION_READ_UNCOMMITTED
* false
* jdbc:thin:oracle
*
* .com.rowset.provider.RIOptimisticProvider
* Oracle Corporation
* 1.0
* LOW
* NONE
*
*
* }
* 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.
*
* {@code
*
* 2
*
* 1
* false
* true
* false
* 1
* false
* true
* 10
* COL1
* COL1
* 10
* 0
* 1
* CHAR
*
*
* 2
* false
* false
* false
* 1
* true
* true
* 39
* COL2
* COL2
* 38
* 0
* 3
* NUMBER
*
*
* }
* 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.
*
* {@code
*
*
*
* firstrow
*
*
* 1
*
*
*
*
* secondrow
*
*
* 2
*
*
*
*
* thirdrow
*
*
* 3
*
*
*
*
* fourthrow
*
*
* 4
*
*
*
* }
* * wrs.absolute(3); * wrs.deleteRow(); ** The XML description shows the third row is marked as a {@code deleteRow}, * which eliminates the third row in the {@code WebRowSet} object. *
* {@code
*
*
*
* firstrow
*
*
* 1
*
*
*
*
* secondrow
*
*
* 2
*
*
*
*
* thirdrow
*
*
* 3
*
*
*
*
* fourthrow
*
*
* 4
*
*
*
*}
*
* {@code
* wrs.moveToInsertRow();
* wrs.updateString(1, "fifththrow");
* wrs.updateString(2, "5");
* wrs.insertRow();
* }
* 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.
*
*
* {@code wrs.moveToCurrentRow();
* wrs.next();
* wrs.updateString(2, "V");
* wrs.acceptChanges();
* }
* 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.
*
* {@code
*
*
*
* firstrow
*
*
* 1
*
*
*
*
* secondrow
*
*
* 2
*
*
*
*
* newthirdrow
*
*
* III
*
*
*
*
* fifthrow
*
*
* 5
*
*
* V
*
*
*
*
* fourthrow
*
*
* 4
*
*
*
*}
*
*{@code
* wrs.absolute(5);
* wrs.updateString(1, "new4thRow");
* wrs.updateString(2, "IV");
* wrs.updateRow();
* }
* 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.
*
* {@code
*
*
*
* firstrow
*
*
* 1
*
*
*
*
* secondrow
*
*
* 2
*
*
*
*
* newthirdrow
*
*
* III
*
*
*
*
* fifthrow
*
*
* 5
*
*
*
*
* fourthrow
*
*
* new4thRow
*
*
* 4
*
*
* IV
*
*
*
* }
*
* @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 {
/**
* Reads a {@code WebRowSet} object in its XML format from the given
* {@code Reader} object.
*
* @param reader the {@code java.io.Reader} stream from which this
* {@code WebRowSet} object will be populated
* @throws SQLException if a database access error occurs
*/
public void readXml(java.io.Reader reader) throws SQLException;
/**
* Reads a stream based XML input to populate this {@code WebRowSet}
* object.
*
* @param iStream the {@code java.io.InputStream} from which this
* {@code WebRowSet} object will be populated
* @throws SQLException if a data source access error occurs
* @throws IOException if an IO exception occurs
*/
public void readXml(java.io.InputStream iStream) throws SQLException, IOException;
/**
* Populates this {@code WebRowSet} object with
* the contents of the given {@code ResultSet} object and writes its
* data, properties, and metadata
* to the given {@code Writer} object in XML format.
* * NOTE: The {@code WebRowSet} cursor may be moved to write out the * contents to the XML data source. If implemented in this way, the cursor must * be returned to its position just prior to the {@code writeXml()} call. * * @param rs the {@code ResultSet} object with which to populate this * {@code WebRowSet} object * @param writer the {@code java.io.Writer} object to write to. * @throws SQLException if an error occurs writing out the rowset * contents in XML format */ public void writeXml(ResultSet rs, java.io.Writer writer) throws SQLException; /** * Populates this {@code WebRowSet} object with * the contents of the given {@code ResultSet} object and writes its * data, properties, and metadata * to the given {@code OutputStream} object in XML format. *
* NOTE: The {@code WebRowSet} cursor may be moved to write out the * contents to the XML data source. If implemented in this way, the cursor must * be returned to its position just prior to the {@code writeXml()} call. * * @param rs the {@code ResultSet} object with which to populate this * {@code WebRowSet} object * @param oStream the {@code java.io.OutputStream} to write to * @throws SQLException if a data source access error occurs * @throws IOException if a IO exception occurs */ public void writeXml(ResultSet rs, java.io.OutputStream oStream) throws SQLException, IOException; /** * Writes the data, properties, and metadata for this {@code WebRowSet} object * to the given {@code Writer} object in XML format. * * @param writer the {@code java.io.Writer} stream to write to * @throws SQLException if an error occurs writing out the rowset * contents to XML */ public void writeXml(java.io.Writer writer) throws SQLException; /** * Writes the data, properties, and metadata for this {@code WebRowSet} object * to the given {@code OutputStream} object in XML format. * * @param oStream the {@code java.io.OutputStream} stream to write to * @throws SQLException if a data source access error occurs * @throws IOException if a IO exception occurs */ public void writeXml(java.io.OutputStream oStream) throws SQLException, IOException; /** * The public identifier for the XML Schema definition that defines the XML * tags and their valid values for a {@code WebRowSet} implementation. */ public static String PUBLIC_XML_SCHEMA = "--//Oracle Corporation//XSD Schema//EN"; /** * The URL for the XML Schema definition file that defines the XML tags and * their valid values for a {@code WebRowSet} implementation. */ public static String SCHEMA_SYSTEM_ID = "http://java.sun.com/xml/ns/jdbc/webrowset.xsd"; }