| J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 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 | |
| 12 | Copyright 2003-2006 Sun Microsystems, Inc. All Rights Reserved. |
| 13 | DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| 14 | |
| 15 | This code is free software; you can redistribute it and/or modify it |
| 16 | under the terms of the GNU General Public License version 2 only, as |
| 17 | published by the Free Software Foundation. Sun designates this |
| 18 | particular file as subject to the "Classpath" exception as provided |
| 19 | by Sun in the LICENSE file that accompanied this code. |
| 20 | |
| 21 | This code is distributed in the hope that it will be useful, but WITHOUT |
| 22 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 23 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| 24 | version 2 for more details (a copy is included in the LICENSE file that |
| 25 | accompanied this code). |
| 26 | |
| 27 | You should have received a copy of the GNU General Public License version |
| 28 | 2 along with this work; if not, write to the Free Software Foundation, |
| 29 | Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| 30 | |
| 31 | Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 32 | CA 95054 USA or visit www.sun.com if you need additional information or |
| 33 | have any questions. |
| 34 | --> |
| 35 | <title>javax.sql.rowset.providers Package</title> |
| 36 | </head> |
| 37 | <body bgcolor="#ffffff"> |
| 38 | Repository for the <tt>RowSet</tt> reference implementations of the |
| 39 | <tt>SyncProvider</tt> abstract class. These implementations provide a |
| 40 | disconnected <code>RowSet</code> |
| 41 | object with the ability to synchronize the data in the underlying data |
| 42 | source with its data. These implementations are provided as |
| 43 | the default <tt>SyncProvider</tt> implementations and are accessible via the |
| 44 | <tt>SyncProvider</tt> SPI managed by the <tt>SyncFactory</tt>. |
| 45 | |
| 46 | <h3>1.0 <code>SyncProvider</code> Reference Implementations</h3> |
| 47 | The main job of a <tt>SyncProvider</tt> implementation is to manage |
| 48 | the reader and writer mechanisms. |
| 49 | The <tt>SyncProvider</tt> SPI, as specified in the <tt>javax.sql.rowset.spi</tt> |
| 50 | package, provides a pluggable mechanism by which <tt>javax.sql.RowSetReader</tt> |
| 51 | and <tt>javax.sql.RowSetWriter</tt> implementations can be supplied to a disconnected |
| 52 | <tt>RowSet</tt> object. |
| 53 | <P> |
| 54 | A reader, a <code>javax.sql.RowSetReader</code> |
| 55 | object, does the work necessary to populate a <code>RowSet</code> object with data. |
| 56 | A writer, a <code>javax.sql.RowSetWriter</code> object, does the work necessary for |
| 57 | synchronizing a <code>RowSet</code> object's data with the data in the originating |
| 58 | source of data. Put another way, a writer writes a <code>RowSet</code> |
| 59 | object's data back to the data source. |
| 60 | <P> |
| 61 | Generally speaking, the course of events is this. The reader makes a connection to |
| 62 | the data source and reads the data from a <code>ResultSet</code> object into its |
| 63 | <code>RowSet</code> object. Then it closes the connection. While |
| 64 | the <code>RowSet</code> object is disconnected, an application makes some modifications |
| 65 | to the data and calls the method <code>acceptChanges</code>. At this point, the |
| 66 | writer is called to write the changes back to the database table or view |
| 67 | from which the original data came. This is called <i>synchronization</i>. |
| 68 | <P> |
| 69 | If the data in the originating data source has not changed, there is no problem |
| 70 | with just writing the <code>RowSet</code> object's new data to the data source. |
| 71 | If it has changed, however, there is a conflict that needs to be resolved. One |
| 72 | way to solve the problem is not to let the data in the data source be changed in |
| 73 | the first place, which can be done by setting locks on a row, a table, or the |
| 74 | whole data source. Setting locks is a way to avoid conflicts, but it can be |
| 75 | very expensive. Another approach, which is at the other end of the spectrum, |
| 76 | is simply to assume that no conflicts will occur and thus do nothing to avoid |
| 77 | conflicts. |
| 78 | Different <code>SyncProvider</code> implementations may handle synchronization in |
| 79 | any of these ways, varying from doing no checking for |
| 80 | conflicts, to doing various levels of checking, to guaranteeing that there are no |
| 81 | conflicts. |
| 82 | <P> |
| 83 | The <code>SyncProvider</code> class offers methods to help a <code>RowSet</code> |
| 84 | object discover and manage how a provider handles synchronization. |
| 85 | The method <code>getProviderGrade</code> returns the |
| 86 | grade of synchronization a provider offers. An application can |
| 87 | direct the provider to use a particular level of locking by calling |
| 88 | the method <code>setDataSourceLock</code> and specifying the level of locking desired. |
| 89 | If a <code>RowSet</code> object's data came from an SQL <code>VIEW</code>, an |
| 90 | application may call the method <code>supportsUpdatableView</code> to |
| 91 | find out whether the <code>VIEW</code> can be updated. |
| 92 | <P> |
| 93 | Synchronization is done completely behind the scenes, so it is third party vendors of |
| 94 | synchronization provider implementations who have to take care of this complex task. |
| 95 | Application programmers can decide which provider to use and the level of locking to |
| 96 | be done, but they are free from having to worry about the implementation details. |
| 97 | <P> |
| 98 | The JDBC <code>RowSet</code> Implementations reference implementation provides two |
| 99 | implementations of the <code>SyncProvider</code> class: |
| 100 | |
| 101 | <UL> |
| 102 | <LI> |
| 103 | <b><tt>RIOptimisticProvider </tt></b>- provides the <tt>javax.sql.RowSetReader</tt> |
| 104 | and <tt>javax.sql.RowSetWriter</tt> interface implementations and provides |
| 105 | an optimistic concurrency model for synchronization. This model assumes that there |
| 106 | will be few conflicts and therefore uses a relatively low grade of synchronization. |
| 107 | If no other provider is available, this is the default provider that the |
| 108 | <code>SyncFactory</code> will supply to a <code>RowSet</code> object. |
| 109 | <br> |
| 110 | <LI> |
| 111 | <b><tt>RIXMLProvider </tt></b>- provides the <tt>XmlReader</tt> (an extension |
| 112 | of the <tt>javax.sql.RowSetReader</tt> interface) and the <tt>XmlWriter</tt> |
| 113 | (an extension of the <tt>javax.sql.RowSetWriter</tt> interface) to enable |
| 114 | <tt>WebRowSet</tt> objects to write their state to a |
| 115 | well formed XML document according to the <tt>WebRowSet</tt> XML schema |
| 116 | definition.<br> |
| 117 | </UL> |
| 118 | |
| 119 | <h3>2.0 Basics in RowSet Population & Synchronization</h3> |
| 120 | A rowset's first task is to populate itself with rows of column values. |
| 121 | Generally, these rows will come from a relational database, so a rowset |
| 122 | has properties that supply what is necessary for making a connection to |
| 123 | a database and executing a query. A rowset that does not need to establish |
| 124 | a connection and execute a command, such as one that gets its data from |
| 125 | a tabular file instead of a relational database, does not need to have these |
| 126 | properties set. The vast majority of RowSets, however, do need to set these |
| 127 | properties. The general rule is that a RowSet is required to set only the |
| 128 | properties that it uses.<br> |
| 129 | <br> |
| 130 | The <tt>command</tt> property contains the query that determines what |
| 131 | data a <code>RowSet</code> will contain. Rowsets have methods for setting a query's |
| 132 | parameter(s), which means that a query can be executed multiple times with |
| 133 | different parameters to produce different result sets. Or the query can be |
| 134 | changed to something completely new to get a new result set. |
| 135 | <p>Once a rowset contains the rows from a <tt>ResultSet</tt> object or some |
| 136 | other data source, its column values can be updated, and its rows can be |
| 137 | inserted or deleted. Any method that causes a change in the rowset's values |
| 138 | or cursor position also notifies any object that has been registered as |
| 139 | a listener with the rowset. So, for example, a table that displays the rowset's |
| 140 | data in an applet can can be notified of changes and make updates as they |
| 141 | occur.<br> |
| 142 | <br> |
| 143 | The changes made to a rowset can be propagated back to the original data |
| 144 | source to keep the rowset and its data source synchronized. Although this |
| 145 | involves many operations behind the scenes, it is completely transparent |
| 146 | to the application programmer and remains the concern of the RowSet provider |
| 147 | developer. All an application has to do is invoke the method <tt>acceptChanges</tt>, |
| 148 | and the data source backing the rowset will be updated to match the current |
| 149 | values in the rowset. </p> |
| 150 | |
| 151 | <p>A disconnected rowset, such as a <tt>CachedRowSet</tt> or <tt>WebRowSet</tt> |
| 152 | object, establishes a connection to populate itself with data from a database |
| 153 | and then closes the connection. The <code>RowSet</code> object will remain |
| 154 | disconnected until it wants to propagate changes back to its database table, |
| 155 | which is optional. To write its changes back to the database (synchronize with |
| 156 | the database), the rowset establishes a connection, write the changes, and then |
| 157 | once again disconnects itself.<br> |
| 158 | </p> |
| 159 | |
| 160 | <h3> 3.0 Other Possible Implementations</h3> |
| 161 | There are many other possible implementations of the <tt>SyncProvider</tt> abstract |
| 162 | class. One possibility is to employ a more robust synchronization model, which |
| 163 | would give a <code>RowSet</code> object increased trust in the provider's |
| 164 | ability to get any updates back to the original data source. Another possibility |
| 165 | is a more formal synchronization mechanism such as SyncML |
| 166 | (<a href="http://www.syncml.org/">http://www.syncml.org/</a>) <br> |
| 167 | <br> |
| 168 | <br> |
| 169 | </body> |
| 170 | </html> |