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

Print this page




  29 
  30 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  31 or visit www.oracle.com if you need additional information or have any
  32 questions.
  33 -->
  34   <title>javax.sql.rowset.spi</title>
  35    
  36 </head>
  37   <body bgcolor="#ffffff">
  38 
  39 The standard classes and interfaces that a third party vendor has to
  40 use in its implementation of a synchronization provider. These classes and 
  41 interfaces are referred to as the Service Provider Interface (SPI). A vendor may 
  42 have its implementation included on the JDBC web page that lists available
  43 <code>SyncProvider</code> implementations by sending email to <code>jdbc@sun.com</code>.
  44 Doing this helps make developers aware of the implementation. To make it possible
  45 for a <code>RowSet</code> object to use an implementation, the vendor must register
  46 it with the <code>SyncFactory</code> singleton. (See the class comment for
  47 <code>SyncProvider</code> for a full explanation of the registration process and 
  48 the naming convention to be used.)
  49 <P>
  50 <h2>Table of Contents</h2>
  51 <ul>
  52 <li><a href="#pkgspec">1.0 Package Specification</a>
  53 <li><a href="#arch">2.0 Service Provider Architecture</a>
  54 <li><a href="#impl">3.0 Implementer's Guide</a>
  55 <li><a href="#resolving">4.0 Resolving Synchronization Conflicts</a>
  56 <li><a href="#relspec">5.0 Related Specifications</a>
  57 <li><a href="#reldocs">6.0 Related Documentation</a>
  58 </ul>
  59 
  60 <h3><a name="pkgspec">1.0 Package Specification</h3>
  61 <P>
  62 The following classes and interfaces make up the <code>javax.sql.rowset.spi</code>
  63 package:
  64 <UL>
  65   <LI><code>SyncFactory</code>
  66   <LI><code>SyncProvider</code>
  67   <LI><code>SyncFactoryException</code>
  68   <LI><code>SyncProviderException</code>
  69   <LI><code>SyncResolver</code>
  70   <LI><code>XmlReader</code>
  71   <LI><code>XmlWriter</code>
  72   <LI><code>TransactionalWriter</code>
  73 </UL>
  74 The following interfaces, in the <code>javax.sql</code> package, are also part of the SPI:
  75 <UL>
  76   <LI><code>RowSetReader</code>
  77   <LI><code>RowSetWriter</code>
  78 </UL>
  79 <P>
  80 A <code>SyncProvider</code> implementation provides a disconnected <code>RowSet</code>


 184 to be thrown.  If no provider is specified,
 185 the <code>SyncFactory</code> singleton will create an instance of the default
 186 provider implementation, <code>RIOptimisticProvider</code>,
 187 and pass it to the requesting <code>RowSet</code> object.
 188 
 189 <P>
 190 If a <code>WebRowSet</code> object does not specify a provider in its constructor, the
 191 <code>SyncFactory</code> will give it an instance of <code>RIOptimisticProvider</code>.
 192 However, the constructor for <code>WebRowSet</code> is implemented to set the provider 
 193 to the <code>RIXMLProvider</code>, which reads and writes a <code>RowSet</code> object
 194 in XML format.
 195 <P>
 196 See the <a href="SyncProvider.html">SyncProvider</a> class
 197 specification for further details.
 198 <p>
 199 Vendors may develop a <tt>SyncProvider</tt> implementation with any one of the possible
 200 levels of synchronization, thus giving <code>RowSet</code> objects a choice of
 201 synchronization mechanisms.  A vendor can make its implementation available by 
 202 registering the fully qualified class name with Oracle Corporation at
 203 <code>jdbc@sun.com</code>. This process is discussed in further detail below. 
 204 <P>
 205 
 206 <a name="arch"><h3>2.0 Service Provider Interface Architecture</h3>
 207 <ul>
 208 <b>2.1 Overview</b>
 209 <p>
 210 The Service Provider Interface provides a pluggable mechanism by which
 211 <code>SyncProvider</code> implementations can be registered and then generated when
 212 required. The lazy reference mechanism employed by the <code>SyncFactory</code> limits
 213 unnecessary resource consumption by not creating an instance until it is 
 214 required by a disconnected
 215 <code>RowSet</code> object. The <code>SyncFactory</code> class also provides
 216 a standard API to configure logging options and streams that <b>may</b> be provided
 217 by a particular <code>SyncProvider</code> implementation.
 218 <p>
 219 <b>2.2 Registering with the <code>SyncFactory</code></b>
 220 <p>
 221 A third party <code>SyncProvider</code> implementation must be registered with the 
 222 <code>SyncFactory</code> in order for a disconnected <code>RowSet</code> object 
 223 to obtain it and thereby use its <code>javax.sql.RowSetReader</code> and 
 224 <code>javax.sql.RowSetWriter</code>
 225 implementations. The following registration mechanisms are available to all 
 226 <code>SyncProvider</code> implementations:
 227 <ul>
 228 <li><b>System properties</b> - Properties set at the command line. These
 229 properties are set at run time and apply system-wide per invocation of the Java
 230 application. See the section <a href="#reldocs">"Related Documentation"</a>
 231 further related information.
 232 <p>
 233 <li><b>Property Files</b> - Properties specified in a standard property file.
 234 This can be specified using a System Property or by modifying a standard
 235 property file located in the platform run-time. The
 236 reference implementation of this technology includes a standard property
 237 file than can be edited to add additional <code>SyncProvider</code> objects.
 238 <p> 
 239 <li><b>JNDI Context</b> - Available providers can be registered on a JNDI
 240 context. The <tt>SyncFactory</tt> will attempt to load <tt>SyncProvider</tt>
 241 objects bound to the context and register them with the factory. This
 242 context must be supplied to the <code>SyncFactory</code> for the mechanism to 
 243 function correctly.
 244 </ul>
 245 <p>
 246 Details on how to specify the system properties or properties in a property file
 247 and how to configure the JNDI Context are explained in detail in the
 248 <a href="SyncFactory.html"><code>SyncFactory</code></a> class description.
 249 <p>
 250 <b>2.3 SyncFactory Provider Instance Generation Policies</b>
 251 <p>
 252 The <code>SyncFactory</code> generates a requested <code>SyncProvider</code>
 253 object if the provider has been correctly registered.  The
 254 following policies are adhered to when either a disconnected <code>RowSet</code> object
 255 is instantiated with a specified <code>SyncProvider</code> implementation or is 
 256 reconfigured at runtime with an alternative <code>SyncProvider</code> object.
 257 <ul>
 258 <li> If a <code>SyncProvider</code> object is specified and the <code>SyncFactory</code>
 259 contains <i>no</i> reference to the provider, a <code>SyncFactoryException</code> is 
 260 thrown.
 261 <p>
 262 <li> If a <code>SyncProvider</code> object is specified and the <code>SyncFactory</code>
 263 contains a reference to the provider, the requested provider is supplied.
 264 <p>
 265 <li> If no <code>SyncProvider</code> object is specified, the reference
 266 implementation provider <code>RIOptimisticProvider</code> is supplied.
 267 </ul>
 268 <p>
 269 These policies are explored in more detail in the <a href="SyncFactory.html">
 270 <code>SyncFactory</code></a> class.
 271 </ul>
 272 
 273 <li><a name="impl"><h3>3.0 SyncProvider Implementer's Guide</h3>
 274 <ul>
 275 <b>3.1 Requirements</b>
 276 <p>
 277 A compliant <code>SyncProvider</code> implementation that is fully pluggable
 278 into the <code>SyncFactory</code> <b>must</b> extend and implement all
 279 abstract methods in the <a href="SyncProvider.html"><code>SyncProvider</code></a>
 280 class. In addition, an implementation <b>must</b> determine the 
 281 grade, locking and updatable view capabilities defined in the
 282 <code>SyncProvider</code> class definition. One or more of the
 283 <code>SyncProvider</code> description criteria <b>must</b> be supported. It
 284 is expected that vendor implementations will offer a range of grade, locking, and
 285 updatable view capabilities.
 286 <p>
 287 Furthermore, the <code>SyncProvider</code> naming convention <b>must</b> be followed as
 288 detailed in the <a href="SyncProvider.html"><code>SyncProvider</code></a> class
 289 description.
 290 <p>
 291 <b>3.2 Grades</b>
 292 <p>
 293 JSR 114 defines a set of grades to describe the quality of synchronization
 294 a <code>SyncProvider</code> object can offer a disconnected <code>RowSet</code>
 295 object. These grades are listed from the lowest quality of service to the highest.
 296 <ul>
 297 <li><b>GRADE_NONE</b> - No synchronization with the originating data source is
 298 provided. A <code>SyncProvider</code> implementation returning this grade will simply
 299 attempt to write any data that has changed in the <code>RowSet</code> object to the
 300 underlying data source, overwriting whatever is there. No attempt is made to compare 
 301 original values with current values to see if there is a conflict. The 
 302 <code>RIXMLProvider</code> is implemented with this grade.
 303 <p>
 304 <li><b>GRADE_CHECK_MODIFIED_AT_COMMIT</b> - A low grade of optimistic synchronization.
 305 A <code>SyncProvider</code> implementation returning this grade
 306 will check for conflicts in rows that have changed between the last synchronization 
 307 and the current synchronization under way. Any changes in the originating data source
 308 that have been modified will not be reflected in the disconnected <code>RowSet</code>
 309 object. If there are no conflicts, changes in the <code>RowSet</code> object will be
 310 written to the data source. If there are conflicts, no changes are written.
 311 The <code>RIOptimisticProvider</code> implementation uses this grade.
 312 <p>
 313 <li><b>GRADE_CHECK_ALL_AT_COMMIT</b> - A high grade of optimistic synchronization.
 314 A <code>SyncProvider</code> implementation   returning this grade
 315 will check all rows, including rows that have not changed in the disconnected
 316 <code>RowSet</code> object. In this way, any changes to rows in the underlying
 317 data source will be reflected in the disconnected <code>RowSet</code> object
 318 when the synchronization finishes successfully.
 319 <p>
 320 <li><b>GRADE_LOCK_WHEN_MODIFIED</b> - A pessimistic grade of synchronization.
 321 <code>SyncProvider</code> implementations returning this grade will lock
 322 the row in the originating  data source that corresponds to the row being changed
 323 in the <code>RowSet</code> object to reduce the possibility of other
 324 processes modifying the same data in the data source.
 325 <p>
 326 <li><b>GRADE_LOCK_WHEN_LOADED</b> - A higher pessimistic synchronization grade.
 327 A <code>SyncProvider</code> implementation returning this grade will lock
 328 the entire view and/or  table affected by the original query used to
 329 populate a <code>RowSet</code> object.
 330 </ul>
 331 <p>
 332 <b>3.3 Locks</b>
 333 <p>
 334 JSR 114 defines a set of constants that specify whether any locks have been
 335 placed on a <code>RowSet</code> object's underlying data source and, if so,
 336 on which constructs the locks are placed.  These locks will remain on the data
 337 source while the <code>RowSet</code> object is disconnected from the data source.
 338 <P>
 339 These constants <b>should</b> be considered complementary to the 
 340 grade constants. The default setting for the majority of grade settings requires
 341 that no data source locks remain when a <code>RowSet</code> object is disconnected 
 342 from its data source.
 343 The grades <code>GRADE_LOCK_WHEN_MODIFIED</code> and
 344 <code>GRADE_LOCK_WHEN_LOADED</code> allow a disconnected <code>RowSet</code> object
 345 to have a fine-grained control over the degree of locking.
 346 <ul>
 347 <li><b>DATASOURCE_NO_LOCK</b> - No locks remain on the originating data source. 
 348 This is the default lock setting for all <code>SyncProvider</code> implementations 
 349 unless otherwise directed by a <code>RowSet</code> object.
 350 <p>
 351 <li><b>DATASOURCE_ROW_LOCK</b> - A lock is placed on the rows that are touched by
 352 the original SQL query used to populate the <code>RowSet</code> object.
 353 <p> 
 354 <li><b>DATASOURCE_TABLE_LOCK</b> - A lock is placed on all tables that are touched
 355 by the query that was used to populate the <code>RowSet</code> object.
 356 <p>
 357 <li><b>DATASOURCE_DB_LOCK</b>
 358 A lock is placed on the entire data source that is used by the <code>RowSet</code>
 359 object.
 360 </ul>
 361 <p>
 362 <b>3.4 Updatable Views</b>
 363 <p>
 364 A <code>RowSet</code> object may be populated with data from an SQL <code>VIEW</code>.
 365 The following constants indicate whether a <code>SyncProvider</code> object can
 366 update data in the table or tables from which the <code>VIEW</code> was derived.
 367 <ul>
 368 <li><b>UPDATABLE_VIEW_SYNC</b>
 369 Indicates that a <code>SyncProvider</code> implementation  supports synchronization
 370 to the table or tables from which the SQL <code>VIEW</code> used to populate  a
 371 a <code>RowSet</code> object is derived.
 372 <p>
 373 <li><b>NONUPDATABLE_VIEW_SYNC</b>
 374 Indicates that a <code>SyncProvider</code> implementation  does <b>not</b> support
 375 synchronization to the table or tables from which the SQL <code>VIEW</code> 
 376 used to populate  a <code>RowSet</code> object is derived.
 377 </ul>
 378 <p>
 379 <b>3.5 Usage of <code>SyncProvider</code> Grading and Locking</b>
 380 <p>
 381 In the example below, the reference <tt>CachedRowSetImpl</tt> implementation
 382 reconfigures its current <tt>SyncProvider</tt> object by calling the 
 383 <tt>setSyncProvider</tt> method.<br>
 384        
 385 <PRE>
 386     CachedRowSetImpl crs = new CachedRowSetImpl();
 387     crs.setSyncProvider("com.foo.bar.HASyncProvider");
 388 </PRE>
 389     An application can retrieve the <tt>SyncProvider</tt> object currently in use
 390 by a disconnected <code>RowSet</code> object. It can also retrieve the
 391 grade of synchronization with which the provider was implemented and the degree of
 392 locking currently in use.  In addition, an application has the flexibility to set


 427        // A lock is placed on the rows that are  touched by the original 
 428        // SQL statement used to populate
 429        // the RowSet object that is using the SyncProvider
 430        break;
 431 
 432       case: DATASOURCE_TABLE_LOCK
 433        // A lock is placed on  all tables that are touched by the original 
 434        // SQL statement used to populated
 435        // the RowSet object that is using the SyncProvider
 436        break;
 437 
 438 </PRE>
 439     It is also possible using the static utility method in the
 440 <code>SyncFactory</code> class to determine the list of <code>SyncProvider</code>
 441 implementations currently registered with the <code>SyncFactory</code>.
 442        
 443 <pre>
 444         Enumeration e = SyncFactory.getRegisteredProviders();
 445 </pre>    
 446 
 447 </ul>
 448 
 449 <h3><a name="resolving">4.0 Resolving Synchronization Conflicts</h3>
 450 
 451 The interface <code>SyncResolver</code> provides a way for an application to
 452 decide manually what to do when a conflict occurs. When the <code>CachedRowSet</code>
 453 method <code>acceptChanges</code> finishes and has detected one or more conflicts,
 454 it throws a <code>SyncProviderException</code> object.  An application can
 455 catch the exception and
 456 have it retrieve a <code>SyncResolver</code> object by calling the method
 457 <code>SyncProviderException.getSyncResolver()</code>. 
 458 <P>
 459 A <code>SyncResolver</code> object, which is a special kind of 
 460 <code>CachedRowSet</code> object or
 461 a <code>JdbcRowSet</code> object that has implemented the <code>SyncResolver</code> 
 462 interface,  examines the conflicts row by row. It is a duplicate of the 
 463 <code>RowSet</code> object being synchronized except that it contains only the data
 464 from the data source this is causing a conflict. All of the other column values are
 465 set to <code>null</code>. To navigate from one conflict value to another, a
 466 <code>SyncResolver</code> object provides the methods <code>nextConflict</code> and
 467 <code>previousConflict</code>.
 468 <P>
 469 The <code>SyncResolver</code> interface also


 474  <LI>setting the value that should be in the data source if it needs to be changed
 475      or setting the value that should be in the <code>RowSet</code> object if it needs
 476      to be changed
 477 </UL>
 478 <P>
 479 When the <code>CachedRowSet</code> method <code>acceptChanges</code> is called, it 
 480 delegates to the <code>RowSet</code> object's  <code>SyncProvider</code> object.
 481 How the writer provided by that <code>SyncProvider</code> object is implemented
 482 determines what level (grade) of checking for conflicts will be done.  After all 
 483 checking for conflicts is completed and one or more conflicts has been found, the method
 484 <code>acceptChanges</code> throws a <code>SyncProviderException</code> object. The
 485 application can catch the exception and use it to obtain a <code>SyncResolver</code> object.  
 486 <P>
 487 The application can then use <code>SyncResolver</code> methods to get information
 488 about each conflict and decide what to do.  If the application logic or the user
 489 decides that a value in the <code>RowSet</code> object should be the one to
 490 persist, the application or user can overwrite the data source value with it.  
 491 <P>
 492 The comment for the <code>SyncResolver</code> interface has more detail.
 493 
 494 <a name="relspec"><h3>5.0 Related Specifications</h3>
 495 <ul>
 496 <li><a href="http://java.sun.com/products/jndi">JNDI 1.3</a>
 497 <li><a href="{@docRoot}/../technotes/guides/logging/index.html">Java Logging
 498 APIs</a>
 499 </ul>
 500 <a name="reldocs"><h3>6.0 Related Documentation</h3>
 501 <ul>
 502 <li><a href="{@docRoot}/../technotes/tools/index.html#basic">System
 503 properties</a>
 504 <li>Resource Files
 505 <li><a href="http://java.sun.com/tutorial/jdbc">DataSource for JDBC
 506 Connections</a>
 507 </ul>
 508 
 509 </body>
 510 </html>


  29 
  30 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  31 or visit www.oracle.com if you need additional information or have any
  32 questions.
  33 -->
  34   <title>javax.sql.rowset.spi</title>
  35 
  36 </head>
  37   <body bgcolor="#ffffff">
  38 
  39 The standard classes and interfaces that a third party vendor has to
  40 use in its implementation of a synchronization provider. These classes and 
  41 interfaces are referred to as the Service Provider Interface (SPI). A vendor may 
  42 have its implementation included on the JDBC web page that lists available
  43 <code>SyncProvider</code> implementations by sending email to <code>jdbc@sun.com</code>.
  44 Doing this helps make developers aware of the implementation. To make it possible
  45 for a <code>RowSet</code> object to use an implementation, the vendor must register
  46 it with the <code>SyncFactory</code> singleton. (See the class comment for
  47 <code>SyncProvider</code> for a full explanation of the registration process and 
  48 the naming convention to be used.)
  49 
  50 <h2>Table of Contents</h2>
  51 <ul>
  52 <li><a href="#pkgspec">1.0 Package Specification</a>
  53 <li><a href="#arch">2.0 Service Provider Architecture</a>
  54 <li><a href="#impl">3.0 Implementer's Guide</a>
  55 <li><a href="#resolving">4.0 Resolving Synchronization Conflicts</a>
  56 <li><a href="#relspec">5.0 Related Specifications</a>
  57 <li><a href="#reldocs">6.0 Related Documentation</a>
  58 </ul>
  59 
  60 <h3><a name="pkgspec">1.0 Package Specification</a></h3>
  61 <P>
  62 The following classes and interfaces make up the <code>javax.sql.rowset.spi</code>
  63 package:
  64 <UL>
  65   <LI><code>SyncFactory</code>
  66   <LI><code>SyncProvider</code>
  67   <LI><code>SyncFactoryException</code>
  68   <LI><code>SyncProviderException</code>
  69   <LI><code>SyncResolver</code>
  70   <LI><code>XmlReader</code>
  71   <LI><code>XmlWriter</code>
  72   <LI><code>TransactionalWriter</code>
  73 </UL>
  74 The following interfaces, in the <code>javax.sql</code> package, are also part of the SPI:
  75 <UL>
  76   <LI><code>RowSetReader</code>
  77   <LI><code>RowSetWriter</code>
  78 </UL>
  79 <P>
  80 A <code>SyncProvider</code> implementation provides a disconnected <code>RowSet</code>


 184 to be thrown.  If no provider is specified,
 185 the <code>SyncFactory</code> singleton will create an instance of the default
 186 provider implementation, <code>RIOptimisticProvider</code>,
 187 and pass it to the requesting <code>RowSet</code> object.
 188 
 189 <P>
 190 If a <code>WebRowSet</code> object does not specify a provider in its constructor, the
 191 <code>SyncFactory</code> will give it an instance of <code>RIOptimisticProvider</code>.
 192 However, the constructor for <code>WebRowSet</code> is implemented to set the provider 
 193 to the <code>RIXMLProvider</code>, which reads and writes a <code>RowSet</code> object
 194 in XML format.
 195 <P>
 196 See the <a href="SyncProvider.html">SyncProvider</a> class
 197 specification for further details.
 198 <p>
 199 Vendors may develop a <tt>SyncProvider</tt> implementation with any one of the possible
 200 levels of synchronization, thus giving <code>RowSet</code> objects a choice of
 201 synchronization mechanisms.  A vendor can make its implementation available by 
 202 registering the fully qualified class name with Oracle Corporation at
 203 <code>jdbc@sun.com</code>. This process is discussed in further detail below. 

 204 
 205 <h3><a name="arch">2.0 Service Provider Interface Architecture</a></h3>

 206 <b>2.1 Overview</b>
 207 <p>
 208 The Service Provider Interface provides a pluggable mechanism by which
 209 <code>SyncProvider</code> implementations can be registered and then generated when
 210 required. The lazy reference mechanism employed by the <code>SyncFactory</code> limits
 211 unnecessary resource consumption by not creating an instance until it is 
 212 required by a disconnected
 213 <code>RowSet</code> object. The <code>SyncFactory</code> class also provides
 214 a standard API to configure logging options and streams that <b>may</b> be provided
 215 by a particular <code>SyncProvider</code> implementation.
 216 <p>
 217 <b>2.2 Registering with the <code>SyncFactory</code></b>
 218 <p>
 219 A third party <code>SyncProvider</code> implementation must be registered with the 
 220 <code>SyncFactory</code> in order for a disconnected <code>RowSet</code> object 
 221 to obtain it and thereby use its <code>javax.sql.RowSetReader</code> and 
 222 <code>javax.sql.RowSetWriter</code>
 223 implementations. The following registration mechanisms are available to all 
 224 <code>SyncProvider</code> implementations:
 225 <ul>
 226 <li><b>System properties</b> - Properties set at the command line. These
 227 properties are set at run time and apply system-wide per invocation of the Java
 228 application. See the section <a href="#reldocs">"Related Documentation"</a>
 229 further related information.
 230 
 231 <li><b>Property Files</b> - Properties specified in a standard property file.
 232 This can be specified using a System Property or by modifying a standard
 233 property file located in the platform run-time. The
 234 reference implementation of this technology includes a standard property
 235 file than can be edited to add additional <code>SyncProvider</code> objects.
 236 
 237 <li><b>JNDI Context</b> - Available providers can be registered on a JNDI
 238 context. The <tt>SyncFactory</tt> will attempt to load <tt>SyncProvider</tt>
 239 objects bound to the context and register them with the factory. This
 240 context must be supplied to the <code>SyncFactory</code> for the mechanism to 
 241 function correctly.
 242 </ul>
 243 <p>
 244 Details on how to specify the system properties or properties in a property file
 245 and how to configure the JNDI Context are explained in detail in the
 246 <a href="SyncFactory.html"><code>SyncFactory</code></a> class description.
 247 <p>
 248 <b>2.3 SyncFactory Provider Instance Generation Policies</b>
 249 <p>
 250 The <code>SyncFactory</code> generates a requested <code>SyncProvider</code>
 251 object if the provider has been correctly registered.  The
 252 following policies are adhered to when either a disconnected <code>RowSet</code> object
 253 is instantiated with a specified <code>SyncProvider</code> implementation or is 
 254 reconfigured at runtime with an alternative <code>SyncProvider</code> object.
 255 <ul>
 256 <li> If a <code>SyncProvider</code> object is specified and the <code>SyncFactory</code>
 257 contains <i>no</i> reference to the provider, a <code>SyncFactoryException</code> is 
 258 thrown.
 259 
 260 <li> If a <code>SyncProvider</code> object is specified and the <code>SyncFactory</code>
 261 contains a reference to the provider, the requested provider is supplied.
 262 
 263 <li> If no <code>SyncProvider</code> object is specified, the reference
 264 implementation provider <code>RIOptimisticProvider</code> is supplied.
 265 </ul>
 266 <p>
 267 These policies are explored in more detail in the <a href="SyncFactory.html">
 268 <code>SyncFactory</code></a> class.

 269 
 270 <h3><a name="impl">3.0 SyncProvider Implementer's Guide</a></h3>
 271 
 272 <b>3.1 Requirements</b>
 273 <p>
 274 A compliant <code>SyncProvider</code> implementation that is fully pluggable
 275 into the <code>SyncFactory</code> <b>must</b> extend and implement all
 276 abstract methods in the <a href="SyncProvider.html"><code>SyncProvider</code></a>
 277 class. In addition, an implementation <b>must</b> determine the 
 278 grade, locking and updatable view capabilities defined in the
 279 <code>SyncProvider</code> class definition. One or more of the
 280 <code>SyncProvider</code> description criteria <b>must</b> be supported. It
 281 is expected that vendor implementations will offer a range of grade, locking, and
 282 updatable view capabilities.
 283 <p>
 284 Furthermore, the <code>SyncProvider</code> naming convention <b>must</b> be followed as
 285 detailed in the <a href="SyncProvider.html"><code>SyncProvider</code></a> class
 286 description.
 287 <p>
 288 <b>3.2 Grades</b>
 289 <p>
 290 JSR 114 defines a set of grades to describe the quality of synchronization
 291 a <code>SyncProvider</code> object can offer a disconnected <code>RowSet</code>
 292 object. These grades are listed from the lowest quality of service to the highest.
 293 <ul>
 294 <li><b>GRADE_NONE</b> - No synchronization with the originating data source is
 295 provided. A <code>SyncProvider</code> implementation returning this grade will simply
 296 attempt to write any data that has changed in the <code>RowSet</code> object to the
 297 underlying data source, overwriting whatever is there. No attempt is made to compare 
 298 original values with current values to see if there is a conflict. The 
 299 <code>RIXMLProvider</code> is implemented with this grade.
 300 
 301 <li><b>GRADE_CHECK_MODIFIED_AT_COMMIT</b> - A low grade of optimistic synchronization.
 302 A <code>SyncProvider</code> implementation returning this grade
 303 will check for conflicts in rows that have changed between the last synchronization 
 304 and the current synchronization under way. Any changes in the originating data source
 305 that have been modified will not be reflected in the disconnected <code>RowSet</code>
 306 object. If there are no conflicts, changes in the <code>RowSet</code> object will be
 307 written to the data source. If there are conflicts, no changes are written.
 308 The <code>RIOptimisticProvider</code> implementation uses this grade.
 309 
 310 <li><b>GRADE_CHECK_ALL_AT_COMMIT</b> - A high grade of optimistic synchronization.
 311 A <code>SyncProvider</code> implementation   returning this grade
 312 will check all rows, including rows that have not changed in the disconnected
 313 <code>RowSet</code> object. In this way, any changes to rows in the underlying
 314 data source will be reflected in the disconnected <code>RowSet</code> object
 315 when the synchronization finishes successfully.
 316 
 317 <li><b>GRADE_LOCK_WHEN_MODIFIED</b> - A pessimistic grade of synchronization.
 318 <code>SyncProvider</code> implementations returning this grade will lock
 319 the row in the originating  data source that corresponds to the row being changed
 320 in the <code>RowSet</code> object to reduce the possibility of other
 321 processes modifying the same data in the data source.
 322 
 323 <li><b>GRADE_LOCK_WHEN_LOADED</b> - A higher pessimistic synchronization grade.
 324 A <code>SyncProvider</code> implementation returning this grade will lock
 325 the entire view and/or  table affected by the original query used to
 326 populate a <code>RowSet</code> object.
 327 </ul>
 328 <p>
 329 <b>3.3 Locks</b>
 330 <p>
 331 JSR 114 defines a set of constants that specify whether any locks have been
 332 placed on a <code>RowSet</code> object's underlying data source and, if so,
 333 on which constructs the locks are placed.  These locks will remain on the data
 334 source while the <code>RowSet</code> object is disconnected from the data source.
 335 <P>
 336 These constants <b>should</b> be considered complementary to the 
 337 grade constants. The default setting for the majority of grade settings requires
 338 that no data source locks remain when a <code>RowSet</code> object is disconnected 
 339 from its data source.
 340 The grades <code>GRADE_LOCK_WHEN_MODIFIED</code> and
 341 <code>GRADE_LOCK_WHEN_LOADED</code> allow a disconnected <code>RowSet</code> object
 342 to have a fine-grained control over the degree of locking.
 343 <ul>
 344 <li><b>DATASOURCE_NO_LOCK</b> - No locks remain on the originating data source. 
 345 This is the default lock setting for all <code>SyncProvider</code> implementations 
 346 unless otherwise directed by a <code>RowSet</code> object.
 347 
 348 <li><b>DATASOURCE_ROW_LOCK</b> - A lock is placed on the rows that are touched by
 349 the original SQL query used to populate the <code>RowSet</code> object.
 350 
 351 <li><b>DATASOURCE_TABLE_LOCK</b> - A lock is placed on all tables that are touched
 352 by the query that was used to populate the <code>RowSet</code> object.
 353 
 354 <li><b>DATASOURCE_DB_LOCK</b>
 355 A lock is placed on the entire data source that is used by the <code>RowSet</code>
 356 object.
 357 </ul>
 358 <p>
 359 <b>3.4 Updatable Views</b>
 360 <p>
 361 A <code>RowSet</code> object may be populated with data from an SQL <code>VIEW</code>.
 362 The following constants indicate whether a <code>SyncProvider</code> object can
 363 update data in the table or tables from which the <code>VIEW</code> was derived.
 364 <ul>
 365 <li><b>UPDATABLE_VIEW_SYNC</b>
 366 Indicates that a <code>SyncProvider</code> implementation  supports synchronization
 367 to the table or tables from which the SQL <code>VIEW</code> used to populate  a
 368 a <code>RowSet</code> object is derived.
 369 
 370 <li><b>NONUPDATABLE_VIEW_SYNC</b>
 371 Indicates that a <code>SyncProvider</code> implementation  does <b>not</b> support
 372 synchronization to the table or tables from which the SQL <code>VIEW</code> 
 373 used to populate  a <code>RowSet</code> object is derived.
 374 </ul>
 375 <p>
 376 <b>3.5 Usage of <code>SyncProvider</code> Grading and Locking</b>
 377 <p>
 378 In the example below, the reference <tt>CachedRowSetImpl</tt> implementation
 379 reconfigures its current <tt>SyncProvider</tt> object by calling the 
 380 <tt>setSyncProvider</tt> method.<br>
 381 
 382 <PRE>
 383     CachedRowSetImpl crs = new CachedRowSetImpl();
 384     crs.setSyncProvider("com.foo.bar.HASyncProvider");
 385 </PRE>
 386     An application can retrieve the <tt>SyncProvider</tt> object currently in use
 387 by a disconnected <code>RowSet</code> object. It can also retrieve the
 388 grade of synchronization with which the provider was implemented and the degree of
 389 locking currently in use.  In addition, an application has the flexibility to set


 424        // A lock is placed on the rows that are  touched by the original 
 425        // SQL statement used to populate
 426        // the RowSet object that is using the SyncProvider
 427        break;
 428 
 429       case: DATASOURCE_TABLE_LOCK
 430        // A lock is placed on  all tables that are touched by the original 
 431        // SQL statement used to populated
 432        // the RowSet object that is using the SyncProvider
 433        break;
 434 
 435 </PRE>
 436     It is also possible using the static utility method in the
 437 <code>SyncFactory</code> class to determine the list of <code>SyncProvider</code>
 438 implementations currently registered with the <code>SyncFactory</code>.
 439 
 440 <pre>
 441        Enumeration e = SyncFactory.getRegisteredProviders();
 442 </pre>
 443 

 444 
 445 <h3><a name="resolving">4.0 Resolving Synchronization Conflicts</a></h3>
 446 
 447 The interface <code>SyncResolver</code> provides a way for an application to
 448 decide manually what to do when a conflict occurs. When the <code>CachedRowSet</code>
 449 method <code>acceptChanges</code> finishes and has detected one or more conflicts,
 450 it throws a <code>SyncProviderException</code> object.  An application can
 451 catch the exception and
 452 have it retrieve a <code>SyncResolver</code> object by calling the method
 453 <code>SyncProviderException.getSyncResolver()</code>. 
 454 <P>
 455 A <code>SyncResolver</code> object, which is a special kind of 
 456 <code>CachedRowSet</code> object or
 457 a <code>JdbcRowSet</code> object that has implemented the <code>SyncResolver</code> 
 458 interface,  examines the conflicts row by row. It is a duplicate of the 
 459 <code>RowSet</code> object being synchronized except that it contains only the data
 460 from the data source this is causing a conflict. All of the other column values are
 461 set to <code>null</code>. To navigate from one conflict value to another, a
 462 <code>SyncResolver</code> object provides the methods <code>nextConflict</code> and
 463 <code>previousConflict</code>.
 464 <P>
 465 The <code>SyncResolver</code> interface also


 470  <LI>setting the value that should be in the data source if it needs to be changed
 471      or setting the value that should be in the <code>RowSet</code> object if it needs
 472      to be changed
 473 </UL>
 474 <P>
 475 When the <code>CachedRowSet</code> method <code>acceptChanges</code> is called, it 
 476 delegates to the <code>RowSet</code> object's  <code>SyncProvider</code> object.
 477 How the writer provided by that <code>SyncProvider</code> object is implemented
 478 determines what level (grade) of checking for conflicts will be done.  After all 
 479 checking for conflicts is completed and one or more conflicts has been found, the method
 480 <code>acceptChanges</code> throws a <code>SyncProviderException</code> object. The
 481 application can catch the exception and use it to obtain a <code>SyncResolver</code> object.  
 482 <P>
 483 The application can then use <code>SyncResolver</code> methods to get information
 484 about each conflict and decide what to do.  If the application logic or the user
 485 decides that a value in the <code>RowSet</code> object should be the one to
 486 persist, the application or user can overwrite the data source value with it.  
 487 <P>
 488 The comment for the <code>SyncResolver</code> interface has more detail.
 489 
 490 <h3><a name="relspec">5.0 Related Specifications</a></h3>
 491 <ul>
 492 <li><a href="http://java.sun.com/products/jndi">JNDI 1.3</a>
 493 <li><a href="{@docRoot}/../technotes/guides/logging/index.html">Java Logging
 494 APIs</a>
 495 </ul>
 496 <h3><a name="reldocs">6.0 Related Documentation</a></h3>
 497 <ul>
 498 <li><a href="{@docRoot}/../technotes/tools/index.html#basic">System
 499 properties</a>
 500 <li>Resource Files
 501 <li><a href="http://java.sun.com/tutorial/jdbc">DataSource for JDBC
 502 Connections</a>
 503 </ul>
 504 
 505 </body>
 506 </html>