diff --git a/src/java.sql.rowset/share/classes/javax/sql/rowset/package-info.java b/src/java.sql.rowset/share/classes/javax/sql/rowset/package-info.java new file mode 100644 index 00000000000..1057b7e37ff --- /dev/null +++ b/src/java.sql.rowset/share/classes/javax/sql/rowset/package-info.java @@ -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 RowSet + * implementations. This package contains interfaces and classes + * that a standard RowSet implementation either implements or extends. + * + *

Table of Contents

+ * + * + *

1.0 Package Specification

+ * This package specifies five standard JDBC RowSet interfaces. + * All five extend the + * RowSet interface described in the JDBC 3.0 + * specification. It is anticipated that additional definitions + * of more specialized JDBC RowSet types will emerge as this technology + * matures. Future definitions should be specified as subinterfaces using + * inheritance similar to the way it is used in this specification. + *

+ * Note: The interface definitions provided in this package form the basis for + * all compliant JDBC RowSet implementations. Vendors and more advanced + * developers who intend to provide their own compliant RowSet implementations + * should pay particular attention to the assertions detailed in specification + * interfaces. + * + *

2.0 Standard RowSet Definitions

+ * + * + *

3.0 Implementer's Guide

+ * Compliant implementations of JDBC RowSet Implementations + * must follow the assertions described in this specification. In accordance + * with the terms of the Java Community Process, 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 RowSet definitions. Implementers + * should also consult the Implementer's Guide in the javax.sql.rowset.spi package for guidelines + * on SyncProvider implementations. + * + * + * + *

4.0 Related Specifications

+ * + * + *

5.0 Related Documentation

+ * + */ +package javax.sql.rowset; diff --git a/src/java.sql.rowset/share/classes/javax/sql/rowset/package.html b/src/java.sql.rowset/share/classes/javax/sql/rowset/package.html deleted file mode 100644 index 12ee65c9b8e..00000000000 --- a/src/java.sql.rowset/share/classes/javax/sql/rowset/package.html +++ /dev/null @@ -1,297 +0,0 @@ - - - - - - - javax.sql.rowset Package - - - - -Standard interfaces and base classes for JDBC RowSet -implementations. This package contains interfaces and classes -that a standard RowSet implementation either implements or extends. - - -

Table of Contents

- - -

1.0 Package Specification

-This package specifies five standard JDBC RowSet interfaces. - All five extend the -RowSet interface described in the JDBC 3.0 -specification. It is anticipated that additional definitions -of more specialized JDBC RowSet types will emerge as this technology -matures. Future definitions should be specified as subinterfaces using -inheritance similar to the way it is used in this specification. -

-Note: The interface definitions provided in this package form the basis for -all compliant JDBC RowSet implementations. Vendors and more advanced -developers who intend to provide their own compliant RowSet implementations -should pay particular attention to the assertions detailed in specification -interfaces. - -

2.0 Standard RowSet Definitions

- - -

3.0 Implementer's Guide

-Compliant implementations of JDBC RowSet Implementations -must follow the assertions described in this specification. In accordance -with the terms of the Java Community Process, 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 RowSet definitions. Implementers -should also consult the Implementer's Guide in the javax.sql.rowset.spi package for guidelines -on SyncProvider implementations. - - - -

4.0 Related Specifications

- - -

5.0 Related Documentation

- - - diff --git a/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package-info.java b/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package-info.java new file mode 100644 index 00000000000..713b4a1a9a7 --- /dev/null +++ b/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package-info.java @@ -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 RowSet object to use an implementation, the vendor must register + * it with the SyncFactory singleton. (See the class comment for + * SyncProvider for a full explanation of the registration process and + * the naming convention to be used.) + * + *

Table of Contents

+ * + * + *

1.0 Package Specification

+ *

+ * The following classes and interfaces make up the javax.sql.rowset.spi + * package: + *

+ * The following interfaces, in the javax.sql package, are also part of the SPI: + * + *

