/*
 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

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.
 *
 * <h3>1.0 Overview</h3>
 * 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://java.sun.com/xml/ns/jdbc/webrowset.xsd">http://java.sun.com/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 inter-operability. 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">http://standards.iso.org/iso/9075/2002/12/sqlxml</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>
 *
 * <h3>2.0 WebRowSet States</h3>
 * 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.
 *
 * <h4>2.1 State 1 - Outputting a {@code WebRowSet} Object to XML</h4>
 * 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}&trade; 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_UNCOMMITED</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>
 * <h4>2.2 State 2 - Deleting a Row</h4>
 * 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>
 * <h4>2.3 State 3 - Inserting a Row</h4>
 * 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>
 * <h4>2.4 State 4 - Modifying a Row</h4>
 * 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
 */

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.
 * <p>
 * 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 <b>must</b>
 * 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.
 * <p>
 * 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 <b>must</b>
 * 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";
}