1 <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
2 <html>
3 <head>
4
5 <meta http-equiv="Content-Type"
6 content="text/html; charset=iso-8859-1">
7
8 <meta name="GENERATOR"
9 content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]">
10 <!--
11 Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights reserved.
12 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
13
14 This code is free software; you can redistribute it and/or modify it
15 under the terms of the GNU General Public License version 2 only, as
16 published by the Free Software Foundation. Oracle designates this
17 particular file as subject to the "Classpath" exception as provided
18 by Oracle in the LICENSE file that accompanied this code.
19
20 This code is distributed in the hope that it will be useful, but WITHOUT
21 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
22 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
23 version 2 for more details (a copy is included in the LICENSE file that
24 accompanied this code).
25
26 You should have received a copy of the GNU General Public License version
27 2 along with this work; if not, write to the Free Software Foundation,
28 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
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>
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 <code>SyncProvider</code> 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>
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
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://docs.oracle.com/javase/jndi/tutorial/index.html">JNDI</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://docs.oracle.com/javase/tutorial/jdbc/">DataSource for JDBC
502 Connections</a>
503 </ul>
504
505 </body>
506 </html>
|
1 <!doctype html>
2 <html lang="en">
3 <head>
4
5 <meta http-equiv="Content-Type"
6 content="text/html; charset=iso-8859-1">
7
8 <meta name="GENERATOR"
9 content="Mozilla/4.79 [en] (Windows NT 5.0; U) [Netscape]">
10 <!--
11 Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights reserved.
12 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
13
14 This code is free software; you can redistribute it and/or modify it
15 under the terms of the GNU General Public License version 2 only, as
16 published by the Free Software Foundation. Oracle designates this
17 particular file as subject to the "Classpath" exception as provided
18 by Oracle in the LICENSE file that accompanied this code.
19
20 This code is distributed in the hope that it will be useful, but WITHOUT
21 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
22 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
23 version 2 for more details (a copy is included in the LICENSE file that
24 accompanied this code).
25
26 You should have received a copy of the GNU General Public License version
27 2 along with this work; if not, write to the Free Software Foundation,
28 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
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>
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 id="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>
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 <code>SyncProvider</code> 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 id="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>
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 id="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
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 id="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 id="relspec">5.0 Related Specifications</a></h3>
491 <ul>
492 <li><a href="http://docs.oracle.com/javase/jndi/tutorial/index.html">JNDI</a>
493 <li><a href="{@docRoot}/../technotes/guides/logging/index.html">Java Logging
494 APIs</a>
495 </ul>
496 <h3><a id="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://docs.oracle.com/javase/tutorial/jdbc/">DataSource for JDBC
502 Connections</a>
503 </ul>
504
505 </body>
506 </html>
|