001 /*
002 * Copyright 2003-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.sql.rowset.spi;
027
028 import javax.sql.*;
029
030 /**
031 * The synchronization mechanism that provides reader/writer capabilities for
032 * disconnected <code>RowSet</code> objects.
033 * A <code>SyncProvider</code> implementation is a class that extends the
034 * <code>SyncProvider</code> abstract class.
035 * <P>
036 * A <code>SyncProvider</code> implementation is
037 * identified by a unique ID, which is its fully qualified class name.
038 * This name must be registered with the
039 * <code>SyncFactory</code> SPI, thus making the implementation available to
040 * all <code>RowSet</code> implementations.
041 * The factory mechanism in the reference implementation uses this name to instantiate
042 * the implementation, which can then provide a <code>RowSet</code> object with its
043 * reader (a <code>javax.sql.RowSetReader</code> object) and its writer (a
044 * <code>javax.sql.RowSetWriter</code> object).
045 * <P>
046 * The Jdbc <code>RowSet</code> Implementations specification provides two
047 * reference implementations of the <code>SyncProvider</code> abstract class:
048 * <code>RIOptimisticProvider</code> and <code>RIXMLProvider</code>.
049 * The <code>RIOptimisticProvider</code> can set any <code>RowSet</code>
050 * implementation with a <code>RowSetReader</code> object and a
051 * <code>RowSetWriter</code> object. However, only the <code>RIXMLProvider</code>
052 * implementation can set an <code>XmlReader</code> object and an
053 * <code>XmlWriter</code> object. A <code>WebRowSet</code> object uses the
054 * <code>XmlReader</code> object to read data in XML format to populate itself with that
055 * data. It uses the <code>XmlWriter</code> object to write itself to a stream or
056 * <code>java.io.Writer</code> object in XML format.
057 * <P>
058 * <h3>1.0 Naming Convention for Implementations</h3>
059 * As a guide to naming <code>SyncProvider</code>
060 * implementations, the following should be noted:
061 * <UL>
062 * <li>The name for a <code>SyncProvider</code> implementation
063 * is its fully qualified class name.
064 * <li>It is recommended that vendors supply a
065 * <code>SyncProvider</code> implementation in a package named <code>providers</code>.
066 * </UL>
067 * <p>
068 * For instance, if a vendor named Fred, Inc. offered a
069 * <code>SyncProvider</code> implementation, you could have the following:
070 * <PRE>
071 * Vendor name: Fred, Inc.
072 * Domain name of vendor: com.fred
073 * Package name: com.fred.providers
074 * SyncProvider implementation class name: HighAvailabilityProvider
075 *
076 * Fully qualified class name of SyncProvider implementation:
077 * com.fred.providers.HighAvailabilityProvider
078 * </PRE>
079 * <P>
080 * The following line of code uses the fully qualified name to register
081 * this implementation with the <code>SyncFactory</code> static instance.
082 * <PRE>
083 * SyncFactory.registerProvider(
084 * "com.fred.providers.HighAvailabilityProvider");
085 * </PRE>
086 * <P>
087 * The default <code>SyncProvider</code> object provided with the reference
088 * implementation uses the following name:
089 * <pre>
090 * com.sun.rowset.providers.RIOptimisticProvider
091 * </pre>
092 * <p>
093 * A vendor can register a <code>SyncProvider</code> implementation class name
094 * with Sun Microsystems, Inc. by sending email to jdbc@sun.com.
095 * Sun will maintain a database listing the
096 * available <code>SyncProvider</code> implementations for use with compliant
097 * <code>RowSet</code> implementations. This database will be similar to the
098 * one already maintained to list available JDBC drivers.
099 * <P>
100 * Vendors should refer to the reference implementation synchronization
101 * providers for additional guidance on how to implement a new
102 * <code>SyncProvider</code> implementation.
103 *
104 * <h3>2.0 How a <code>RowSet</code> Object Gets Its Provider</h3>
105 *
106 * A disconnected <code>Rowset</code> object may get access to a
107 * <code>SyncProvider</code> object in one of the following two ways:
108 * <UL>
109 * <LI>Using a constructor<BR>
110 * <PRE>
111 * CachedRowSet crs = new CachedRowSet(
112 * "com.fred.providers.HighAvailabilitySyncProvider");
113 * </PRE>
114 * <LI>Using the <code>setSyncProvider</code> method
115 * <PRE>
116 * CachedRowSet crs = new CachedRowSet();
117 * crs.setSyncProvider("com.fred.providers.HighAvailabilitySyncProvider");
118 * </PRE>
119
120 * </UL>
121 * <p>
122 * By default, the reference implementations of the <code>RowSet</code> synchronization
123 * providers are always available to the Java platform.
124 * If no other pluggable synchronization providers have been correctly
125 * registered, the <code>SyncFactory</code> will automatically generate
126 * an instance of the default <code>SyncProvider</code> reference implementation.
127 * Thus, in the preceding code fragment, if no implementation named
128 * <code>com.fred.providers.HighAvailabilitySyncProvider</code> has been
129 * registered with the <code>SyncFactory</code> instance, <i>crs</i> will be
130 * assigned the default provider in the reference implementation, which is
131 * <code>com.sun.rowset.providers.RIOptimisticProvider</code>.
132 * <p>
133 * <h3>3.0 Violations and Synchronization Issues</h3>
134 * If an update between a disconnected <code>RowSet</code> object
135 * and a data source violates
136 * the original query or the underlying data source constraints, this will
137 * result in undefined behavior for all disconnected <code>RowSet</code> implementations
138 * and their designated <code>SyncProvider</code> implementations.
139 * Not defining the behavior when such violations occur offers greater flexibility
140 * for a <code>SyncProvider</code>
141 * implementation to determine its own best course of action.
142 * <p>
143 * A <code>SyncProvider</code> implementation
144 * may choose to implement a specific handler to
145 * handle a subset of query violations.
146 * However if an original query violation or a more general data source constraint
147 * violation is not handled by the <code>SyncProvider</code> implementation,
148 * all <code>SyncProvider</code>
149 * objects must throw a <code>SyncProviderException</code>.
150 * <p>
151 * <h3>4.0 Updatable SQL VIEWs</h3>
152 * It is possible for any disconnected or connected <code>RowSet</code> object to be populated
153 * from an SQL query that is formulated originally from an SQL <code>VIEW</code>.
154 * While in many cases it is possible for an update to be performed to an
155 * underlying view, such an update requires additional metadata, which may vary.
156 * The <code>SyncProvider</code> class provides two constants to indicate whether
157 * an implementation supports updating an SQL <code>VIEW</code>.
158 * <ul>
159 * <li><code><b>NONUPDATABLE_VIEW_SYNC</b></code> - Indicates that a <code>SyncProvider</code>
160 * implementation does not support synchronization with an SQL <code>VIEW</code> as the
161 * underlying source of data for the <code>RowSet</code> object.
162 * <li><code><b>UPDATABLE_VIEW_SYNC</b></code> - Indicates that a
163 * <code>SyncProvider</code> implementation
164 * supports synchronization with an SQL <code>VIEW</code> as the underlying source
165 * of data.
166 * </ul>
167 * <P>
168 * The default is for a <code>RowSet</code> object not to be updatable if it was
169 * populated with data from an SQL <code>VIEW</code>.
170 * <P>
171 * <h3>5.0 <code>SyncProvider</code> Constants</h3>
172 * The <code>SyncProvider</code> class provides three sets of constants that
173 * are used as return values or parameters for <code>SyncProvider</code> methods.
174 * <code>SyncProvider</code> objects may be implemented to perform synchronization
175 * between a <code>RowSet</code> object and its underlying data source with varying
176 * degrees of of care. The first group of constants indicate how synchronization
177 * is handled. For example, <code>GRADE_NONE</code> indicates that a
178 * <code>SyncProvider</code> object will not take any care to see what data is
179 * valid and will simply write the <code>RowSet</code> data to the data source.
180 * <code>GRADE_MODIFIED_AT_COMMIT</code> indicates that the provider will check
181 * only modified data for validity. Other grades check all data for validity
182 * or set locks when data is modified or loaded.
183 * <OL>
184 * <LI>Constants to indicate the synchronization grade of a
185 * <code>SyncProvider</code> object
186 * <UL>
187 * <LI>SyncProvider.GRADE_NONE
188 * <LI>SyncProvider.GRADE_MODIFIED_AT_COMMIT
189 * <LI>SyncProvider.GRADE_CHECK_ALL_AT_COMMIT
190 * <LI>SyncProvider.GRADE_LOCK_WHEN_MODIFIED
191 * <LI>SyncProvider.GRADE_LOCK_WHEN_LOADED
192 * </UL>
193 * <LI>Constants to indicate what locks are set on the data source
194 * <UL>
195 * <LI>SyncProvider.DATASOURCE_NO_LOCK
196 * <LI>SyncProvider.DATASOURCE_ROW_LOCK
197 * <LI>SyncProvider.DATASOURCE_TABLE_LOCK
198 * <LI>SyncProvider.DATASOURCE_DB_LOCK
199 * </UL>
200 * <LI>Constants to indicate whether a <code>SyncProvider</code> object can
201 * perform updates to an SQL <code>VIEW</code> <BR>
202 * These constants are explained in the preceding section (4.0).
203 * <UL>
204 * <LI>SyncProvider.UPDATABLE_VIEW_SYNC
205 * <LI>SyncProvider.NONUPDATABLE_VIEW_SYNC
206 * </UL>
207 * </OL>
208 *
209 * @author Jonathan Bruce
210 * @see javax.sql.rowset.spi.SyncFactory
211 * @see javax.sql.rowset.spi.SyncFactoryException
212 */
213 public abstract class SyncProvider {
214
215 /**
216 * Creates a default <code>SyncProvider</code> object.
217 */
218 public SyncProvider() {
219 }
220
221 /**
222 * Returns the unique identifier for this <code>SyncProvider</code> object.
223 *
224 * @return a <code>String</code> object with the fully qualified class name of
225 * this <code>SyncProvider</code> object
226 */
227 public abstract String getProviderID();
228
229 /**
230 * Returns a <code>javax.sql.RowSetReader</code> object, which can be used to
231 * populate a <code>RowSet</code> object with data.
232 *
233 * @return a <code>javax.sql.RowSetReader</code> object
234 */
235 public abstract RowSetReader getRowSetReader();
236
237 /**
238 * Returns a <code>javax.sql.RowSetWriter</code> object, which can be
239 * used to write a <code>RowSet</code> object's data back to the
240 * underlying data source.
241 *
242 * @return a <code>javax.sql.RowSetWriter</code> object
243 */
244 public abstract RowSetWriter getRowSetWriter();
245
246 /**
247 * Returns a constant indicating the
248 * grade of synchronization a <code>RowSet</code> object can expect from
249 * this <code>SyncProvider</code> object.
250 *
251 * @return an int that is one of the following constants:
252 * SyncProvider.GRADE_NONE,
253 * SyncProvider.GRADE_CHECK_MODIFIED_AT_COMMIT,
254 * SyncProvider.GRADE_CHECK_ALL_AT_COMMIT,
255 * SyncProvider.GRADE_LOCK_WHEN_MODIFIED,
256 * SyncProvider.GRADE_LOCK_WHEN_LOADED
257 */
258 public abstract int getProviderGrade();
259
260 /**
261 * Sets a lock on the underlying data source at the level indicated by
262 * <i>datasource_lock</i>. This should cause the
263 * <code>SyncProvider</code> to adjust its behavior by increasing or
264 * decreasing the level of optimism it provides for a successful
265 * synchronization.
266 *
267 * @param datasource_lock one of the following constants indicating the severity
268 * level of data source lock required:
269 * <pre>
270 * SyncProvider.DATASOURCE_NO_LOCK,
271 * SyncProvider.DATASOURCE_ROW_LOCK,
272 * SyncProvider.DATASOURCE_TABLE_LOCK,
273 * SyncProvider.DATASOURCE_DB_LOCK,
274 * </pre>
275 * @throws SyncProviderException if an unsupported data source locking level
276 * is set.
277 * @see #getDataSourceLock
278 */
279 public abstract void setDataSourceLock(int datasource_lock)
280 throws SyncProviderException;
281
282 /**
283 * Returns the current data source lock severity level active in this
284 * <code>SyncProvider</code> implementation.
285 *
286 * @return a constant indicating the current level of data source lock
287 * active in this <code>SyncProvider</code> object;
288 * one of the following:
289 * <pre>
290 * SyncProvider.DATASOURCE_NO_LOCK,
291 * SyncProvider.DATASOURCE_ROW_LOCK,
292 * SyncProvider.DATASOURCE_TABLE_LOCK,
293 * SyncProvider.DATASOURCE_DB_LOCK
294 * </pre>
295 * @throws SyncProviderExceptiom if an error occurs determining the data
296 * source locking level.
297 * @see #setDataSourceLock
298
299 */
300 public abstract int getDataSourceLock()
301 throws SyncProviderException;
302
303 /**
304 * Returns whether this <code>SyncProvider</code> implementation
305 * can perform synchronization between a <code>RowSet</code> object
306 * and the SQL <code>VIEW</code> in the data source from which
307 * the <code>RowSet</code> object got its data.
308 *
309 * @return an <code>int</code> saying whether this <code>SyncProvider</code>
310 * object supports updating an SQL <code>VIEW</code>; one of the
311 * following:
312 * SyncProvider.UPDATABLE_VIEW_SYNC,
313 * SyncProvider.NONUPDATABLE_VIEW_SYNC
314 */
315 public abstract int supportsUpdatableView();
316
317 /**
318 * Returns the release version of this <code>SyncProvider</code> instance.
319 *
320 * @return a <code>String</code> detailing the release version of the
321 * <code>SyncProvider</code> implementation
322 */
323 public abstract String getVersion();
324
325 /**
326 * Returns the vendor name of this <code>SyncProvider</code> instance
327 *
328 * @return a <code>String</code> detailing the vendor name of this
329 * <code>SyncProvider</code> implementation
330 */
331 public abstract String getVendor();
332
333 /*
334 * Standard description of synchronization grades that a SyncProvider
335 * could provide.
336 */
337
338 /**
339 * Indicates that no synchronization with the originating data source is
340 * provided. A <code>SyncProvider</code>
341 * implementation returning this grade will simply attempt to write
342 * updates in the <code>RowSet</code> object to the underlying data
343 * source without checking the validity of any data.
344 *
345 */
346 public static int GRADE_NONE = 1;
347
348 /**
349 * Indicates a low level optimistic synchronization grade with
350 * respect to the originating data source.
351 *
352 * A <code>SyncProvider</code> implementation
353 * returning this grade will check only rows that have changed.
354 *
355 */
356 public static int GRADE_CHECK_MODIFIED_AT_COMMIT = 2;
357
358 /**
359 * Indicates a high level optimistic synchronization grade with
360 * respect to the originating data source.
361 *
362 * A <code>SyncProvider</code> implementation
363 * returning this grade will check all rows, including rows that have not
364 * changed.
365 */
366 public static int GRADE_CHECK_ALL_AT_COMMIT = 3;
367
368 /**
369 * Indicates a pessimistic synchronization grade with
370 * respect to the originating data source.
371 *
372 * A <code>SyncProvider</code>
373 * implementation returning this grade will lock the row in the originating
374 * data source.
375 */
376 public static int GRADE_LOCK_WHEN_MODIFIED = 4;
377
378 /**
379 * Indicates the most pessimistic synchronization grade with
380 * respect to the originating
381 * data source. A <code>SyncProvider</code>
382 * implementation returning this grade will lock the entire view and/or
383 * table affected by the original statement used to populate a
384 * <code>RowSet</code> object.
385 */
386 public static int GRADE_LOCK_WHEN_LOADED = 5;
387
388 /**
389 * Indicates that no locks remain on the originating data source. This is the default
390 * lock setting for all <code>SyncProvider</code> implementations unless
391 * otherwise directed by a <code>RowSet</code> object.
392 */
393 public static int DATASOURCE_NO_LOCK = 1;
394
395 /**
396 * Indicates that a lock is placed on the rows that are touched by the original
397 * SQL statement used to populate the <code>RowSet</code> object
398 * that is using this <code>SyncProvider</code> object.
399 */
400 public static int DATASOURCE_ROW_LOCK = 2;
401
402 /**
403 * Indicates that a lock is placed on all tables that are touched by the original
404 * SQL statement used to populate the <code>RowSet</code> object
405 * that is using this <code>SyncProvider</code> object.
406 */
407 public static int DATASOURCE_TABLE_LOCK = 3;
408
409 /**
410 * Indicates that a lock is placed on the entire data source that is the source of
411 * data for the <code>RowSet</code> object
412 * that is using this <code>SyncProvider</code> object.
413 */
414 public static int DATASOURCE_DB_LOCK = 4;
415
416 /**
417 * Indicates that a <code>SyncProvider</code> implementation
418 * supports synchronization between a <code>RowSet</code> object and
419 * the SQL <code>VIEW</code> used to populate it.
420 */
421 public static int UPDATABLE_VIEW_SYNC = 5;
422
423 /**
424 * Indicates that a <code>SyncProvider</code> implementation
425 * does <B>not</B> support synchronization between a <code>RowSet</code>
426 * object and the SQL <code>VIEW</code> used to populate it.
427 */
428 public static int NONUPDATABLE_VIEW_SYNC = 6;
429 }
|