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