src/share/classes/javax/sql/rowset/spi/package.html

Print this page

        

*** 44,65 **** Doing this helps make developers aware of the implementation. 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.) ! <P> <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 name="pkgspec">1.0 Package Specification</h3> <P> The following classes and interfaces make up the <code>javax.sql.rowset.spi</code> package: <UL> <LI><code>SyncFactory</code> --- 44,65 ---- Doing this helps make developers aware of the implementation. 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 name="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>
*** 199,212 **** Vendors may develop a <tt>SyncProvider</tt> implementation with any one of the possible levels of synchronization, thus giving <code>RowSet</code> objects a choice of synchronization mechanisms. A vendor can make its implementation available by registering the fully qualified class name with Oracle Corporation at <code>jdbc@sun.com</code>. This process is discussed in further detail below. - <P> ! <a name="arch"><h3>2.0 Service Provider Interface Architecture</h3> ! <ul> <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 --- 199,210 ---- Vendors may develop a <tt>SyncProvider</tt> implementation with any one of the possible levels of synchronization, thus giving <code>RowSet</code> objects a choice of synchronization mechanisms. A vendor can make its implementation available by registering the fully qualified class name with Oracle Corporation at <code>jdbc@sun.com</code>. This process is discussed in further detail below. ! <h3><a name="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
*** 227,243 **** <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. ! <p> <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. ! <p> <li><b>JNDI Context</b> - Available providers can be registered on a JNDI context. The <tt>SyncFactory</tt> will attempt to load <tt>SyncProvider</tt> 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. --- 225,241 ---- <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 <tt>SyncFactory</tt> will attempt to load <tt>SyncProvider</tt> 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.
*** 256,279 **** 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. ! <p> <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. ! <p> <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. - </ul> ! <li><a name="impl"><h3>3.0 SyncProvider Implementer's Guide</h3> ! <ul> <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> --- 254,276 ---- 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 name="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>
*** 298,330 **** 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. ! <p> <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. ! <p> <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. ! <p> <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. ! <p> <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> --- 295,327 ---- 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>
*** 345,361 **** 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. ! <p> <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. ! <p> <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. ! <p> <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> --- 342,358 ---- 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>
*** 367,377 **** <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 a <code>RowSet</code> object is derived. ! <p> <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> --- 364,374 ---- <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 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>
*** 442,454 **** <pre> Enumeration e = SyncFactory.getRegisteredProviders(); </pre> - </ul> ! <h3><a name="resolving">4.0 Resolving Synchronization Conflicts</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 --- 439,450 ---- <pre> Enumeration e = SyncFactory.getRegisteredProviders(); </pre> ! <h3><a name="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
*** 489,505 **** 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. ! <a name="relspec"><h3>5.0 Related Specifications</h3> <ul> <li><a href="http://java.sun.com/products/jndi">JNDI 1.3</a> <li><a href="{@docRoot}/../technotes/guides/logging/index.html">Java Logging APIs</a> </ul> ! <a name="reldocs"><h3>6.0 Related Documentation</h3> <ul> <li><a href="{@docRoot}/../technotes/tools/index.html#basic">System properties</a> <li>Resource Files <li><a href="http://java.sun.com/tutorial/jdbc">DataSource for JDBC --- 485,501 ---- 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 name="relspec">5.0 Related Specifications</a></h3> <ul> <li><a href="http://java.sun.com/products/jndi">JNDI 1.3</a> <li><a href="{@docRoot}/../technotes/guides/logging/index.html">Java Logging APIs</a> </ul> ! <h3><a name="reldocs">6.0 Related Documentation</a></h3> <ul> <li><a href="{@docRoot}/../technotes/tools/index.html#basic">System properties</a> <li>Resource Files <li><a href="http://java.sun.com/tutorial/jdbc">DataSource for JDBC