+ * A SyncProvider implementation provides a disconnected RowSet + * 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 reader, a RowSetReader or + * XMLReader object, reads data into a RowSet object when the + * CachedRowSet methods execute or populate + * are called. A writer, a RowSetWriter or XMLWriter + * object, writes changes back to the underlying data source when the + * CachedRowSet method acceptChanges is called. + *

+ * The process of writing changes in a RowSet object to its data source + * is known as synchronization. The SyncProvider implementation that a + * RowSet object is using determines the level of synchronization that the + * RowSet object's writer uses. The various levels of synchronization are + * referred to as grades. + *

+ * The lower grades of synchronization are + * known as optimistic 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 RowSet 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 RowSet + * object will be lost. + *

+ * Higher grades of synchronization are called pessimistic 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. + *

+ * The lowest level of synchronization is simply writing any changes made to the + * RowSet 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. + *

+ * The RIXMLProvider implementation uses the lowest level + * of synchronization and just writes RowSet changes to the data source. + * + *

+ * 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 RowSet object got its data, + * the changes made to the RowSet object are lost. The + * RIOptimisticProvider implementation uses this level of synchronization. + *

+ * 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 RowSet object and its data source + * synchronized. + *

+ * It is a requirement that all disconnected RowSet objects + * (CachedRowSet, FilteredRowSet, JoinRowSet, + * and WebRowSet objects) obtain their SyncProvider objects + * from the SyncFactory mechanism. + *

+ * The reference implementation (RI) provides two synchronization providers. + *

+ * + * These SyncProvider implementations + * are bundled with the reference implementation, which makes them always available to + * RowSet implementations. + * SyncProvider implementations make themselves available by being + * registered with the SyncFactory singleton. When a RowSet + * object requests a provider, by specifying it in the constructor or as an argument to the + * CachedRowSet method setSyncProvider, + * the SyncFactory singleton + * checks to see if the requested provider has been registered with it. + * If it has, the SyncFactory creates an instance of it and passes it to the + * requesting RowSet object. + * If the SyncProvider implementation that is specified has not been registered, + * the SyncFactory singleton causes a SyncFactoryException object + * to be thrown. If no provider is specified, + * the SyncFactory singleton will create an instance of the default + * provider implementation, RIOptimisticProvider, + * and pass it to the requesting RowSet object. + * + *

+ * If a WebRowSet object does not specify a provider in its constructor, the + * SyncFactory will give it an instance of RIOptimisticProvider. + * However, the constructor for WebRowSet is implemented to set the provider + * to the RIXMLProvider, which reads and writes a RowSet object + * in XML format. + *

+ * See the SyncProvider class + * specification for further details. + *

+ * Vendors may develop a SyncProvider implementation with any one of the possible + * levels of synchronization, thus giving RowSet objects a choice of + * synchronization mechanisms. + * + *

2.0 Service Provider Interface Architecture

+ * 2.1 Overview + *

+ * The Service Provider Interface provides a pluggable mechanism by which + * SyncProvider implementations can be registered and then generated when + * required. The lazy reference mechanism employed by the SyncFactory limits + * unnecessary resource consumption by not creating an instance until it is + * required by a disconnected + * RowSet object. The SyncFactory class also provides + * a standard API to configure logging options and streams that may be provided + * by a particular SyncProvider implementation. + *

+ * 2.2 Registering with the SyncFactory + *

+ * A third party SyncProvider implementation must be registered with the + * SyncFactory in order for a disconnected RowSet object + * to obtain it and thereby use its javax.sql.RowSetReader and + * javax.sql.RowSetWriter + * implementations. The following registration mechanisms are available to all + * SyncProvider implementations: + *

+ *

+ * 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 + * SyncFactory class description. + *

+ * 2.3 SyncFactory Provider Instance Generation Policies + *

+ * The SyncFactory generates a requested SyncProvider + * object if the provider has been correctly registered. The + * following policies are adhered to when either a disconnected RowSet object + * is instantiated with a specified SyncProvider implementation or is + * reconfigured at runtime with an alternative SyncProvider object. + *

