changeset 50847:db65921e9a9b

8201608: fix broken links in javax/sql/rowset/package.html and javax/sql/rowset/spi/package.html Reviewed-by: rriggs, psandoz
author lancea
date Thu, 07 Jun 2018 06:27:09 -0400
parents 8e56de95ce10
children bd6b78feb6a3
files src/java.sql.rowset/share/classes/javax/sql/rowset/package-info.java src/java.sql.rowset/share/classes/javax/sql/rowset/package.html src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package-info.java src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package.html
diffstat 4 files changed, 766 insertions(+), 790 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.sql.rowset/share/classes/javax/sql/rowset/package-info.java	Thu Jun 07 06:27:09 2018 -0400
@@ -0,0 +1,286 @@
+/*
+ * Copyright (c)  2017, 2018, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * Standard interfaces and base classes for JDBC <code>RowSet</code>
+ * implementations. This package contains interfaces and classes
+ * that a standard <code>RowSet</code> implementation either implements or extends.
+ *
+ * <h2>Table of Contents</h2>
+ * <ul>
+ * <li><a href="#pkgspec">1.0 Package Specification</a>
+ * <li><a href="#stdrowset">2.0 Standard RowSet Definitions</a>
+ * <li><a href="#impl">3.0 Implementer's Guide</a>
+ * <li><a href="#relspec">4.0 Related Specifications</a>
+ * <li><a href="#reldocs">5.0 Related Documentation</a>
+ * </ul>
+ *
+ * <h3><a id="pkgspec">1.0 Package Specification</a></h3>
+ * This package specifies five standard JDBC <code>RowSet</code> interfaces.
+ * All five extend the
+ * <a href="{@docRoot}/java.sql/javax/sql/RowSet.html">RowSet</a> interface described in the JDBC 3.0
+ * specification.  It is anticipated that additional definitions
+ * of more specialized JDBC <code>RowSet</code> types will emerge as this technology
+ * matures. Future definitions <i>should</i> be specified as subinterfaces using
+ * inheritance similar to the way it is used in this specification.
+ * <p>
+ * <i>Note:</i> The interface definitions provided in this package form the basis for
+ * all compliant JDBC <code>RowSet</code> implementations. Vendors and more advanced
+ * developers who intend to provide their own compliant <code>RowSet</code> implementations
+ * should pay particular attention to the assertions detailed in specification
+ * interfaces.
+ *
+ * <h3><a id="stdrowset">2.0 Standard RowSet Definitions</a></h3>
+ * <ul>
+ * <li><a href="JdbcRowSet.html"><b><code>JdbcRowSet</code></b></a> - A wrapper around
+ * a <code>ResultSet</code> object that makes it possible to use the result set as a
+ * JavaBeans&trade; component. Thus,
+ * a <code>JdbcRowSet</code> object can be a Bean that any tool
+ * makes available for assembling an application as part of a component based
+ * architecture. A <code>JdbcRowSet</code> object is a connected <code>RowSet</code>
+ * object, that is, it
+ * <b>must</b> continually maintain its connection to its data source using a JDBC
+ * technology-enabled driver ("JDBC driver"). In addition, a <code>JdbcRowSet</code>
+ * object provides a fully updatable and scrollable tabular
+ * data structure as defined in the JDBC 3.0 specification.
+ *
+ * <li><a href="CachedRowSet.html">
+ * <b><code>CachedRowSet</code>&trade;</b></a>
+ *  - A <code>CachedRowSet</code> object is a JavaBeans&trade;
+ * component that is scrollable, updatable, serializable, and generally disconnected from
+ * the source of its data. A <code>CachedRowSet</code> object
+ * typically contains rows from a result set, but it can also contain rows from any
+ * file with a tabular format, such as a spreadsheet. <code>CachedRowSet</code> implementations
+ * <b>must</b> use the <code>SyncFactory</code> to manage and obtain pluggable
+ * <code>SyncProvider</code> objects to provide synchronization between the
+ * disconnected <code>RowSet</code> object and the originating data source.
+ * Typically a <code>SyncProvider</code> implementation relies upon a JDBC
+ * driver to obtain connectivity to a particular data source.
+ * Further details on this mechanism are discussed in the <a
+ * href="spi/package-summary.html"><code>javax.sql.rowset.spi</code></a> package
+ * specification.
+ *
+ * <li><a href="WebRowSet.html"><b><code>WebRowSet</code></b></a> - A
+ * <code>WebRowSet</code> object is an extension of <code>CachedRowSet</code>
+ * that can read and write a <code>RowSet</code> object in a well formed XML format.
+ * This class calls an <a href="spi/XmlReader.html"><code>XmlReader</code></a> object
+ * (an extension of the <a href="{@docRoot}/java.sql/javax/sql/RowSetReader.html"><code>RowSetReader</code></a>
+ * interface) to read a rowset in XML format. It calls an
+ * <a href="spi/XmlWriter.html"><code>XmlWriter</code></a> object (an extension of the
+ * <a href="{@docRoot}/java.sql/javax/sql/RowSetWriter.html"><code>RowSetWriter</code></a> interface)
+ * to write a rowset in XML format. The reader and writer required by
+ * <code>WebRowSet</code> objects are provided by the
+ * <code>SyncFactory</code> in the form of <code>SyncProvider</code>
+ * implementations. In order to ensure well formed XML usage, a standard generic XML
+ * Schema is defined and published at
+ * <a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd">
+ * <code>http://java.sun.com/xml/ns/jdbc/webrowset.xsd</code></a>.
+ *
+ * <li><a href="FilteredRowSet.html"><b><code>FilteredRowSet</code></b></a> - A
+ * <code>FilteredRowSet</code> object provides filtering functionality in a programmatic
+ * and extensible way. There are many instances when a <code>RowSet</code> <code>object</code>
+ * has a need to provide filtering in its contents without sacrificing the disconnected
+ * environment, thus saving the expense of having to create a connection to the data source.
+ * Solutions to this need vary from providing heavyweight full scale
+ * SQL query abilities, to portable components, to more lightweight
+ * approaches. A <code>FilteredRowSet</code> object consumes
+ * an implementation of the <a href="Predicate.html"><code>Predicate</code></a>
+ * interface, which <b>may</b> define a filter at run time. In turn, a
+ * <code>FilteredRowSet</code> object is tasked with enforcing the set filter for both
+ * inbound and outbound read and write operations. That is, all filters can be
+ * considered as bi-directional. No standard filters are defined;
+ * however, sufficient mechanics are specified to permit any required filter to be
+ * implemented.
+ *
+ * <li><a href="JoinRowSet.html"><b><code>JoinRowSet</code></b></a> - The <code>JoinRowSet</code>
+ * interface  describes a mechanism by which relationships can be established between
+ * two or more standard <code>RowSet</code> implementations. Any number of <code>RowSet</code>
+ * objects can be added to a <code>JoinRowSet</code> object provided  the <code>RowSet</code>objects
+ * can be related  in a SQL <code>JOIN</code> like fashion. By definition, the SQL <code>JOIN</code>
+ * statement  is used to combine the data contained in two (<i>or more</i>) relational
+ * database tables based upon a common attribute. By establishing and then enforcing
+ * column matches, a <code>JoinRowSet</code> object establishes relationships between
+ * <code>RowSet</code> instances without the need to touch the originating data source.
+ * </ul>
+ *
+ * <h3><a id="impl">3.0 Implementer's Guide</a></h3>
+ * Compliant implementations of JDBC <code>RowSet</code> Implementations
+ * <b>must</b> follow the assertions described in this specification. In accordance
+ * with the terms of the <a href="http://www.jcp.org">Java Community Process</a>, a
+ * Test Compatibility Kit (TCK) can be licensed to ensure compatibility with the
+ * specification. The following paragraphs outline a number of starting points for
+ * implementers of the standard JDBC <code>RowSet</code> definitions. Implementers
+ * should also consult the <i>Implementer's Guide</i> in the <a
+ * href="spi/package-summary.html">javax.sql.rowset.spi</a> package for guidelines
+ * on <a href="spi/SyncProvider.html"><code>SyncProvider</code></a> implementations.
+ *
+ * <ul>
+ * <li><b>3.1 Constructor</b>
+ * <p>
+ *   All <code>RowSet</code> implementations <strong>must</strong> provide a
+ * no-argument constructor.
+ * </li>
+ * <li><b>3.2 Role of the <code>BaseRowSet</code> Class</b>
+ * <p>
+ * A compliant JDBC <code>RowSet</code> implementation <b>must</b> implement one or more
+ * standard interfaces specified in this package and <b>may</b> extend the
+ * <a href="BaseRowSet.html"><code>BaseRowSet</code></a> abstract class. For example, a
+ * <code>CachedRowSet</code> implementation must implement the <code>CachedRowSet</code>
+ * interface and extend the <code>BaseRowSet</code> abstract class. The
+ * <code>BaseRowSet</code> class provides the standard architecture on which all
+ * <code>RowSet</code> implementations should be built, regardless of whether the
+ * <code>RowSet</code> objects exist in a connected or disconnected environment.
+ * The <code>BaseRowSet</code> abstract class provides any <code>RowSet</code> implementation
+ * with its base functionality, including property manipulation and event notification
+ * that is fully compliant with <a href="http://java.sun.com/products/javabeans">JavaBeans</a>
+ * component requirements. As an example, all implementations provided in the
+ * reference implementations (contained in the <code>com.sun.rowset</code> package) use
+ * the <code>BaseRowSet</code> class as a basis for their implementations.
+ * <P>
+ * The following table illustrates the features that the <code>BaseRowSet</code>
+ * abstract class provides.
+ * <blockquote>
+ *   <table class="striped" style="vertical-align:top; width:75%">
+ *     <caption>Features in <code>BaseRowSet</code></caption>
+ *         <thead>
+ *           <tr>
+ *             <th scope="col">Feature</th>
+ *             <th scope="col">Details</th>
+ *           </tr>
+ *         </thead>
+ *         <tbody>
+ *           <tr>
+ *             <th scope="row">Properties</th>
+ *             <td>Provides standard JavaBeans property manipulation
+ * mechanisms to allow applications to get and set <code>RowSet</code> command and
+ * property  values. Refer to the   documentation of the <code>javax.sql.RowSet</code>
+ * interface  (available in the JDBC 3.0 specification) for more details on
+ * the standard  <code>RowSet</code> properties.</td>
+ *           </tr>
+ *           <tr>
+ *             <th scope="row">Event notification</th>
+ *             <td>Provides standard JavaBeans event notifications
+ * to registered event listeners. Refer to the documentation of <code>javax.sql.RowSetEvent</code>
+ * interface (available in the JDBC 3.0 specification) for
+ * more details on how  to register and handle standard RowSet events generated
+ * by  compliant implementations.</td>
+ *           </tr>
+ *           <tr>
+ *             <th scope="row">Setters for a RowSet object's command</th>
+ *             <td>Provides a complete set of setter methods
+ *                for setting RowSet command parameters.</td>
+ *           </tr>
+ *           <tr>
+ *             <th scope="row">Streams</th>
+ *             <td>Provides fields for storing of stream instances
+ * in addition to providing a set of constants for stream type designation.</td>
+ *           </tr>
+ *     </tbody>
+ *   </table>
+ *   </blockquote>
+ *
+ * <li><b>3.3 Connected RowSet Requirements</b>
+ * <p>
+ * The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> always
+ * be connected to the originating data source. Implementations of the <code>JdbcRowSet</code>
+ * should ensure that this connection is provided solely by a JDBC driver.
+ * Furthermore, <code>RowSet</code> objects that are implementations of the
+ * <code>JdbcRowSet</code> interface and are therefore operating in a connected environment
+ * do not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> object
+ * or a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver to
+ * supply their needs by virtue of the presence of an underlying updatable and scrollable
+ * <code>ResultSet</code> implementation.
+ *
+ * <li>
+ * <b>3.4 Disconnected RowSet Requirements</b>
+ * <p>
+ * A disconnected <code>RowSet</code> object, such as a <code>CachedRowSet</code> object,
+ * <b>should</b> delegate
+ * connection management to a <code>SyncProvider</code> object provided by the
+ * <code>SyncFactory</code>. To ensure fully disconnected semantics, all
+ * disconnected <code>RowSet</code> objects <b>must</b> ensure
+ * that the original connection made to the data source to populate the <code>RowSet</code>
+ * object is closed to permit the garbage collector to recover and release resources. The
+ * <code>SyncProvider</code> object ensures that the critical JDBC properties are
+ * maintained in order to re-establish a connection to the data source when a
+ * synchronization is required. A disconnected <code>RowSet</code> object should
+ * therefore ensure that no
+ * extraneous references remain on the <code>Connection</code> object.
+ *
+ * <li><b>3.5 Role of RowSetMetaDataImpl</b>
+ * <p>
+ * The <code>RowsetMetaDataImpl</code> class is a utility class that provides an implementation of the
+ * <a href="{@docRoot}/java.sql/javax/sql/RowSetMetaData.html">RowSetMetaData</a> interface, supplying standard setter
+ * method implementations for metadata for both connected and disconnected
+ * <code>RowSet</code> objects. All implementations are free to use this standard
+ * implementation but are not required to do so.
+ *
+ * <li><b>3.6 RowSetWarning Class</b>
+ * <p>
+ * The <code>RowSetWarning</code> class provides warnings that can be set
+ * on <code>RowSet</code> implementations.
+ * Similar to <a href="{@docRoot}/java.sql/java/sql/SQLWarning.html">SQLWarning</a> objects,
+ * <code>RowSetWarning</code>  objects are silently chained to the object whose method
+ * caused the warning to be thrown. All <code>RowSet</code> implementations <b>should</b>
+ * ensure that this chaining occurs if a warning is generated and also ensure that the
+ * warnings are available via the <code>getRowSetWarnings</code> method defined in either
+ * the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code> interface.
+ * After a warning has been retrieved with one of the
+ * <code>getRowSetWarnings</code> methods, the <code>RowSetWarning</code> method
+ * <code>getNextWarning</code> can be called on it to retrieve any warnings that might
+ * be chained on it.  If a warning is returned, <code>getNextWarning</code> can be called
+ * on it, and so on until there are no more warnings.
+ *
+ * <li><b>3.7 The Joinable Interface</b>
+ * <P>
+ * The <code>Joinable</code> interface provides both connected and disconnected
+ * <code>RowSet</code> objects with the capability to be added to a
+ * <code>JoinRowSet</code> object in an SQL <code>JOIN</code> operation.
+ * A <code>RowSet</code> object that has  implemented the <code>Joinable</code>
+ * interface can set a match column, retrieve a match column, or unset a match column.
+ * A <code>JoinRowSet</code> object can then use the <code>RowSet</code> object's
+ * match column as a basis for adding the <code>RowSet</code> object.
+ * </li>
+ *
+ * <li><b>3.8 The RowSetFactory Interface</b>
+ *   <p>
+ *       A <code>RowSetFactory</code> implementation <strong>must</strong>
+ *       be provided.
+ * </li>
+ * </ul>
+ *
+ * <h3><a id="relspec">4.0 Related Specifications</a></h3>
+ * <ul>
+ * <li><a href="https://jcp.org/en/jsr/detail?id=221">JDBC 4.3 Specification</a>
+ * <li><a href="http://www.w3.org/XML/Schema">XML Schema</a>
+ * </ul>
+ *
+ * <h3><a id="reldocs">5.0 Related Documentation</a></h3>
+ * <ul>
+ * <li><a href="http://docs.oracle.com/javase/tutorial/jdbc/basics/rowset.html">
+ * JDBC RowSet Tutorial</a>
+ *</ul>
+ */
+package javax.sql.rowset;
--- a/src/java.sql.rowset/share/classes/javax/sql/rowset/package.html	Thu Jun 07 12:23:46 2018 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,297 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-
-  <meta http-equiv="Content-Type"
- content="text/html; charset=iso-8859-1">
-<!--
-Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
-DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
-
-This code is free software; you can redistribute it and/or modify it
-under the terms of the GNU General Public License version 2 only, as
-published by the Free Software Foundation.  Oracle designates this
-particular file as subject to the "Classpath" exception as provided
-by Oracle in the LICENSE file that accompanied this code.
-
-This code is distributed in the hope that it will be useful, but WITHOUT
-ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-version 2 for more details (a copy is included in the LICENSE file that
-accompanied this code).
-
-You should have received a copy of the GNU General Public License version
-2 along with this work; if not, write to the Free Software Foundation,
-Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-
-Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
-or visit www.oracle.com if you need additional information or have any
-questions.
-
--->
-  <title>javax.sql.rowset Package</title>
-</head>
-  <body>
-
-<!-- Description clause -->
-Standard interfaces and base classes for JDBC <code>RowSet</code>
-implementations. This package contains interfaces and classes 
-that a standard <code>RowSet</code> implementation either implements or extends.
-
-
-<h2>Table of Contents</h2>
-<ul>
-<li><a href="#pkgspec">1.0 Package Specification</a>
-<li><a href="#stdrowset">2.0 Standard RowSet Definitions</a>
-<li><a href="#impl">3.0 Implementer's Guide</a>
-<li><a href="#relspec">4.0 Related Specifications</a>
-<li><a href="#reldocs">5.0 Related Documentation</a>
-</ul>
-
-<h3><a id="pkgspec">1.0 Package Specification</a></h3>
-This package specifies five standard JDBC <code>RowSet</code> interfaces.
- All five extend the 
-<a href="../RowSet.html">RowSet</a> interface described in the JDBC 3.0
-specification.  It is anticipated that additional definitions
-of more specialized JDBC <code>RowSet</code> types will emerge as this technology
-matures. Future definitions <i>should</i> be specified as subinterfaces using
-inheritance similar to the way it is used in this specification.
-<p>
-<i>Note:</i> The interface definitions provided in this package form the basis for
-all compliant JDBC <code>RowSet</code> implementations. Vendors and more advanced
-developers who intend to provide their own compliant <code>RowSet</code> implementations
-should pay particular attention to the assertions detailed in specification
-interfaces. 
-
-<h3><a id="stdrowset">2.0 Standard RowSet Definitions</a></h3>
-<ul>
-<li><a href="JdbcRowSet.html"><b><code>JdbcRowSet</code></b></a> - A wrapper around
-a <code>ResultSet</code> object that makes it possible to use the result set as a
-JavaBeans&trade; component. Thus,
-a <code>JdbcRowSet</code> object can be a Bean that any tool
-makes available for assembling an application as part of a component based
-architecture. A <code>JdbcRowSet</code> object is a connected <code>RowSet</code>
-object, that is, it 
-<b>must</b> continually maintain its connection to its data source using a JDBC
-technology-enabled driver ("JDBC driver"). In addition, a <code>JdbcRowSet</code>
-object provides a fully updatable and scrollable tabular
-data structure as defined in the JDBC 3.0 specification.
-
-<li><a href="CachedRowSet.html">
-<b><code>CachedRowSet</code>&trade;</b></a>
- - A <code>CachedRowSet</code> object is a JavaBeans&trade;
- component that is scrollable, updatable, serializable, and generally disconnected from
- the source of its data. A <code>CachedRowSet</code> object
-typically contains rows from a result set, but it can also contain rows from any
-file with a tabular format, such as a spreadsheet. <code>CachedRowSet</code> implementations
-<b>must</b> use the <code>SyncFactory</code> to manage and obtain pluggable
-<code>SyncProvider</code> objects to provide synchronization between the
-disconnected <code>RowSet</code> object and the originating data source.
-Typically a <code>SyncProvider</code> implementation relies upon a JDBC
-driver to obtain connectivity to a particular data source.
-Further details on this mechanism are discussed in the <a
-href="spi/package-summary.html"><code>javax.sql.rowset.spi</code></a> package
-specification.
-
-<li><a href="WebRowSet.html"><b><code>WebRowSet</code></b></a> - A 
-<code>WebRowSet</code> object is an extension of <code>CachedRowSet</code>
-that can read and write a <code>RowSet</code> object in a well formed XML format.
-This class calls an <a href="spi/XmlReader.html"><code>XmlReader</code></a> object
-(an extension of the <a href="../RowSetReader.html"><code>RowSetReader</code></a>
-interface) to read a rowset in XML format. It calls an 
-<a href="spi/XmlWriter.html"><code>XmlWriter</code></a> object (an extension of the
-<a href="../RowSetWriter.html"><code>RowSetWriter</code></a> interface)
-to write a rowset in XML format. The reader and writer required by
-<code>WebRowSet</code> objects are provided by the
-<code>SyncFactory</code> in the form of <code>SyncProvider</code>
-implementations. In order to ensure well formed XML usage, a standard generic XML
-Schema is defined and published at
-<a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd">
-<code>http://java.sun.com/xml/ns/jdbc/webrowset.xsd</code></a>.
-
-<li><a href="FilteredRowSet.html"><b><code>FilteredRowSet</code></b></a> - A
-<code>FilteredRowSet</code> object provides filtering functionality in a programmatic
-and extensible way. There are many instances when a <code>RowSet</code> <code>object</code>
-has a need to provide filtering in its contents without sacrificing the disconnected
-environment, thus saving the expense of having to create a connection to the data source.
-Solutions to this need vary from providing heavyweight full scale 
-SQL query abilities, to portable components, to more lightweight 
-approaches. A <code>FilteredRowSet</code> object consumes
-an implementation of the <a href="Predicate.html"><code>Predicate</code></a>
-interface, which <b>may</b> define a filter at run time. In turn, a
-<code>FilteredRowSet</code> object is tasked with enforcing the set filter for both
-inbound and outbound read and write operations. That is, all filters can be
-considered as bi-directional. No standard filters are defined;
-however, sufficient mechanics are specified to permit any required filter to be
-implemented.
-
-<li><a href="JoinRowSet.html"><b><code>JoinRowSet</code></b></a> - The <code>JoinRowSet</code>
-interface  describes a mechanism by which relationships can be established between
-two or more standard <code>RowSet</code> implementations. Any number of <code>RowSet</code>
- objects can be added to a <code>JoinRowSet</code> object provided  the <code>RowSet</code>objects
-can be related  in a SQL <code>JOIN</code> like fashion. By definition, the SQL <code>JOIN</code>
-statement  is used to combine the data contained in two (<i>or more</i>) relational
-database tables based upon a common attribute. By establishing and then enforcing
-column matches, a <code>JoinRowSet</code> object establishes relationships between
-<code>RowSet</code> instances without the need to touch the originating data source.
-</ul>
-
-<h3><a id="impl">3.0 Implementer's Guide</a></h3>
-Compliant implementations of JDBC <code>RowSet</code> Implementations
-<b>must</b> follow the assertions described in this specification. In accordance
-with the terms of the <a href="http://www.jcp.org">Java Community Process</a>, a
-Test Compatibility Kit (TCK) can be licensed to ensure compatibility with the
-specification. The following paragraphs outline a number of starting points for
-implementers of the standard JDBC <code>RowSet</code> definitions. Implementers
-should also consult the <i>Implementer's Guide</i> in the <a
-href="spi/package-summary.html">javax.sql.rowset.spi</a> package for guidelines
-on <a href="spi/SyncProvider.html"><code>SyncProvider</code></a> implementations.
-
-<ul>
-<li><b>3.1 Constructor</b>
-<p>
-    All <code>RowSet</code> implementations <strong>must</strong> provide a
-no-argument constructor.
-</li>
-<li><b>3.2 Role of the <code>BaseRowSet</code> Class</b>
-<p>
-A compliant JDBC <code>RowSet</code> implementation <b>must</b> implement one or more
-standard interfaces specified in this package and <b>may</b> extend the
-<a href="BaseRowSet.html"><code>BaseRowSet</code></a> abstract class. For example, a
-<code>CachedRowSet</code> implementation must implement the <code>CachedRowSet</code>
-interface and extend the <code>BaseRowSet</code> abstract class. The
-<code>BaseRowSet</code> class provides the standard architecture on which all
-<code>RowSet</code> implementations should be built, regardless of whether the
-<code>RowSet</code> objects exist in a connected or disconnected environment.
-The <code>BaseRowSet</code> abstract class provides any <code>RowSet</code> implementation
-with its base functionality, including property manipulation and event notification
-that is fully compliant with <a href="http://java.sun.com/products/javabeans">JavaBeans</a>
-component requirements. As an example, all implementations provided in the
-reference implementations (contained in the <code>com.sun.rowset</code> package) use
-the <code>BaseRowSet</code> class as a basis for their implementations.
-<P>
-The following table illustrates the features that the <code>BaseRowSet</code>
-abstract class provides.
-  <blockquote>
-    <table class="striped" style="vertical-align:top; width:75%">
-	<caption>Features in <code>BaseRowSet</code></caption>
-          <thead>
-            <tr>
-              <th scope="col">Feature</th>
-              <th scope="col">Details</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <th scope="row">Properties</th>
-              <td>Provides standard JavaBeans property manipulation
-mechanisms to allow applications to get and set <code>RowSet</code> command and
-property  values. Refer to the   documentation of the <code>javax.sql.RowSet</code>
-interface  (available in the JDBC 3.0 specification) for more details on
-the standard  <code>RowSet</code> properties.</td>
-            </tr>
-            <tr>
-              <th scope="row">Event notification</th>
-              <td>Provides standard JavaBeans event notifications
-to registered event listeners. Refer to the documentation of <code>javax.sql.RowSetEvent</code>
-interface (available in the JDBC 3.0 specification) for
-more details on how  to register and handle standard RowSet events generated
-by  compliant implementations.</td>
-            </tr>
-            <tr>
-              <th scope="row">Setters for a RowSet object's command</th>
-              <td>Provides a complete set of setter methods
-                 for setting RowSet command parameters.</td>
-            </tr>
-            <tr>
-              <th scope="row">Streams</th>
-              <td>Provides fields for storing of stream instances
-  in addition to providing a set of constants for stream type designation.</td>
-            </tr>
-      </tbody>
-    </table>
-    </blockquote>
-
-<li><b>3.3 Connected RowSet Requirements</b>
-<p>
-The <code>JdbcRowSet</code> describes a <code>RowSet</code> object that <b>must</b> always
-be connected to the originating data source. Implementations of the <code>JdbcRowSet</code>
-should ensure that this connection is provided solely by a JDBC driver.
-Furthermore, <code>RowSet</code> objects that are implementations of the
-<code>JdbcRowSet</code> interface and are therefore operating in a connected environment
-do not use the <code>SyncFactory</code> to obtain a <code>RowSetReader</code> object
-or a <code>RowSetWriter</code> object. They can safely rely on the JDBC driver to
-supply their needs by virtue of the presence of an underlying updatable and scrollable
-<code>ResultSet</code> implementation.
-
-<li>
-<b>3.4 Disconnected RowSet Requirements</b>
-<p> 
-A disconnected <code>RowSet</code> object, such as a <code>CachedRowSet</code> object,
-<b>should</b> delegate  
-connection management to a <code>SyncProvider</code> object provided by the
-<code>SyncFactory</code>. To ensure fully disconnected semantics, all
-disconnected <code>RowSet</code> objects <b>must</b> ensure
-that the original connection made to the data source to populate the <code>RowSet</code>
-object is closed to permit the garbage collector to recover and release resources. The
-<code>SyncProvider</code> object ensures that the critical JDBC properties are
-maintained in order to re-establish a connection to the data source when a
-synchronization is required. A disconnected <code>RowSet</code> object should
-therefore ensure that no
-extraneous references remain on the <code>Connection</code> object.
-
-<li><b>3.5 Role of RowSetMetaDataImpl</b>
-<p>
-The <code>RowsetMetaDataImpl</code> class is a utility class that provides an implementation of the
-<a href="../RowSetMetaData.html">RowSetMetaData</a> interface, supplying standard setter
-method implementations for metadata for both connected and disconnected
-<code>RowSet</code> objects. All implementations are free to use this standard
-implementation but are not required to do so.
-
-<li><b>3.6 RowSetWarning Class</b>
-<p>
-The <code>RowSetWarning</code> class provides warnings that can be set
-on <code>RowSet</code> implementations.
-Similar to <a href="../../../java/sql/SQLWarning.html">SQLWarning</a> objects,
-<code>RowSetWarning</code>  objects are silently chained to the object whose method
-caused the warning to be thrown. All <code>RowSet</code> implementations <b>should</b>
-ensure that this chaining occurs if a warning is generated and also ensure that the
-warnings are available via the <code>getRowSetWarnings</code> method defined in either
-the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code> interface.
-After a warning has been retrieved with one of the
-<code>getRowSetWarnings</code> methods, the <code>RowSetWarning</code> method
-<code>getNextWarning</code> can be called on it to retrieve any warnings that might
-be chained on it.  If a warning is returned, <code>getNextWarning</code> can be called
-on it, and so on until there are no more warnings.
-
-<li><b>3.7 The Joinable Interface</b>
-<P>
-The <code>Joinable</code> interface provides both connected and disconnected
-<code>RowSet</code> objects with the capability to be added to a
-<code>JoinRowSet</code> object in an SQL <code>JOIN</code> operation.
-A <code>RowSet</code> object that has  implemented the <code>Joinable</code>
-interface can set a match column, retrieve a match column, or unset a match column.
-A <code>JoinRowSet</code> object can then use the <code>RowSet</code> object's
-match column as a basis for adding the <code>RowSet</code> object.
-</li>
-
-<li><b>3.8 The RowSetFactory Interface</b>
-    <p>
-        A <code>RowSetFactory</code> implementation <strong>must</strong>
-        be provided.
-</li>
-</ul>
-
-<h3><a id="relspec">4.0 Related Specifications</a></h3>
-<ul>
-<li><a href="https://jcp.org/en/jsr/detail?id=221">JDBC 4.3 Specification</a>
-<li><a href="http://www.w3.org/XML/Schema">XML Schema</a>
-</ul>
-
-<h3><a id="reldocs">5.0 Related Documentation</a></h3>
-<ul>
-<li><a href="http://docs.oracle.com/javase/tutorial/jdbc/basics/rowset.html">
-JDBC RowSet Tutorial</a>
-</ul>
-</body>
-</html>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package-info.java	Thu Jun 07 06:27:09 2018 -0400
@@ -0,0 +1,480 @@
+/*
+ * Copyright (c)  2003, 2018, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * The standard classes and interfaces that a third party vendor has to
+ * use in its implementation of a synchronization provider. These classes and
+ * interfaces are referred to as the Service Provider Interface (SPI).  To make it possible
+ * for a <code>RowSet</code> object to use an implementation, the vendor must register
+ * it with the <code>SyncFactory</code> singleton. (See the class comment for
+ * <code>SyncProvider</code> for a full explanation of the registration process and
+ * the naming convention to be used.)
+ *
+ * <h2>Table of Contents</h2>
+ * <ul>
+ * <li><a href="#pkgspec">1.0 Package Specification</a>
+ * <li><a href="#arch">2.0 Service Provider Architecture</a>
+ * <li><a href="#impl">3.0 Implementer's Guide</a>
+ * <li><a href="#resolving">4.0 Resolving Synchronization Conflicts</a>
+ * <li><a href="#relspec">5.0 Related Specifications</a>
+ * <li><a href="#reldocs">6.0 Related Documentation</a>
+ * </ul>
+ *
+ * <h3><a id="pkgspec">1.0 Package Specification</a></h3>
+ * <P>
+ * The following classes and interfaces make up the <code>javax.sql.rowset.spi</code>
+ * package:
+ * <UL>
+ *  <LI><code>SyncFactory</code>
+ *  <LI><code>SyncProvider</code>
+ *  <LI><code>SyncFactoryException</code>
+ *  <LI><code>SyncProviderException</code>
+ *  <LI><code>SyncResolver</code>
+ *  <LI><code>XmlReader</code>
+ *  <LI><code>XmlWriter</code>
+ *  <LI><code>TransactionalWriter</code>
+ * </UL>
+ * The following interfaces, in the <code>javax.sql</code> package, are also part of the SPI:
+ * <UL>
+ *  <LI><code>RowSetReader</code>
+ *  <LI><code>RowSetWriter</code>
+ * </UL>
+ * <P>
+ * A <code>SyncProvider</code> implementation provides a disconnected <code>RowSet</code>
+ * object with the mechanisms for reading data into it and for writing data that has been
+ * modified in it
+ * back to the underlying data source.  A <i>reader</i>, a <code>RowSetReader</code> or
+ * <code>XMLReader</code> object, reads data into a <code>RowSet</code> object when the
+ * <code>CachedRowSet</code> methods <code>execute</code> or <code>populate</code>
+ * are called.  A <i>writer</i>, a <code>RowSetWriter</code> or <code>XMLWriter</code>
+ * object, writes changes back to the underlying data source when the
+ * <code>CachedRowSet</code> method <code>acceptChanges</code> is called.
+ * <P>
+ * The process of writing changes in a <code>RowSet</code> object to its data source
+ * is known as <i>synchronization</i>.  The <code>SyncProvider</code> implementation that a
+ * <code>RowSet</code> object is using determines the level of synchronization that the
+ * <code>RowSet</code> object's writer uses. The various levels of synchronization are
+ * referred to as <i>grades</i>.
+ * <P>
+ * The lower grades of synchronization are
+ * known as <i>optimistic</i> concurrency levels because they optimistically
+ * assume that there will be no conflicts or very few conflicts.  A conflict exists when
+ * the same data modified in the <code>RowSet</code> object has also been modified
+ * in the data source. Using the optimistic concurrency model means that if there
+ * is a conflict, modifications to either the data source or the <code>RowSet</code>
+ * object will be lost.
+ * <P>
+ * Higher grades of synchronization are called <i>pessimistic</i> because they assume
+ * that others will be accessing the data source and making modifications.  These
+ * grades set varying levels of locks to increase the chances that no conflicts
+ * occur.
+ * <P>
+ * The lowest level of synchronization is simply writing any changes made to the
+ * <code>RowSet</code> object to its underlying data source.  The writer does
+ * nothing to check for conflicts.
+ * If there is a conflict and the data
+ * source values are overwritten, the changes other parties have made by to the data
+ * source are lost.
+ * <P>
+ * The <code>RIXMLProvider</code> implementation uses the lowest level
+ * of synchronization and just writes <code>RowSet</code> changes to the data source.
+ *
+ * <P>
+ * For the next level up, the
+ * writer checks to see if there are any conflicts, and if there are,
+ * it does not write anything to the data source.  The problem with this concurrency
+ * level is that if another party has modified the corresponding data in the data source
+ * since the <code>RowSet</code> object got its data,
+ * the changes made to the <code>RowSet</code> object are lost. The
+ * <code>RIOptimisticProvider</code> implementation uses this level of synchronization.
+ * <P>
+ * At higher levels of synchronization, referred to as pessimistic concurrency,
+ * the writer take steps to avoid conflicts by setting locks. Setting locks
+ * can vary from setting a lock on a single row to setting a lock on a table
+ * or the entire data source. The level of synchronization is therefore a tradeoff
+ * between the ability of users to access the data source concurrently and the  ability
+ * of the writer to keep the data in the <code>RowSet</code> object and its data source
+ * synchronized.
+ * <P>
+ * It is a requirement that all disconnected <code>RowSet</code> objects
+ * (<code>CachedRowSet</code>, <code>FilteredRowSet</code>, <code>JoinRowSet</code>,
+ * and <code>WebRowSet</code> objects) obtain their <code>SyncProvider</code> objects
+ * from the <code>SyncFactory</code> mechanism.
+ * <P>
+ * The reference implementation (RI) provides two synchronization providers.
+ *    <UL>
+ *       <LI><b><code>RIOptimisticProvider</code></b> <br>
+ *            The default provider that the <code>SyncFactory</code> instance will
+ *            supply to a disconnected <code>RowSet</code> object when no provider
+ *            implementation is specified.<BR>
+ *            This synchronization provider uses an optimistic concurrency model,
+ *            assuming that there will be few conflicts among users
+ *            who are accessing the same data in a database.  It avoids
+ *            using locks; rather, it checks to see if there is a conflict
+ *            before trying to synchronize the <code>RowSet</code> object and the
+ *            data source. If there is a conflict, it does nothing, meaning that
+ *            changes to the <code>RowSet</code> object are not persisted to the data
+ *            source.
+ *        <LI><B><code>RIXMLProvider</code></B> <BR>
+ *             A synchronization provider that can be used with a
+ *             <code>WebRowSet</code> object, which is a rowset that can be written
+ *             in XML format or read from XML format. The
+ *             <code>RIXMLProvider</code> implementation does no checking at all for
+ *             conflicts and simply writes any updated data in the
+ *             <code>WebRowSet</code> object to the underlying data source.
+ *             <code>WebRowSet</code> objects use this provider when they are
+ *             dealing with XML data.
+ *     </UL>
+ *
+ *  These <code>SyncProvider</code> implementations
+ *  are bundled with the reference implementation, which makes them always available to
+ *  <code>RowSet</code> implementations.
+ *  <code>SyncProvider</code> implementations make themselves available by being
+ *  registered with the <code>SyncFactory</code> singleton.  When a <code>RowSet</code>
+ *  object requests a provider, by specifying it in the constructor or as an argument to the
+ *  <code>CachedRowSet</code> method <code>setSyncProvider</code>,
+ *  the <code>SyncFactory</code> singleton
+ *  checks to see if the requested provider has been registered with it.
+ *  If it has, the <code>SyncFactory</code> creates an instance of it and passes it to the
+ *  requesting <code>RowSet</code> object.
+ *  If the <code>SyncProvider</code> implementation that is specified has not been registered,
+ *  the <code>SyncFactory</code> singleton causes a <code>SyncFactoryException</code> object
+ *  to be thrown.  If no provider is specified,
+ *  the <code>SyncFactory</code> singleton will create an instance of the default
+ *  provider implementation, <code>RIOptimisticProvider</code>,
+ *  and pass it to the requesting <code>RowSet</code> object.
+ *
+ * <P>
+ * If a <code>WebRowSet</code> object does not specify a provider in its constructor, the
+ * <code>SyncFactory</code> will give it an instance of <code>RIOptimisticProvider</code>.
+ * However, the constructor for <code>WebRowSet</code> is implemented to set the provider
+ * to the <code>RIXMLProvider</code>, which reads and writes a <code>RowSet</code> object
+ *  in XML format.
+ *  <P>
+ * See the <a href="SyncProvider.html">SyncProvider</a> class
+ *  specification for further details.
+ * <p>
+ * Vendors may develop a <code>SyncProvider</code> implementation with any one of the possible
+ * levels of synchronization, thus giving <code>RowSet</code> objects a choice of
+ * synchronization mechanisms.
+ *
+ * <h3><a id="arch">2.0 Service Provider Interface Architecture</a></h3>
+ * <b>2.1 Overview</b>
+ * <p>
+ * The Service Provider Interface provides a pluggable mechanism by which
+ * <code>SyncProvider</code> implementations can be registered and then generated when
+ * required. The lazy reference mechanism employed by the <code>SyncFactory</code> limits
+ * unnecessary resource consumption by not creating an instance until it is
+ * required by a disconnected
+ * <code>RowSet</code> object. The <code>SyncFactory</code> class also provides
+ * a standard API to configure logging options and streams that <b>may</b> be provided
+ * by a particular <code>SyncProvider</code> implementation.
+ * <p>
+ * <b>2.2 Registering with the <code>SyncFactory</code></b>
+ * <p>
+ * A third party <code>SyncProvider</code> implementation must be registered with the
+ * <code>SyncFactory</code> in order for a disconnected <code>RowSet</code> object
+ * to obtain it and thereby use its <code>javax.sql.RowSetReader</code> and
+ * <code>javax.sql.RowSetWriter</code>
+ * implementations. The following registration mechanisms are available to all
+ * <code>SyncProvider</code> implementations:
+ * <ul>
+ * <li><b>System properties</b> - Properties set at the command line. These
+ * properties are set at run time and apply system-wide per invocation of the Java
+ * application. See the section <a href="#reldocs">"Related Documentation"</a>
+ * further related information.
+ *
+ * <li><b>Property Files</b> - Properties specified in a standard property file.
+ * This can be specified using a System Property or by modifying a standard
+ * property file located in the platform run-time. The
+ * reference implementation of this technology includes a standard property
+ * file than can be edited to add additional <code>SyncProvider</code> objects.
+ *
+ * <li><b>JNDI Context</b> - Available providers can be registered on a JNDI
+ * context. The <code>SyncFactory</code> will attempt to load <code>SyncProvider</code>
+ * objects bound to the context and register them with the factory. This
+ * context must be supplied to the <code>SyncFactory</code> for the mechanism to
+ * function correctly.
+ * </ul>
+ * <p>
+ * Details on how to specify the system properties or properties in a property file
+ * and how to configure the JNDI Context are explained in detail in the
+ * <a href="SyncFactory.html"><code>SyncFactory</code></a> class description.
+ * <p>
+ * <b>2.3 SyncFactory Provider Instance Generation Policies</b>
+ * <p>
+ * The <code>SyncFactory</code> generates a requested <code>SyncProvider</code>
+ * object if the provider has been correctly registered.  The
+ * following policies are adhered to when either a disconnected <code>RowSet</code> object
+ * is instantiated with a specified <code>SyncProvider</code> implementation or is
+ * reconfigured at runtime with an alternative <code>SyncProvider</code> object.
+ * <ul>
+ * <li> If a <code>SyncProvider</code> object is specified and the <code>SyncFactory</code>
+ * contains <i>no</i> reference to the provider, a <code>SyncFactoryException</code> is
+ * thrown.
+ *
+ * <li> If a <code>SyncProvider</code> object is specified and the <code>SyncFactory</code>
+ * contains a reference to the provider, the requested provider is supplied.
+ *
+ * <li> If no <code>SyncProvider</code> object is specified, the reference
+ * implementation provider <code>RIOptimisticProvider</code> is supplied.
+ * </ul>
+ * <p>
+ * These policies are explored in more detail in the <a href="SyncFactory.html">
+ * <code>SyncFactory</code></a> class.
+ *
+ * <h3><a id="impl">3.0 SyncProvider Implementer's Guide</a></h3>
+ *
+ * <b>3.1 Requirements</b>
+ * <p>
+ * A compliant <code>SyncProvider</code> implementation that is fully pluggable
+ * into the <code>SyncFactory</code> <b>must</b> extend and implement all
+ * abstract methods in the <a href="SyncProvider.html"><code>SyncProvider</code></a>
+ * class. In addition, an implementation <b>must</b> determine the
+ * grade, locking and updatable view capabilities defined in the
+ * <code>SyncProvider</code> class definition. One or more of the
+ * <code>SyncProvider</code> description criteria <b>must</b> be supported. It
+ * is expected that vendor implementations will offer a range of grade, locking, and
+ * updatable view capabilities.
+ * <p>
+ * Furthermore, the <code>SyncProvider</code> naming convention <b>must</b> be followed as
+ * detailed in the <a href="SyncProvider.html"><code>SyncProvider</code></a> class
+ * description.
+ * <p>
+ * <b>3.2 Grades</b>
+ * <p>
+ * JSR 114 defines a set of grades to describe the quality of synchronization
+ * a <code>SyncProvider</code> object can offer a disconnected <code>RowSet</code>
+ * object. These grades are listed from the lowest quality of service to the highest.
+ * <ul>
+ * <li><b>GRADE_NONE</b> - No synchronization with the originating data source is
+ * provided. A <code>SyncProvider</code> implementation returning this grade will simply
+ * attempt to write any data that has changed in the <code>RowSet</code> object to the
+ *underlying data source, overwriting whatever is there. No attempt is made to compare
+ * original values with current values to see if there is a conflict. The
+ * <code>RIXMLProvider</code> is implemented with this grade.
+ *
+ * <li><b>GRADE_CHECK_MODIFIED_AT_COMMIT</b> - A low grade of optimistic synchronization.
+ * A <code>SyncProvider</code> implementation returning this grade
+ * will check for conflicts in rows that have changed between the last synchronization
+ * and the current synchronization under way. Any changes in the originating data source
+ * that have been modified will not be reflected in the disconnected <code>RowSet</code>
+ * object. If there are no conflicts, changes in the <code>RowSet</code> object will be
+ * written to the data source. If there are conflicts, no changes are written.
+ * The <code>RIOptimisticProvider</code> implementation uses this grade.
+ *
+ * <li><b>GRADE_CHECK_ALL_AT_COMMIT</b> - A high grade of optimistic synchronization.
+ * A <code>SyncProvider</code> implementation   returning this grade
+ * will check all rows, including rows that have not changed in the disconnected
+ * <code>RowSet</code> object. In this way, any changes to rows in the underlying
+ * data source will be reflected in the disconnected <code>RowSet</code> object
+ * when the synchronization finishes successfully.
+ *
+ * <li><b>GRADE_LOCK_WHEN_MODIFIED</b> - A pessimistic grade of synchronization.
+ * <code>SyncProvider</code> implementations returning this grade will lock
+ * the row in the originating  data source that corresponds to the row being changed
+ * in the <code>RowSet</code> object to reduce the possibility of other
+ * processes modifying the same data in the data source.
+ *
+ * <li><b>GRADE_LOCK_WHEN_LOADED</b> - A higher pessimistic synchronization grade.
+ * A <code>SyncProvider</code> implementation returning this grade will lock
+ * the entire view and/or  table affected by the original query used to
+ * populate a <code>RowSet</code> object.
+ * </ul>
+ * <p>
+ * <b>3.3 Locks</b>
+ * <p>
+ * JSR 114 defines a set of constants that specify whether any locks have been
+ * placed on a <code>RowSet</code> object's underlying data source and, if so,
+ * on which constructs the locks are placed.  These locks will remain on the data
+ * source while the <code>RowSet</code> object is disconnected from the data source.
+ * <P>
+ * These constants <b>should</b> be considered complementary to the
+ * grade constants. The default setting for the majority of grade settings requires
+ * that no data source locks remain when a <code>RowSet</code> object is disconnected
+ * from its data source.
+ * The grades <code>GRADE_LOCK_WHEN_MODIFIED</code> and
+ * <code>GRADE_LOCK_WHEN_LOADED</code> allow a disconnected <code>RowSet</code> object
+ * to have a fine-grained control over the degree of locking.
+ * <ul>
+ * <li><b>DATASOURCE_NO_LOCK</b> - No locks remain on the originating data source.
+ * This is the default lock setting for all <code>SyncProvider</code> implementations
+ * unless otherwise directed by a <code>RowSet</code> object.
+ *
+ * <li><b>DATASOURCE_ROW_LOCK</b> - A lock is placed on the rows that are touched by
+ * the original SQL query used to populate the <code>RowSet</code> object.
+ *
+ * <li><b>DATASOURCE_TABLE_LOCK</b> - A lock is placed on all tables that are touched
+ * by the query that was used to populate the <code>RowSet</code> object.
+ *
+ * <li><b>DATASOURCE_DB_LOCK</b>
+ * A lock is placed on the entire data source that is used by the <code>RowSet</code>
+ * object.
+ * </ul>
+ * <p>
+ * <b>3.4 Updatable Views</b>
+ * <p>
+ * A <code>RowSet</code> object may be populated with data from an SQL <code>VIEW</code>.
+ * The following constants indicate whether a <code>SyncProvider</code> object can
+ * update data in the table or tables from which the <code>VIEW</code> was derived.
+ * <ul>
+ * <li><b>UPDATABLE_VIEW_SYNC</b>
+ * Indicates that a <code>SyncProvider</code> implementation  supports synchronization
+ * to the table or tables from which the SQL <code>VIEW</code> used to populate
+ * a <code>RowSet</code> object is derived.
+ *
+ * <li><b>NONUPDATABLE_VIEW_SYNC</b>
+ * Indicates that a <code>SyncProvider</code> implementation  does <b>not</b> support
+ * synchronization to the table or tables from which the SQL <code>VIEW</code>
+ * used to populate  a <code>RowSet</code> object is derived.
+ * </ul>
+ * <p>
+ * <b>3.5 Usage of <code>SyncProvider</code> Grading and Locking</b>
+ * <p>
+ * In the example below, the reference <code>CachedRowSetImpl</code> implementation
+ * reconfigures its current <code>SyncProvider</code> object by calling the
+ * <code>setSyncProvider</code> method.<br>
+ *
+ * <PRE>
+ *   CachedRowSetImpl crs = new CachedRowSetImpl();
+ *   crs.setSyncProvider("com.foo.bar.HASyncProvider");
+ * </PRE>
+ *   An application can retrieve the <code>SyncProvider</code> object currently in use
+ * by a disconnected <code>RowSet</code> object. It can also retrieve the
+ * grade of synchronization with which the provider was implemented and the degree of
+ * locking currently in use.  In addition, an application has the flexibility to set
+ * the degree of locking to be used, which can increase the possibilities for successful
+ * synchronization.  These operation are shown in the following code fragment.
+ * <PRE>
+ *   SyncProvider sync = crs.getSyncProvider();
+ *
+ *   switch (sync.getProviderGrade()) {
+ *   case: SyncProvider.GRADE_CHECK_ALL_AT_COMMIT
+ *         //A high grade of optimistic synchronization
+ *    break;
+ *    case: SyncProvider.GRADE_CHECK_MODIFIED_AT_COMMIT
+ *         //A low grade of optimistic synchronization
+ *    break;
+ *    case: SyncProvider.GRADE_LOCK_WHEN_LOADED
+ *         // A pessimistic synchronization grade
+ *    break;
+ *    case: SyncProvider.GRADE_LOCK_WHEN_MODIFIED
+ *         // A pessimistic synchronization grade
+ *    break;
+ *    case: SyncProvider.GRADE_NONE
+ *      // No synchronization with the originating data source provided
+ *    break;
+ *    }
+ *
+ *    switch (sync.getDataSourcLock() {
+ *      case: SyncProvider.DATASOURCE_DB_LOCK
+ *       // A lock is placed on the entire datasource that is used by the
+ *       // <code>RowSet</code> object
+ *       break;
+ *
+ *      case: SyncProvider.DATASOURCE_NO_LOCK
+ *       // No locks remain on the  originating data source.
+ *      break;
+ *
+ *      case: SyncProvider.DATASOURCE_ROW_LOCK
+ *       // A lock is placed on the rows that are  touched by the original
+ *       // SQL statement used to populate
+ *       // the RowSet object that is using the SyncProvider
+ *       break;
+ *
+ *      case: DATASOURCE_TABLE_LOCK
+ *       // A lock is placed on  all tables that are touched by the original
+ *       // SQL statement used to populated
+ *       // the RowSet object that is using the SyncProvider
+ *      break;
+ *
+ * </PRE>
+ *    It is also possible using the static utility method in the
+ * <code>SyncFactory</code> class to determine the list of <code>SyncProvider</code>
+ * implementations currently registered with the <code>SyncFactory</code>.
+ *
+ * <pre>
+ *       Enumeration e = SyncFactory.getRegisteredProviders();
+ * </pre>
+ *
+ *
+ * <h3><a id="resolving">4.0 Resolving Synchronization Conflicts</a></h3>
+ *
+ * The interface <code>SyncResolver</code> provides a way for an application to
+ * decide manually what to do when a conflict occurs. When the <code>CachedRowSet</code>
+ * method <code>acceptChanges</code> finishes and has detected one or more conflicts,
+ * it throws a <code>SyncProviderException</code> object.  An application can
+ * catch the exception and
+ * have it retrieve a <code>SyncResolver</code> object by calling the method
+ * <code>SyncProviderException.getSyncResolver()</code>.
+ * <P>
+ * A <code>SyncResolver</code> object, which is a special kind of
+ * <code>CachedRowSet</code> object or
+ * a <code>JdbcRowSet</code> object that has implemented the <code>SyncResolver</code>
+ * interface,  examines the conflicts row by row. It is a duplicate of the
+ * <code>RowSet</code> object being synchronized except that it contains only the data
+ * from the data source this is causing a conflict. All of the other column values are
+ * set to <code>null</code>. To navigate from one conflict value to another, a
+ * <code>SyncResolver</code> object provides the methods <code>nextConflict</code> and
+ * <code>previousConflict</code>.
+ * <P>
+ * The <code>SyncResolver</code> interface also
+ * provides methods for doing the following:
+ * <UL>
+ *  <LI>finding out whether the conflict involved an update, a delete, or an insert
+ *  <LI>getting the value in the data source that caused the conflict
+ *  <LI>setting the value that should be in the data source if it needs to be changed
+ *      or setting the value that should be in the <code>RowSet</code> object if it needs
+ *      to be changed
+ * </UL>
+ * <P>
+ * When the <code>CachedRowSet</code> method <code>acceptChanges</code> is called, it
+ * delegates to the <code>RowSet</code> object's  <code>SyncProvider</code> object.
+ * How the writer provided by that <code>SyncProvider</code> object is implemented
+ * determines what level (grade) of checking for conflicts will be done.  After all
+ * checking for conflicts is completed and one or more conflicts has been found, the method
+ * <code>acceptChanges</code> throws a <code>SyncProviderException</code> object. The
+ * application can catch the exception and use it to obtain a <code>SyncResolver</code> object.
+ * <P>
+ * The application can then use <code>SyncResolver</code> methods to get information
+ * about each conflict and decide what to do.  If the application logic or the user
+ * decides that a value in the <code>RowSet</code> object should be the one to
+ * persist, the application or user can overwrite the data source value with it.
+ * <P>
+ * The comment for the <code>SyncResolver</code> interface has more detail.
+ *
+ * <h3><a id="relspec">5.0 Related Specifications</a></h3>
+ * <ul>
+ * <li><a href="http://docs.oracle.com/javase/jndi/tutorial/index.html">JNDI</a>
+ * <li><a href="{@docRoot}/java.logging/java/util/logging/package-summary.html">Java Logging
+ * APIs</a>
+ * </ul>
+ * <h3><a id="reldocs">6.0 Related Documentation</a></h3>
+ * <ul>
+ * <li><a href="http://docs.oracle.com/javase/tutorial/jdbc/">DataSource for JDBC
+ * Connections</a>
+ * </ul>
+ */
+package javax.sql.rowset.spi;
--- a/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package.html	Thu Jun 07 12:23:46 2018 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,493 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-
-  <meta http-equiv="Content-Type"
- content="text/html; charset=iso-8859-1">
-
-  <meta name="GENERATOR"
- content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]">
-<!--
-Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
-DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
-
-This code is free software; you can redistribute it and/or modify it
-under the terms of the GNU General Public License version 2 only, as
-published by the Free Software Foundation.  Oracle designates this
-particular file as subject to the "Classpath" exception as provided
-by Oracle in the LICENSE file that accompanied this code.
-
-This code is distributed in the hope that it will be useful, but WITHOUT
-ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-version 2 for more details (a copy is included in the LICENSE file that
-accompanied this code).
-
-You should have received a copy of the GNU General Public License version
-2 along with this work; if not, write to the Free Software Foundation,
-Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-
-Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
-or visit www.oracle.com if you need additional information or have any
-questions.
--->
-  <title>javax.sql.rowset.spi</title>
-
-</head>
-  <body>
-
-The standard classes and interfaces that a third party vendor has to
-use in its implementation of a synchronization provider. These classes and
-interfaces are referred to as the Service Provider Interface (SPI).  To make it possible
-for a <code>RowSet</code> object to use an implementation, the vendor must register
-it with the <code>SyncFactory</code> singleton. (See the class comment for
-<code>SyncProvider</code> for a full explanation of the registration process and
-the naming convention to be used.)
-
-<h2>Table of Contents</h2>
-<ul>
-<li><a href="#pkgspec">1.0 Package Specification</a>
-<li><a href="#arch">2.0 Service Provider Architecture</a>
-<li><a href="#impl">3.0 Implementer's Guide</a>
-<li><a href="#resolving">4.0 Resolving Synchronization Conflicts</a>
-<li><a href="#relspec">5.0 Related Specifications</a>
-<li><a href="#reldocs">6.0 Related Documentation</a>
-</ul>
-
-<h3><a id="pkgspec">1.0 Package Specification</a></h3>
-<P>
-The following classes and interfaces make up the <code>javax.sql.rowset.spi</code>
-package:
-<UL>
-  <LI><code>SyncFactory</code>
-  <LI><code>SyncProvider</code>
-  <LI><code>SyncFactoryException</code>
-  <LI><code>SyncProviderException</code>
-  <LI><code>SyncResolver</code>
-  <LI><code>XmlReader</code>
-  <LI><code>XmlWriter</code>
-  <LI><code>TransactionalWriter</code>
-</UL>
-The following interfaces, in the <code>javax.sql</code> package, are also part of the SPI:
-<UL>
-  <LI><code>RowSetReader</code>
-  <LI><code>RowSetWriter</code>
-</UL>
-<P>
-A <code>SyncProvider</code> implementation provides a disconnected <code>RowSet</code>
-object with the mechanisms for reading data into it and for writing data that has been
-modified in it
-back to the underlying data source.  A <i>reader</i>, a <code>RowSetReader</code> or
-<code>XMLReader</code> object, reads data into a <code>RowSet</code> object when the
-<code>CachedRowSet</code> methods <code>execute</code> or <code>populate</code>
-are called.  A <i>writer</i>, a <code>RowSetWriter</code> or <code>XMLWriter</code>
-object, writes changes back to the underlying data source when the
-<code>CachedRowSet</code> method <code>acceptChanges</code> is called.
-<P>
-The process of writing changes in a <code>RowSet</code> object to its data source
-is known as <i>synchronization</i>.  The <code>SyncProvider</code> implementation that a
-<code>RowSet</code> object is using determines the level of synchronization that the
-<code>RowSet</code> object's writer uses. The various levels of synchronization are
-referred to as <i>grades</i>.
-<P>
-The lower grades of synchronization are
-known as <i>optimistic</i> concurrency levels because they optimistically
-assume that there will be no conflicts or very few conflicts.  A conflict exists when
-the same data modified in the <code>RowSet</code> object has also been modified
-in the data source. Using the optimistic concurrency model means that if there
-is a conflict, modifications to either the data source or the <code>RowSet</code>
-object will be lost.
-<P>
-Higher grades of synchronization are called <i>pessimistic</i> because they assume
-that others will be accessing the data source and making modifications.  These
-grades set varying levels of locks to increase the chances that no conflicts
-occur.
-<P>
-The lowest level of synchronization is simply writing any changes made to the
-<code>RowSet</code> object to its underlying data source.  The writer does
-nothing to check for conflicts.
-If there is a conflict and the data
-source values are overwritten, the changes other parties have made by to the data
-source are lost.
-<P>
-The <code>RIXMLProvider</code> implementation uses the lowest level
-of synchronization and just writes <code>RowSet</code> changes to the data source.
-
-<P>
-For the next level up, the
-writer checks to see if there are any conflicts, and if there are,
-it does not write anything to the data source.  The problem with this concurrency
-level is that if another party has modified the corresponding data in the data source
-since the <code>RowSet</code> object got its data,
-the changes made to the <code>RowSet</code> object are lost. The
-<code>RIOptimisticProvider</code> implementation uses this level of synchronization.
-<P>
-At higher levels of synchronization, referred to as pessimistic concurrency,
-the writer take steps to avoid conflicts by setting locks. Setting locks
-can vary from setting a lock on a single row to setting a lock on a table
-or the entire data source. The level of synchronization is therefore a tradeoff
-between the ability of users to access the data source concurrently and the  ability
-of the writer to keep the data in the <code>RowSet</code> object and its data source
-synchronized.
-<P>
-It is a requirement that all disconnected <code>RowSet</code> objects
-(<code>CachedRowSet</code>, <code>FilteredRowSet</code>, <code>JoinRowSet</code>,
-and <code>WebRowSet</code> objects) obtain their <code>SyncProvider</code> objects
-from the <code>SyncFactory</code> mechanism.
-<P>
-The reference implementation (RI) provides two synchronization providers.
-    <UL>
-       <LI><b><code>RIOptimisticProvider</code></b> <br>
-           The default provider that the <code>SyncFactory</code> instance will
-           supply to a disconnected <code>RowSet</code> object when no provider
-           implementation is specified.<BR>
-           This synchronization provider uses an optimistic concurrency model,
-           assuming that there will be few conflicts among users
-           who are accessing the same data in a database.  It avoids
-           using locks; rather, it checks to see if there is a conflict
-           before trying to synchronize the <code>RowSet</code> object and the
-           data source. If there is a conflict, it does nothing, meaning that
-           changes to the <code>RowSet</code> object are not persisted to the data
-           source.
-       <LI><B><code>RIXMLProvider</code></B> <BR>
-            A synchronization provider that can be used with a
-            <code>WebRowSet</code> object, which is a rowset that can be written
-            in XML format or read from XML format. The
-            <code>RIXMLProvider</code> implementation does no checking at all for
-            conflicts and simply writes any updated data in the
-            <code>WebRowSet</code> object to the underlying data source.
-            <code>WebRowSet</code> objects use this provider when they are
-            dealing with XML data.
-    </UL>
-
-These <code>SyncProvider</code> implementations
-are bundled with the reference implementation, which makes them always available to
-<code>RowSet</code> implementations.
-<code>SyncProvider</code> implementations make themselves available by being
-registered with the <code>SyncFactory</code> singleton.  When a <code>RowSet</code>
-object requests a provider, by specifying it in the constructor or as an argument to the
-<code>CachedRowSet</code> method <code>setSyncProvider</code>,
-the <code>SyncFactory</code> singleton
-checks to see if the requested provider has been registered with it.
-If it has, the <code>SyncFactory</code> creates an instance of it and passes it to the
-requesting <code>RowSet</code> object.
-If the <code>SyncProvider</code> implementation that is specified has not been registered,
-the <code>SyncFactory</code> singleton causes a <code>SyncFactoryException</code> object
-to be thrown.  If no provider is specified,
-the <code>SyncFactory</code> singleton will create an instance of the default
-provider implementation, <code>RIOptimisticProvider</code>,
-and pass it to the requesting <code>RowSet</code> object.
-
-<P>
-If a <code>WebRowSet</code> object does not specify a provider in its constructor, the
-<code>SyncFactory</code> will give it an instance of <code>RIOptimisticProvider</code>.
-However, the constructor for <code>WebRowSet</code> is implemented to set the provider
-to the <code>RIXMLProvider</code>, which reads and writes a <code>RowSet</code> object
-in XML format.
-<P>
-See the <a href="SyncProvider.html">SyncProvider</a> class
-specification for further details.
-<p>
-Vendors may develop a <code>SyncProvider</code> implementation with any one of the possible
-levels of synchronization, thus giving <code>RowSet</code> objects a choice of
-synchronization mechanisms.
-
-<h3><a id="arch">2.0 Service Provider Interface Architecture</a></h3>
-<b>2.1 Overview</b>
-<p>
-The Service Provider Interface provides a pluggable mechanism by which
-<code>SyncProvider</code> implementations can be registered and then generated when
-required. The lazy reference mechanism employed by the <code>SyncFactory</code> limits
-unnecessary resource consumption by not creating an instance until it is
-required by a disconnected
-<code>RowSet</code> object. The <code>SyncFactory</code> class also provides
-a standard API to configure logging options and streams that <b>may</b> be provided
-by a particular <code>SyncProvider</code> implementation.
-<p>
-<b>2.2 Registering with the <code>SyncFactory</code></b>
-<p>
-A third party <code>SyncProvider</code> implementation must be registered with the
-<code>SyncFactory</code> in order for a disconnected <code>RowSet</code> object
-to obtain it and thereby use its <code>javax.sql.RowSetReader</code> and
-<code>javax.sql.RowSetWriter</code>
-implementations. The following registration mechanisms are available to all
-<code>SyncProvider</code> implementations:
-<ul>
-<li><b>System properties</b> - Properties set at the command line. These
-properties are set at run time and apply system-wide per invocation of the Java
-application. See the section <a href="#reldocs">"Related Documentation"</a>
-further related information.
-
-<li><b>Property Files</b> - Properties specified in a standard property file.
-This can be specified using a System Property or by modifying a standard
-property file located in the platform run-time. The
-reference implementation of this technology includes a standard property
-file than can be edited to add additional <code>SyncProvider</code> objects.
-
-<li><b>JNDI Context</b> - Available providers can be registered on a JNDI
-context. The <code>SyncFactory</code> will attempt to load <code>SyncProvider</code>
-objects bound to the context and register them with the factory. This
-context must be supplied to the <code>SyncFactory</code> for the mechanism to
-function correctly.
-</ul>
-<p>
-Details on how to specify the system properties or properties in a property file
-and how to configure the JNDI Context are explained in detail in the
-<a href="SyncFactory.html"><code>SyncFactory</code></a> class description.
-<p>
-<b>2.3 SyncFactory Provider Instance Generation Policies</b>
-<p>
-The <code>SyncFactory</code> generates a requested <code>SyncProvider</code>
-object if the provider has been correctly registered.  The
-following policies are adhered to when either a disconnected <code>RowSet</code> object
-is instantiated with a specified <code>SyncProvider</code> implementation or is
-reconfigured at runtime with an alternative <code>SyncProvider</code> object.
-<ul>
-<li> If a <code>SyncProvider</code> object is specified and the <code>SyncFactory</code>
-contains <i>no</i> reference to the provider, a <code>SyncFactoryException</code> is
-thrown.
-
-<li> If a <code>SyncProvider</code> object is specified and the <code>SyncFactory</code>
-contains a reference to the provider, the requested provider is supplied.
-
-<li> If no <code>SyncProvider</code> object is specified, the reference
-implementation provider <code>RIOptimisticProvider</code> is supplied.
-</ul>
-<p>
-These policies are explored in more detail in the <a href="SyncFactory.html">
-<code>SyncFactory</code></a> class.
-
-<h3><a id="impl">3.0 SyncProvider Implementer's Guide</a></h3>
-
-<b>3.1 Requirements</b>
-<p>
-A compliant <code>SyncProvider</code> implementation that is fully pluggable
-into the <code>SyncFactory</code> <b>must</b> extend and implement all
-abstract methods in the <a href="SyncProvider.html"><code>SyncProvider</code></a>
-class. In addition, an implementation <b>must</b> determine the
-grade, locking and updatable view capabilities defined in the
-<code>SyncProvider</code> class definition. One or more of the
-<code>SyncProvider</code> description criteria <b>must</b> be supported. It
-is expected that vendor implementations will offer a range of grade, locking, and
-updatable view capabilities.
-<p>
-Furthermore, the <code>SyncProvider</code> naming convention <b>must</b> be followed as
-detailed in the <a href="SyncProvider.html"><code>SyncProvider</code></a> class
-description.
-<p>
-<b>3.2 Grades</b>
-<p>
-JSR 114 defines a set of grades to describe the quality of synchronization
-a <code>SyncProvider</code> object can offer a disconnected <code>RowSet</code>
-object. These grades are listed from the lowest quality of service to the highest.
-<ul>
-<li><b>GRADE_NONE</b> - No synchronization with the originating data source is
-provided. A <code>SyncProvider</code> implementation returning this grade will simply
-attempt to write any data that has changed in the <code>RowSet</code> object to the
-underlying data source, overwriting whatever is there. No attempt is made to compare
-original values with current values to see if there is a conflict. The
-<code>RIXMLProvider</code> is implemented with this grade.
-
-<li><b>GRADE_CHECK_MODIFIED_AT_COMMIT</b> - A low grade of optimistic synchronization.
-A <code>SyncProvider</code> implementation returning this grade
-will check for conflicts in rows that have changed between the last synchronization
-and the current synchronization under way. Any changes in the originating data source
-that have been modified will not be reflected in the disconnected <code>RowSet</code>
-object. If there are no conflicts, changes in the <code>RowSet</code> object will be
-written to the data source. If there are conflicts, no changes are written.
-The <code>RIOptimisticProvider</code> implementation uses this grade.
-
-<li><b>GRADE_CHECK_ALL_AT_COMMIT</b> - A high grade of optimistic synchronization.
-A <code>SyncProvider</code> implementation   returning this grade
-will check all rows, including rows that have not changed in the disconnected
-<code>RowSet</code> object. In this way, any changes to rows in the underlying
-data source will be reflected in the disconnected <code>RowSet</code> object
-when the synchronization finishes successfully.
-
-<li><b>GRADE_LOCK_WHEN_MODIFIED</b> - A pessimistic grade of synchronization.
-<code>SyncProvider</code> implementations returning this grade will lock
-the row in the originating  data source that corresponds to the row being changed
-in the <code>RowSet</code> object to reduce the possibility of other
-processes modifying the same data in the data source.
-
-<li><b>GRADE_LOCK_WHEN_LOADED</b> - A higher pessimistic synchronization grade.
-A <code>SyncProvider</code> implementation returning this grade will lock
-the entire view and/or  table affected by the original query used to
-populate a <code>RowSet</code> object.
-</ul>
-<p>
-<b>3.3 Locks</b>
-<p>
-JSR 114 defines a set of constants that specify whether any locks have been
-placed on a <code>RowSet</code> object's underlying data source and, if so,
-on which constructs the locks are placed.  These locks will remain on the data
-source while the <code>RowSet</code> object is disconnected from the data source.
-<P>
-These constants <b>should</b> be considered complementary to the
-grade constants. The default setting for the majority of grade settings requires
-that no data source locks remain when a <code>RowSet</code> object is disconnected
-from its data source.
-The grades <code>GRADE_LOCK_WHEN_MODIFIED</code> and
-<code>GRADE_LOCK_WHEN_LOADED</code> allow a disconnected <code>RowSet</code> object
-to have a fine-grained control over the degree of locking.
-<ul>
-<li><b>DATASOURCE_NO_LOCK</b> - No locks remain on the originating data source.
-This is the default lock setting for all <code>SyncProvider</code> implementations
-unless otherwise directed by a <code>RowSet</code> object.
-
-<li><b>DATASOURCE_ROW_LOCK</b> - A lock is placed on the rows that are touched by
-the original SQL query used to populate the <code>RowSet</code> object.
-
-<li><b>DATASOURCE_TABLE_LOCK</b> - A lock is placed on all tables that are touched
-by the query that was used to populate the <code>RowSet</code> object.
-
-<li><b>DATASOURCE_DB_LOCK</b>
-A lock is placed on the entire data source that is used by the <code>RowSet</code>
-object.
-</ul>
-<p>
-<b>3.4 Updatable Views</b>
-<p>
-A <code>RowSet</code> object may be populated with data from an SQL <code>VIEW</code>.
-The following constants indicate whether a <code>SyncProvider</code> object can
-update data in the table or tables from which the <code>VIEW</code> was derived.
-<ul>
-<li><b>UPDATABLE_VIEW_SYNC</b>
-Indicates that a <code>SyncProvider</code> implementation  supports synchronization
-to the table or tables from which the SQL <code>VIEW</code> used to populate
-a <code>RowSet</code> object is derived.
-
-<li><b>NONUPDATABLE_VIEW_SYNC</b>
-Indicates that a <code>SyncProvider</code> implementation  does <b>not</b> support
-synchronization to the table or tables from which the SQL <code>VIEW</code>
-used to populate  a <code>RowSet</code> object is derived.
-</ul>
-<p>
-<b>3.5 Usage of <code>SyncProvider</code> Grading and Locking</b>
-<p>
-In the example below, the reference <code>CachedRowSetImpl</code> implementation
-reconfigures its current <code>SyncProvider</code> object by calling the
-<code>setSyncProvider</code> method.<br>
-
-<PRE>
-    CachedRowSetImpl crs = new CachedRowSetImpl();
-    crs.setSyncProvider("com.foo.bar.HASyncProvider");
-</PRE>
-    An application can retrieve the <code>SyncProvider</code> object currently in use
-by a disconnected <code>RowSet</code> object. It can also retrieve the
-grade of synchronization with which the provider was implemented and the degree of
-locking currently in use.  In addition, an application has the flexibility to set
-the degree of locking to be used, which can increase the possibilities for successful
-synchronization.  These operation are shown in the following code fragment.
-<PRE>
-    SyncProvider sync = crs.getSyncProvider();
-
-    switch (sync.getProviderGrade()) {
-    case: SyncProvider.GRADE_CHECK_ALL_AT_COMMIT
-         //A high grade of optimistic synchronization
-    break;
-    case: SyncProvider.GRADE_CHECK_MODIFIED_AT_COMMIT
-         //A low grade of optimistic synchronization
-    break;
-    case: SyncProvider.GRADE_LOCK_WHEN_LOADED
-         // A pessimistic synchronization grade
-    break;
-    case: SyncProvider.GRADE_LOCK_WHEN_MODIFIED
-         // A pessimistic synchronization grade
-    break;
-    case: SyncProvider.GRADE_NONE
-      // No synchronization with the originating data source provided
-    break;
-    }
-
-    switch (sync.getDataSourcLock() {
-      case: SyncProvider.DATASOURCE_DB_LOCK
-       // A lock is placed on the entire datasource that is used by the
-       // <code>RowSet</code> object
-       break;
-
-      case: SyncProvider.DATASOURCE_NO_LOCK
-       // No locks remain on the  originating data source.
-      break;
-
-      case: SyncProvider.DATASOURCE_ROW_LOCK
-       // A lock is placed on the rows that are  touched by the original
-       // SQL statement used to populate
-       // the RowSet object that is using the SyncProvider
-       break;
-
-      case: DATASOURCE_TABLE_LOCK
-       // A lock is placed on  all tables that are touched by the original
-       // SQL statement used to populated
-       // the RowSet object that is using the SyncProvider
-       break;
-
-</PRE>
-    It is also possible using the static utility method in the
-<code>SyncFactory</code> class to determine the list of <code>SyncProvider</code>
-implementations currently registered with the <code>SyncFactory</code>.
-
-<pre>
-       Enumeration e = SyncFactory.getRegisteredProviders();
-</pre>
-
-
-<h3><a id="resolving">4.0 Resolving Synchronization Conflicts</a></h3>
-
-The interface <code>SyncResolver</code> provides a way for an application to
-decide manually what to do when a conflict occurs. When the <code>CachedRowSet</code>
-method <code>acceptChanges</code> finishes and has detected one or more conflicts,
-it throws a <code>SyncProviderException</code> object.  An application can
-catch the exception and
-have it retrieve a <code>SyncResolver</code> object by calling the method
-<code>SyncProviderException.getSyncResolver()</code>.
-<P>
-A <code>SyncResolver</code> object, which is a special kind of
-<code>CachedRowSet</code> object or
-a <code>JdbcRowSet</code> object that has implemented the <code>SyncResolver</code>
-interface,  examines the conflicts row by row. It is a duplicate of the
-<code>RowSet</code> object being synchronized except that it contains only the data
-from the data source this is causing a conflict. All of the other column values are
-set to <code>null</code>. To navigate from one conflict value to another, a
-<code>SyncResolver</code> object provides the methods <code>nextConflict</code> and
-<code>previousConflict</code>.
-<P>
-The <code>SyncResolver</code> interface also
-provides methods for doing the following:
-<UL>
- <LI>finding out whether the conflict involved an update, a delete, or an insert
- <LI>getting the value in the data source that caused the conflict
- <LI>setting the value that should be in the data source if it needs to be changed
-     or setting the value that should be in the <code>RowSet</code> object if it needs
-     to be changed
-</UL>
-<P>
-When the <code>CachedRowSet</code> method <code>acceptChanges</code> is called, it
-delegates to the <code>RowSet</code> object's  <code>SyncProvider</code> object.
-How the writer provided by that <code>SyncProvider</code> object is implemented
-determines what level (grade) of checking for conflicts will be done.  After all
-checking for conflicts is completed and one or more conflicts has been found, the method
-<code>acceptChanges</code> throws a <code>SyncProviderException</code> object. The
-application can catch the exception and use it to obtain a <code>SyncResolver</code> object.
-<P>
-The application can then use <code>SyncResolver</code> methods to get information
-about each conflict and decide what to do.  If the application logic or the user
-decides that a value in the <code>RowSet</code> object should be the one to
-persist, the application or user can overwrite the data source value with it.
-<P>
-The comment for the <code>SyncResolver</code> interface has more detail.
-
-<h3><a id="relspec">5.0 Related Specifications</a></h3>
-<ul>
-<li><a href="http://docs.oracle.com/javase/jndi/tutorial/index.html">JNDI</a>
-<li><a href="{@docRoot}/java/util/logging/package-summary.html">Java Logging
-APIs</a>
-</ul>
-<h3><a id="reldocs">6.0 Related Documentation</a></h3>
-<ul>
-<li><a href="http://docs.oracle.com/javase/tutorial/jdbc/">DataSource for JDBC
-Connections</a>
-</ul>
-
-</body>
-</html>