1. /*
  2. * @(#)SyncProvider.java 1.9 04/03/11
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.sql.rowset.spi;
  8. import javax.sql.*;
  9. /**
  10. * The synchronization mechanism that provides reader/writer capabilities for
  11. * disconnected <code>RowSet</code> objects.
  12. * A <code>SyncProvider</code> implementation is a class that extends the
  13. * <code>SyncProvider</code> abstract class.
  14. * <P>
  15. * A <code>SyncProvider</code> implementation is
  16. * identified by a unique ID, which is its fully qualified class name.
  17. * This name must be registered with the
  18. * <code>SyncFactory</code> SPI, thus making the implementation available to
  19. * all <code>RowSet</code> implementations.
  20. * The factory mechanism in the reference implementation uses this name to instantiate
  21. * the implementation, which can then provide a <code>RowSet</code> object with its
  22. * reader (a <code>javax.sql.RowSetReader</code> object) and its writer (a
  23. * <code>javax.sql.RowSetWriter</code> object).
  24. * <P>
  25. * The Jdbc <code>RowSet</code> Implementations specification provides two
  26. * reference implementations of the <code>SyncProvider</code> abstract class:
  27. * <code>RIOptimisticProvider</code> and <code>RIXMLProvider</code>.
  28. * The <code>RIOptimisticProvider</code> can set any <code>RowSet</code>
  29. * implementation with a <code>RowSetReader</code> object and a
  30. * <code>RowSetWriter</code> object. However, only the <code>RIXMLProvider</code>
  31. * implementation can set an <code>XmlReader</code> object and an
  32. * <code>XmlWriter</code> object. A <code>WebRowSet</code> object uses the
  33. * <code>XmlReader</code> object to read data in XML format to populate itself with that
  34. * data. It uses the <code>XmlWriter</code> object to write itself to a stream or
  35. * <code>java.io.Writer</code> object in XML format.
  36. * <P>
  37. * <h3>1.0 Naming Convention for Implementations</h3>
  38. * As a guide to naming <code>SyncProvider</code>
  39. * implementations, the following should be noted:
  40. * <UL>
  41. * <li>The name for a <code>SyncProvider</code> implementation
  42. * is its fully qualified class name.
  43. * <li>It is recommended that vendors supply a
  44. * <code>SyncProvider</code> implementation in a package named <code>providers</code>.
  45. * </UL>
  46. * <p>
  47. * For instance, if a vendor named Fred, Inc. offered a
  48. * <code>SyncProvider</code> implementation, you could have the following:
  49. * <PRE>
  50. * Vendor name: Fred, Inc.
  51. * Domain name of vendor: com.fred
  52. * Package name: com.fred.providers
  53. * SyncProvider implementation class name: HighAvailabilityProvider
  54. *
  55. * Fully qualified class name of SyncProvider implementation:
  56. * com.fred.providers.HighAvailabilityProvider
  57. * </PRE>
  58. * <P>
  59. * The following line of code uses the fully qualified name to register
  60. * this implementation with the <code>SyncFactory</code> static instance.
  61. * <PRE>
  62. * SyncFactory.registerProvider(
  63. * "com.fred.providers.HighAvailabilityProvider");
  64. * </PRE>
  65. * <P>
  66. * The default <code>SyncProvider</code> object provided with the reference
  67. * implementation uses the following name:
  68. * <pre>
  69. * com.sun.rowset.providers.RIOptimisticProvider
  70. * </pre>
  71. * <p>
  72. * A vendor can register a <code>SyncProvider</code> implementation class name
  73. * with Sun Microsystems, Inc. by sending email to jdbc@sun.com.
  74. * Sun will maintain a database listing the
  75. * available <code>SyncProvider</code> implementations for use with compliant
  76. * <code>RowSet</code> implementations. This database will be similar to the
  77. * one already maintained to list available JDBC drivers.
  78. * <P>
  79. * Vendors should refer to the reference implementation synchronization
  80. * providers for additional guidance on how to implement a new
  81. * <code>SyncProvider</code> implementation.
  82. *
  83. * <h3>2.0 How a <code>RowSet</code> Object Gets Its Provider</h3>
  84. *
  85. * A disconnected <code>Rowset</code> object may get access to a
  86. * <code>SyncProvider</code> object in one of the following two ways:
  87. * <UL>
  88. * <LI>Using a constructor<BR>
  89. * <PRE>
  90. * CachedRowSet crs = new CachedRowSet(
  91. * "com.fred.providers.HighAvailabilitySyncProvider");
  92. * </PRE>
  93. * <LI>Using the <code>setSyncProvider</code> method
  94. * <PRE>
  95. * CachedRowSet crs = new CachedRowSet();
  96. * crs.setSyncProvider("com.fred.providers.HighAvailabilitySyncProvider");
  97. * </PRE>
  98. * </UL>
  99. * <p>
  100. * By default, the reference implementations of the <code>RowSet</code> synchronization
  101. * providers are always available to the Java platform.
  102. * If no other pluggable synchronization providers have been correctly
  103. * registered, the <code>SyncFactory</code> will automatically generate
  104. * an instance of the default <code>SyncProvider</code> reference implementation.
  105. * Thus, in the preceding code fragment, if no implementation named
  106. * <code>com.fred.providers.HighAvailabilitySyncProvider</code> has been
  107. * registered with the <code>SyncFactory</code> instance, <i>crs</i> will be
  108. * assigned the default provider in the reference implementation, which is
  109. * <code>com.sun.rowset.providers.RIOptimisticProvider</code>.
  110. * <p>
  111. * <h3>3.0 Violations and Synchronization Issues</h3>
  112. * If an update between a disconnected <code>RowSet</code> object
  113. * and a data source violates
  114. * the original query or the underlying data source constraints, this will
  115. * result in undefined behavior for all disconnected <code>RowSet</code> implementations
  116. * and their designated <code>SyncProvider</code> implementations.
  117. * Not defining the behavior when such violations occur offers greater flexibility
  118. * for a <code>SyncProvider</code>
  119. * implementation to determine its own best course of action.
  120. * <p>
  121. * A <code>SyncProvider</code> implementation
  122. * may choose to implement a specific handler to
  123. * handle a subset of query violations.
  124. * However if an original query violation or a more general data source constraint
  125. * violation is not handled by the <code>SyncProvider</code> implementation,
  126. * all <code>SyncProvider</code>
  127. * objects must throw a <code>SyncProviderException</code>.
  128. * <p>
  129. * <h3>4.0 Updatable SQL VIEWs</h3>
  130. * It is possible for any disconnected or connected <code>RowSet</code> object to be populated
  131. * from an SQL query that is formulated originally from an SQL <code>VIEW</code>.
  132. * While in many cases it is possible for an update to be performed to an
  133. * underlying view, such an update requires additional metadata, which may vary.
  134. * The <code>SyncProvider</code> class provides two constants to indicate whether
  135. * an implementation supports updating an SQL <code>VIEW</code>.
  136. * <ul>
  137. * <li><code><b>NONUPDATABLE_VIEW_SYNC</b></code> - Indicates that a <code>SyncProvider</code>
  138. * implementation does not support synchronization with an SQL <code>VIEW</code> as the
  139. * underlying source of data for the <code>RowSet</code> object.
  140. * <li><code><b>UPDATABLE_VIEW_SYNC</b></code> - Indicates that a
  141. * <code>SyncProvider</code> implementation
  142. * supports synchronization with an SQL <code>VIEW</code> as the underlying source
  143. * of data.
  144. * </ul>
  145. * <P>
  146. * The default is for a <code>RowSet</code> object not to be updatable if it was
  147. * populated with data from an SQL <code>VIEW</code>.
  148. * <P>
  149. * <h3>5.0 <code>SyncProvider</code> Constants</h3>
  150. * The <code>SyncProvider</code> class provides three sets of constants that
  151. * are used as return values or parameters for <code>SyncProvider</code> methods.
  152. * <code>SyncProvider</code> objects may be implemented to perform synchronization
  153. * between a <code>RowSet</code> object and its underlying data source with varying
  154. * degrees of of care. The first group of constants indicate how synchronization
  155. * is handled. For example, <code>GRADE_NONE</code> indicates that a
  156. * <code>SyncProvider</code> object will not take any care to see what data is
  157. * valid and will simply write the <code>RowSet</code> data to the data source.
  158. * <code>GRADE_MODIFIED_AT_COMMIT</code> indicates that the provider will check
  159. * only modified data for validity. Other grades check all data for validity
  160. * or set locks when data is modified or loaded.
  161. * <OL>
  162. * <LI>Constants to indicate the synchronization grade of a
  163. * <code>SyncProvider</code> object
  164. * <UL>
  165. * <LI>SyncProvider.GRADE_NONE
  166. * <LI>SyncProvider.GRADE_MODIFIED_AT_COMMIT
  167. * <LI>SyncProvider.GRADE_CHECK_ALL_AT_COMMIT
  168. * <LI>SyncProvider.GRADE_LOCK_WHEN_MODIFIED
  169. * <LI>SyncProvider.GRADE_LOCK_WHEN_LOADED
  170. * </UL>
  171. * <LI>Constants to indicate what locks are set on the data source
  172. * <UL>
  173. * <LI>SyncProvider.DATASOURCE_NO_LOCK
  174. * <LI>SyncProvider.DATASOURCE_ROW_LOCK
  175. * <LI>SyncProvider.DATASOURCE_TABLE_LOCK
  176. * <LI>SyncProvider.DATASOURCE_DB_LOCK
  177. * </UL>
  178. * <LI>Constants to indicate whether a <code>SyncProvider</code> object can
  179. * perform updates to an SQL <code>VIEW</code> <BR>
  180. * These constants are explained in the preceding section (4.0).
  181. * <UL>
  182. * <LI>SyncProvider.UPDATABLE_VIEW_SYNC
  183. * <LI>SyncProvider.NONUPDATABLE_VIEW_SYNC
  184. * </UL>
  185. * </OL>
  186. *
  187. * @author Jonathan Bruce
  188. * @see javax.sql.rowset.spi.SyncFactory
  189. * @see javax.sql.rowset.spi.SyncFactoryException
  190. */
  191. public abstract class SyncProvider {
  192. /**
  193. * Creates a default <code>SyncProvider</code> object.
  194. */
  195. public SyncProvider() {
  196. }
  197. /**
  198. * Returns the unique identifier for this <code>SyncProvider</code> object.
  199. *
  200. * @return a <code>String</code> object with the fully qualified class name of
  201. * this <code>SyncProvider</code> object
  202. */
  203. public abstract String getProviderID();
  204. /**
  205. * Returns a <code>javax.sql.RowSetReader</code> object, which can be used to
  206. * populate a <code>RowSet</code> object with data.
  207. *
  208. * @return a <code>javax.sql.RowSetReader</code> object
  209. */
  210. public abstract RowSetReader getRowSetReader();
  211. /**
  212. * Returns a <code>javax.sql.RowSetWriter</code> object, which can be
  213. * used to write a <code>RowSet</code> object's data back to the
  214. * underlying data source.
  215. *
  216. * @return a <code>javax.sql.RowSetWriter</code> object
  217. */
  218. public abstract RowSetWriter getRowSetWriter();
  219. /**
  220. * Returns a constant indicating the
  221. * grade of synchronization a <code>RowSet</code> object can expect from
  222. * this <code>SyncProvider</code> object.
  223. *
  224. * @return an int that is one of the following constants:
  225. * SyncProvider.GRADE_NONE,
  226. * SyncProvider.GRADE_CHECK_MODIFIED_AT_COMMIT,
  227. * SyncProvider.GRADE_CHECK_ALL_AT_COMMIT,
  228. * SyncProvider.GRADE_LOCK_WHEN_MODIFIED,
  229. * SyncProvider.GRADE_LOCK_WHEN_LOADED
  230. */
  231. public abstract int getProviderGrade();
  232. /**
  233. * Sets a lock on the underlying data source at the level indicated by
  234. * <i>datasource_lock</i>. This should cause the
  235. * <code>SyncProvider</code> to adjust its behavior by increasing or
  236. * decreasing the level of optimism it provides for a successful
  237. * synchronization.
  238. *
  239. * @param datasource_lock one of the following constants indicating the severity
  240. * level of data source lock required:
  241. * <pre>
  242. * SyncProvider.DATASOURCE_NO_LOCK,
  243. * SyncProvider.DATASOURCE_ROW_LOCK,
  244. * SyncProvider.DATASOURCE_TABLE_LOCK,
  245. * SyncProvider.DATASOURCE_DB_LOCK,
  246. * </pre>
  247. * @throws SyncProviderException if an unsupported data source locking level
  248. * is set.
  249. * @see #getDataSourceLock
  250. */
  251. public abstract void setDataSourceLock(int datasource_lock)
  252. throws SyncProviderException;
  253. /**
  254. * Returns the current data source lock severity level active in this
  255. * <code>SyncProvider</code> implementation.
  256. *
  257. * @return a constant indicating the current level of data source lock
  258. * active in this <code>SyncProvider</code> object;
  259. * one of the following:
  260. * <pre>
  261. * SyncProvider.DATASOURCE_NO_LOCK,
  262. * SyncProvider.DATASOURCE_ROW_LOCK,
  263. * SyncProvider.DATASOURCE_TABLE_LOCK,
  264. * SyncProvider.DATASOURCE_DB_LOCK
  265. * </pre>
  266. * @throws SyncProviderExceptiom if an error occurs determining the data
  267. * source locking level.
  268. * @see #setDataSourceLock
  269. */
  270. public abstract int getDataSourceLock()
  271. throws SyncProviderException;
  272. /**
  273. * Returns whether this <code>SyncProvider</code> implementation
  274. * can perform synchronization between a <code>RowSet</code> object
  275. * and the SQL <code>VIEW</code> in the data source from which
  276. * the <code>RowSet</code> object got its data.
  277. *
  278. * @return an <code>int</code> saying whether this <code>SyncProvider</code>
  279. * object supports updating an SQL <code>VIEW</code> one of the
  280. * following:
  281. * SyncProvider.UPDATABLE_VIEW_SYNC,
  282. * SyncProvider.NONUPDATABLE_VIEW_SYNC
  283. */
  284. public abstract int supportsUpdatableView();
  285. /**
  286. * Returns the release version of this <code>SyncProvider</code> instance.
  287. *
  288. * @return a <code>String</code> detailing the release version of the
  289. * <code>SyncProvider</code> implementation
  290. */
  291. public abstract String getVersion();
  292. /**
  293. * Returns the vendor name of this <code>SyncProvider</code> instance
  294. *
  295. * @return a <code>String</code> detailing the vendor name of this
  296. * <code>SyncProvider</code> implementation
  297. */
  298. public abstract String getVendor();
  299. /*
  300. * Standard description of synchronization grades that a SyncProvider
  301. * could provide.
  302. */
  303. /**
  304. * Indicates that no synchronization with the originating data source is
  305. * provided. A <code>SyncProvider</code>
  306. * implementation returning this grade will simply attempt to write
  307. * updates in the <code>RowSet</code> object to the underlying data
  308. * source without checking the validity of any data.
  309. *
  310. */
  311. public static int GRADE_NONE = 1;
  312. /**
  313. * Indicates a low level optimistic synchronization grade with
  314. * respect to the originating data source.
  315. *
  316. * A <code>SyncProvider</code> implementation
  317. * returning this grade will check only rows that have changed.
  318. *
  319. */
  320. public static int GRADE_CHECK_MODIFIED_AT_COMMIT = 2;
  321. /**
  322. * Indicates a high level optimistic synchronization grade with
  323. * respect to the originating data source.
  324. *
  325. * A <code>SyncProvider</code> implementation
  326. * returning this grade will check all rows, including rows that have not
  327. * changed.
  328. */
  329. public static int GRADE_CHECK_ALL_AT_COMMIT = 3;
  330. /**
  331. * Indicates a pessimistic synchronization grade with
  332. * respect to the originating data source.
  333. *
  334. * A <code>SyncProvider</code>
  335. * implementation returning this grade will lock the row in the originating
  336. * data source.
  337. */
  338. public static int GRADE_LOCK_WHEN_MODIFIED = 4;
  339. /**
  340. * Indicates the most pessimistic synchronization grade with
  341. * respect to the originating
  342. * data source. A <code>SyncProvider</code>
  343. * implementation returning this grade will lock the entire view and/or
  344. * table affected by the original statement used to populate a
  345. * <code>RowSet</code> object.
  346. */
  347. public static int GRADE_LOCK_WHEN_LOADED = 5;
  348. /**
  349. * Indicates that no locks remain on the originating data source. This is the default
  350. * lock setting for all <code>SyncProvider</code> implementations unless
  351. * otherwise directed by a <code>RowSet</code> object.
  352. */
  353. public static int DATASOURCE_NO_LOCK = 1;
  354. /**
  355. * Indicates that a lock is placed on the rows that are touched by the original
  356. * SQL statement used to populate the <code>RowSet</code> object
  357. * that is using this <code>SyncProvider</code> object.
  358. */
  359. public static int DATASOURCE_ROW_LOCK = 2;
  360. /**
  361. * Indicates that a lock is placed on all tables that are touched by the original
  362. * SQL statement used to populate the <code>RowSet</code> object
  363. * that is using this <code>SyncProvider</code> object.
  364. */
  365. public static int DATASOURCE_TABLE_LOCK = 3;
  366. /**
  367. * Indicates that a lock is placed on the entire data source that is the source of
  368. * data for the <code>RowSet</code> object
  369. * that is using this <code>SyncProvider</code> object.
  370. */
  371. public static int DATASOURCE_DB_LOCK = 4;
  372. /**
  373. * Indicates that a <code>SyncProvider</code> implementation
  374. * supports synchronization between a <code>RowSet</code> object and
  375. * the SQL <code>VIEW</code> used to populate it.
  376. */
  377. public static int UPDATABLE_VIEW_SYNC = 5;
  378. /**
  379. * Indicates that a <code>SyncProvider</code> implementation
  380. * does <B>not</B> support synchronization between a <code>RowSet</code>
  381. * object and the SQL <code>VIEW</code> used to populate it.
  382. */
  383. public static int NONUPDATABLE_VIEW_SYNC = 6;
  384. }