+ *

+ * These policies are explored in more detail in the + * SyncFactory class. + * + *

3.0 SyncProvider Implementer's Guide

+ * + * 3.1 Requirements + *

+ * A compliant SyncProvider implementation that is fully pluggable + * into the SyncFactory must extend and implement all + * abstract methods in the SyncProvider + * class. In addition, an implementation must determine the + * grade, locking and updatable view capabilities defined in the + * SyncProvider class definition. One or more of the + * SyncProvider description criteria must be supported. It + * is expected that vendor implementations will offer a range of grade, locking, and + * updatable view capabilities. + *

+ * Furthermore, the SyncProvider naming convention must be followed as + * detailed in the SyncProvider class + * description. + *

+ * 3.2 Grades + *

+ * JSR 114 defines a set of grades to describe the quality of synchronization + * a SyncProvider object can offer a disconnected RowSet + * object. These grades are listed from the lowest quality of service to the highest. + *

+ *

+ * 3.3 Locks + *

+ * JSR 114 defines a set of constants that specify whether any locks have been + * placed on a RowSet 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 RowSet object is disconnected from the data source. + *

+ * These constants should 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 RowSet object is disconnected + * from its data source. + * The grades GRADE_LOCK_WHEN_MODIFIED and + * GRADE_LOCK_WHEN_LOADED allow a disconnected RowSet object + * to have a fine-grained control over the degree of locking. + *

+ *

+ * 3.4 Updatable Views + *

+ * A RowSet object may be populated with data from an SQL VIEW. + * The following constants indicate whether a SyncProvider object can + * update data in the table or tables from which the VIEW was derived. + *

+ *

+ * 3.5 Usage of SyncProvider Grading and Locking + *

+ * In the example below, the reference CachedRowSetImpl implementation + * reconfigures its current SyncProvider object by calling the + * setSyncProvider method.
+ * + * 

+ *   CachedRowSetImpl crs = new CachedRowSetImpl();
+ *   crs.setSyncProvider("com.foo.bar.HASyncProvider");
+ *
+ * An application can retrieve the SyncProvider object currently in use + * by a disconnected RowSet 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. + * 
+ *   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
+ *       // RowSet 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;
+ *
+ *
+ * It is also possible using the static utility method in the + * SyncFactory class to determine the list of SyncProvider + * implementations currently registered with the SyncFactory. + * + * 
+ *       Enumeration e = SyncFactory.getRegisteredProviders();
+ *
+ * + * + *

4.0 Resolving Synchronization Conflicts

+ * + * The interface SyncResolver provides a way for an application to + * decide manually what to do when a conflict occurs. When the CachedRowSet + * method acceptChanges finishes and has detected one or more conflicts, + * it throws a SyncProviderException object. An application can + * catch the exception and + * have it retrieve a SyncResolver object by calling the method + * SyncProviderException.getSyncResolver(). + *

+ * A SyncResolver object, which is a special kind of + * CachedRowSet object or + * a JdbcRowSet object that has implemented the SyncResolver + * interface, examines the conflicts row by row. It is a duplicate of the + * RowSet 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 null. To navigate from one conflict value to another, a + * SyncResolver object provides the methods nextConflict and + * previousConflict. + *

+ * The SyncResolver interface also + * provides methods for doing the following: + *

+ *

+ * When the CachedRowSet method acceptChanges is called, it + * delegates to the RowSet object's SyncProvider object. + * How the writer provided by that SyncProvider 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 + * acceptChanges throws a SyncProviderException object. The + * application can catch the exception and use it to obtain a SyncResolver object. + *

+ * The application can then use SyncResolver 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 RowSet object should be the one to + * persist, the application or user can overwrite the data source value with it. + *

+ * The comment for the SyncResolver interface has more detail. + * + *

5.0 Related Specifications

+ * + *

6.0 Related Documentation

