| author | lancea |
| Thu, 07 Jun 2018 06:27:09 -0400 | |
| changeset 50444 | db65921e9a9b |
| parent 50443 | 8e56de95ce10 |
| child 50445 | bd6b78feb6a3 |
--- /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™ 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>™</b></a> + * - A <code>CachedRowSet</code> object is a JavaBeans™ + * 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™ 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>™</b></a> - - A <code>CachedRowSet</code> object is a JavaBeans™ - 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>