/*
 * @(#)WebRowSet.java	1.7 06/04/07
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN 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</code>
 * must implement. 
 * <P>
 * <h3>1.0 Overview</h3>
 * The <code>WebRowSetImpl</code> 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>
 * <pre>
 * <a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd">http://java.sun.com/xml/ns/jdbc/webrowset.xsd</a>
 * </pre>
 * </ul>
 * It describes the standard XML document format required when describing a
 * <code>RowSet</code> object in XML and must be used be all standard implementations 
 * of the <code>WebRowSet</code> interface to ensure interoperability. In addition, 
 * the <code>WebRowSet</code> 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>
 * <pre>
 * <a href="http://standards.iso.org/iso/9075/2002/12/sqlxml">http://standards.iso.org/iso/9075/2002/12/sqlxml</a>

 * </pre>
 * </ul>
 * The schema definition describes the internal data of a <code>RowSet</code> object
 * in three distinct areas:
 * <UL>
 * <li><b>properties</b></li>
 * These properties describe the standard synchronization provider properties in
 * addition to the more general <code>RowSet</code> properties.
 * <p>
 * <li><b>metadata</b></li>
 * This describes the metadata associated with the tabular structure governed by a
 * <code>WebRowSet</code> object. The metadata described is closely aligned with the
 * metadata accessible in the underlying <code>java.sql.ResultSet</code> interface.
 * <p>
 * <li><b>data</b></li>
 * This describes the original data (the state of data since the last population 
 * or last synchronization of the <code>WebRowSet</code> object) and the current 
 * data. By keeping track of the delta between the original data and the current data, 
 * a <code>WebRowSet</code> maintains
 * the ability to synchronize changes in its data back to the originating data source.
 * </ul>
 * <P>
 * <h3>2.0 WebRowSet States</h3>
 * The following sections demonstrates how a <code>WebRowSet</code> implementation
 * should use the XML Schema to describe update, insert, and delete operations 
 * and to describe the state of a <code>WebRowSet</code> object in XML. 
 * <p>
 * <h4>2.1 State 1 - Outputting a <code>WebRowSet</code> Object to XML</h3>
 * In this example, a <code>WebRowSet</code> 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</code> 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</code><sup><font size=-2>TM</font></sup> interface 
 * provide key details that describe WebRowSet
 * properties. Outputting the WebRowSet object to XML using the standard 
 * <code>writeXml</code> methods describes the internal properties as follows:
 * <PRE>
 * <<font color=red>properties</font>>
 *       <<font color=red>command</font>>select co1, col2 from test_table<<font color=red>/command</font>>

 *	<<font color=red>concurrency</font>>1<<font color=red>/concurrency</font>>
 *	<<font color=red>datasource/</font>>
 *	<<font color=red>escape-processing</font>>true<<font color=red>/escape-processing</font>>
 *	<<font color=red>fetch-direction</font>>0<<font color=red>/fetch-direction</font>>
 *	<<font color=red>fetch-size</font>>0<<font color=red>/fetch-size</font>>
 *	<<font color=red>isolation-level</font>>1<<font color=red>/isolation-level</font>>
 *	<<font color=red>key-columns/</font>>
 *	<<font color=red>map/</font>>
 *	<<font color=red>max-field-size</font>>0<<font color=red>/max-field-size</font>>
 *	<<font color=red>max-rows</font>>0<<font color=red>/max-rows</font>>
 *	<<font color=red>query-timeout</font>>0<<font color=red>/query-timeout</font>>
 *	<<font color=red>read-only</font>>false<<font color=red>/read-only</font>>
 *	<<font color=red>rowset-type</font>>TRANSACTION_READ_UNCOMMITED<<font color=red>/rowset-type</font>>

 *	<<font color=red>show-deleted</font>>false<<font color=red>/show-deleted</font>>
 *	<<font color=red>table-name/</font>>
 *	<<font color=red>url</font>>jdbc:thin:oracle<<font color=red>/url</font>>
 *	<<font color=red>sync-provider</font>>
 *		<<font color=red>sync-provider-name</font>>.com.rowset.provider.RIOptimisticProvider<<font 
color=red>/sync-provider-name</font>>
 *		<<font color=red>sync-provider-vendor</font>>Sun Microsystems<<font color=red>/sync-provider-vendor</font>>