+ * + */ +package javax.sql.rowset.spi; diff --git a/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package.html b/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package.html deleted file mode 100644 index 786b906fec9..00000000000 --- a/src/java.sql.rowset/share/classes/javax/sql/rowset/spi/package.html +++ /dev/null @@ -1,493 +0,0 @@ - - - - - - - - - javax.sql.rowset.spi - - - - -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 RowSet object to use an implementation, the vendor must register -it with the SyncFactory singleton. (See the class comment for -SyncProvider for a full explanation of the registration process and -the naming convention to be used.) - -

Table of Contents

- - -

1.0 Package Specification

-

-The following classes and interfaces make up the javax.sql.rowset.spi -package: -

-The following interfaces, in the javax.sql package, are also part of the SPI: - -

-A SyncProvider implementation provides a disconnected RowSet -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 reader, a RowSetReader or -XMLReader object, reads data into a RowSet object when the -CachedRowSet methods execute or populate -are called. A writer, a RowSetWriter or XMLWriter -object, writes changes back to the underlying data source when the -CachedRowSet method acceptChanges is called. -

-The process of writing changes in a RowSet object to its data source -is known as synchronization. The SyncProvider implementation that a -RowSet object is using determines the level of synchronization that the -RowSet object's writer uses. The various levels of synchronization are -referred to as grades. -

-The lower grades of synchronization are -known as optimistic 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 RowSet 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 RowSet -object will be lost. -

-Higher grades of synchronization are called pessimistic 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. -

-The lowest level of synchronization is simply writing any changes made to the -RowSet 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. -

-The RIXMLProvider implementation uses the lowest level -of synchronization and just writes RowSet changes to the data source. - -

-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 RowSet object got its data, -the changes made to the RowSet object are lost. The -RIOptimisticProvider implementation uses this level of synchronization. -

-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 RowSet object and its data source -synchronized. -

-It is a requirement that all disconnected RowSet objects -(CachedRowSet, FilteredRowSet, JoinRowSet, -and WebRowSet objects) obtain their SyncProvider objects -from the SyncFactory mechanism. -

-The reference implementation (RI) provides two synchronization providers. -

- -These SyncProvider implementations -are bundled with the reference implementation, which makes them always available to -RowSet implementations. -SyncProvider implementations make themselves available by being -registered with the SyncFactory singleton. When a RowSet -object requests a provider, by specifying it in the constructor or as an argument to the -CachedRowSet method setSyncProvider, -the SyncFactory singleton -checks to see if the requested provider has been registered with it. -If it has, the SyncFactory creates an instance of it and passes it to the -requesting RowSet object. -If the SyncProvider implementation that is specified has not been registered, -the SyncFactory singleton causes a SyncFactoryException object -to be thrown. If no provider is specified, -the SyncFactory singleton will create an instance of the default -provider implementation, RIOptimisticProvider, -and pass it to the requesting RowSet object. - -

-If a WebRowSet object does not specify a provider in its constructor, the -SyncFactory will give it an instance of RIOptimisticProvider. -However, the constructor for WebRowSet is implemented to set the provider -to the RIXMLProvider, which reads and writes a RowSet object -in XML format. -

-See the SyncProvider class -specification for further details. -

-Vendors may develop a SyncProvider implementation with any one of the possible -levels of synchronization, thus giving RowSet objects a choice of -synchronization mechanisms. - -

2.0 Service Provider Interface Architecture

-2.1 Overview -

-The Service Provider Interface provides a pluggable mechanism by which -SyncProvider implementations can be registered and then generated when -required. The lazy reference mechanism employed by the SyncFactory limits -unnecessary resource consumption by not creating an instance until it is -required by a disconnected -RowSet object. The SyncFactory class also provides -a standard API to configure logging options and streams that may be provided -by a particular SyncProvider implementation. -

-2.2 Registering with the SyncFactory -

-A third party SyncProvider implementation must be registered with the -SyncFactory in order for a disconnected RowSet object -to obtain it and thereby use its javax.sql.RowSetReader and -javax.sql.RowSetWriter -implementations. The following registration mechanisms are available to all -SyncProvider implementations: -

-

-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 -SyncFactory class description. -

-2.3 SyncFactory Provider Instance Generation Policies -

-The SyncFactory generates a requested SyncProvider -object if the provider has been correctly registered. The -following policies are adhered to when either a disconnected RowSet object -is instantiated with a specified SyncProvider implementation or is -reconfigured at runtime with an alternative SyncProvider object. -

-

-These policies are explored in more detail in the -SyncFactory class. - -

3.0 SyncProvider Implementer's Guide

- -3.1 Requirements -

-A compliant SyncProvider implementation that is fully pluggable -into the SyncFactory must extend and implement all -abstract methods in the SyncProvider -class. In addition, an implementation must determine the -grade, locking and updatable view capabilities defined in the -SyncProvider class definition. One or more of the -SyncProvider description criteria must be supported. It -is expected that vendor implementations will offer a range of grade, locking, and -updatable view capabilities. -

-Furthermore, the SyncProvider naming convention must be followed as -detailed in the SyncProvider class -description. -

-3.2 Grades -

-JSR 114 defines a set of grades to describe the quality of synchronization -a SyncProvider object can offer a disconnected RowSet -object. These grades are listed from the lowest quality of service to the highest. -

-

-3.3 Locks -

-JSR 114 defines a set of constants that specify whether any locks have been -placed on a RowSet 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 RowSet object is disconnected from the data source. -

-These constants should 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 RowSet object is disconnected -from its data source. -The grades GRADE_LOCK_WHEN_MODIFIED and -GRADE_LOCK_WHEN_LOADED allow a disconnected RowSet object -to have a fine-grained control over the degree of locking. -

-

-3.4 Updatable Views -

-A RowSet object may be populated with data from an SQL VIEW. -The following constants indicate whether a SyncProvider object can -update data in the table or tables from which the VIEW was derived. -

-

-3.5 Usage of SyncProvider Grading and Locking -

-In the example below, the reference CachedRowSetImpl implementation -reconfigures its current SyncProvider object by calling the -setSyncProvider method.
- -

-    CachedRowSetImpl crs = new CachedRowSetImpl();
-    crs.setSyncProvider("com.foo.bar.HASyncProvider");
-
- An application can retrieve the SyncProvider object currently in use -by a disconnected RowSet 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. -
-    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
-       // RowSet 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;
-
-
- It is also possible using the static utility method in the -SyncFactory class to determine the list of SyncProvider -implementations currently registered with the SyncFactory. - -
-       Enumeration e = SyncFactory.getRegisteredProviders();
-
- - -

4.0 Resolving Synchronization Conflicts

- -The interface SyncResolver provides a way for an application to -decide manually what to do when a conflict occurs. When the CachedRowSet -method acceptChanges finishes and has detected one or more conflicts, -it throws a SyncProviderException object. An application can -catch the exception and -have it retrieve a SyncResolver object by calling the method -SyncProviderException.getSyncResolver(). -

-A SyncResolver object, which is a special kind of -CachedRowSet object or -a JdbcRowSet object that has implemented the SyncResolver -interface, examines the conflicts row by row. It is a duplicate of the -RowSet 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 null. To navigate from one conflict value to another, a -SyncResolver object provides the methods nextConflict and -previousConflict. -

-The SyncResolver interface also -provides methods for doing the following: -

-

-When the CachedRowSet method acceptChanges is called, it -delegates to the RowSet object's SyncProvider object. -How the writer provided by that SyncProvider 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 -acceptChanges throws a SyncProviderException object. The -application can catch the exception and use it to obtain a SyncResolver object. -

-The application can then use SyncResolver 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 RowSet object should be the one to -persist, the application or user can overwrite the data source value with it. -

-The comment for the SyncResolver interface has more detail. - -

5.0 Related Specifications

- -

6.0 Related Documentation

- - - -