1. /*
  2. * @(#)WebRowSet.java 1.5 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;
  8. import java.sql.*;
  9. import javax.sql.*;
  10. import javax.naming.*;
  11. import java.io.*;
  12. import java.math.*;
  13. import org.xml.sax.*;
  14. /**
  15. * The standard interface that all implementations of a <code>WebRowSet</code>
  16. * must implement.
  17. * <P>
  18. * <h3>1.0 Overview</h3>
  19. * The <code>WebRowSetImpl</code> provides the standard
  20. * reference implementation, which may be extended if required.
  21. * <P>
  22. * The standard WebRowSet XML Schema definition is available at the following
  23. * URI:
  24. * <ul>
  25. * <pre>
  26. * <a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd">http://java.sun.com/xml/ns/jdbc/webrowset.xsd</a>
  27. * </pre>
  28. * </ul>
  29. * It describes the standard XML document format required when describing a
  30. * <code>RowSet</code> object in XML and must be used be all standard implementations
  31. * of the <code>WebRowSet</code> interface to ensure interoperability. In addition,
  32. * the <code>WebRowSet</code> schema uses specific SQL/XML Schema annotations,
  33. * thus ensuring greater cross
  34. * platform inter-operability. This is an effort currently under way at the ISO
  35. * organization. The SQL/XML definition is available at the following URI:
  36. * <ul>
  37. * <pre>
  38. * <a href="http://standards.iso.org/iso/9075/2002/12/sqlxml">http://standards.iso.org/iso/9075/2002/12/sqlxml</a>
  39. * </pre>
  40. * </ul>
  41. * The schema definition describes the internal data of a <code>RowSet</code> object
  42. * in three distinct areas:
  43. * <UL>
  44. * <li><b>properties</b></li>
  45. * These properties describe the standard synchronization provider properties in
  46. * addition to the more general <code>RowSet</code> properties.
  47. * <p>
  48. * <li><b>metadata</b></li>
  49. * This describes the metadata associated with the tabular structure governed by a
  50. * <code>WebRowSet</code> object. The metadata described is closely aligned with the
  51. * metadata accessible in the underlying <code>java.sql.ResultSet</code> interface.
  52. * <p>
  53. * <li><b>data</b></li>
  54. * This describes the original data (the state of data since the last population
  55. * or last synchronization of the <code>WebRowSet</code> object) and the current
  56. * data. By keeping track of the delta between the original data and the current data,
  57. * a <code>WebRowSet</code> maintains
  58. * the ability to synchronize changes in its data back to the originating data source.
  59. * </ul>
  60. * <P>
  61. * <h3>2.0 WebRowSet States</h3>
  62. * The following sections demonstrates how a <code>WebRowSet</code> implementation
  63. * should use the XML Schema to describe update, insert, and delete operations
  64. * and to describe the state of a <code>WebRowSet</code> object in XML.
  65. * <p>
  66. * <h4>2.1 State 1 - Outputting a <code>WebRowSet</code> Object to XML</h3>
  67. * In this example, a <code>WebRowSet</code> object is created and populated with a simple 2 column,
  68. * 5 row table from a data source. Having the 5 rows in a <code>WebRowSet</code> object
  69. * makes it possible to describe them in XML. The
  70. * metadata describing the various standard JavaBeans properties as defined
  71. * in the RowSet interface plus the standard properties defined in
  72. * the <code>CachedRowSet</code><sup><font size=-2>TM</font></sup> interface
  73. * provide key details that describe WebRowSet
  74. * properties. Outputting the WebRowSet object to XML using the standard
  75. * <code>writeXml</code> methods describes the internal properties as follows:
  76. * <PRE>
  77. * <<font color=red>properties</font>>
  78. * <<font color=red>command</font>>select co1, col2 from test_table<<font color=red>/command</font>>
  79. * <<font color=red>concurrency</font>>1<<font color=red>/concurrency</font>>
  80. * <<font color=red>datasource/</font>>
  81. * <<font color=red>escape-processing</font>>true<<font color=red>/escape-processing</font>>
  82. * <<font color=red>fetch-direction</font>>0<<font color=red>/fetch-direction</font>>
  83. * <<font color=red>fetch-size</font>>0<<font color=red>/fetch-size</font>>
  84. * <<font color=red>isolation-level</font>>1<<font color=red>/isolation-level</font>>
  85. * <<font color=red>key-columns/</font>>
  86. * <<font color=red>map/</font>>
  87. * <<font color=red>max-field-size</font>>0<<font color=red>/max-field-size</font>>
  88. * <<font color=red>max-rows</font>>0<<font color=red>/max-rows</font>>
  89. * <<font color=red>query-timeout</font>>0<<font color=red>/query-timeout</font>>
  90. * <<font color=red>read-only</font>>false<<font color=red>/read-only</font>>
  91. * <<font color=red>rowset-type</font>>TRANSACTION_READ_UNCOMMITED<<font color=red>/rowset-type</font>>
  92. * <<font color=red>show-deleted</font>>false<<font color=red>/show-deleted</font>>
  93. * <<font color=red>table-name/</font>>
  94. * <<font color=red>url</font>>jdbc:thin:oracle<<font color=red>/url</font>>
  95. * <<font color=red>sync-provider</font>>
  96. * <<font color=red>sync-provider-name</font>>.com.rowset.provider.RIOptimisticProvider<<font color=red>/sync-provider-name</font>>
  97. * <<font color=red>sync-provider-vendor</font>>Sun Microsystems<<font color=red>/sync-provider-vendor</font>>
  98. * <<font color=red>sync-provider-version</font>>1.0<<font color=red>/sync-provider-name</font>>
  99. * <<font color=red>sync-provider-grade</font>>LOW<<font color=red>/sync-provider-grade</font>>
  100. * <<font color=red>data-source-lock</font>>NONE<<font color=red>/data-source-lock</font>>
  101. * <<font color=red>/sync-provider</font>>
  102. * <<font color=red>/properties</font>>
  103. * </PRE>
  104. * The meta-data describing the make up of the WebRowSet is described
  105. * in XML as detailed below. Note both columns are described between the
  106. * <code>column-definition</code> tags.
  107. * <PRE>
  108. * <<font color=red>metadata</font>>
  109. * <<font color=red>column-count</font>>2<<font color=red>/column-count</font>>
  110. * <<font color=red>column-definition</font>>
  111. * <<font color=red>column-index</font>>1<<font color=red>/column-index</font>>
  112. * <<font color=red>auto-increment</font>>false<<font color=red>/auto-increment</font>>
  113. * <<font color=red>case-sensitive</font>>true<<font color=red>/case-sensitive</font>>
  114. * <<font color=red>currency</font>>false<<font color=red>/currency</font>>
  115. * <<font color=red>nullable</font>>1<<font color=red>/nullable</font>>
  116. * <<font color=red>signed</font>>false<<font color=red>/signed</font>>
  117. * <<font color=red>searchable</font>>true<<font color=red>/searchable</font>>
  118. * <<font color=red>column-display-size</font>>10<<font color=red>/column-display-size</font>>
  119. * <<font color=red>column-label</font>>COL1<<font color=red>/column-label</font>>
  120. * <<font color=red>column-name</font>>COL1<<font color=red>/column-name</font>>
  121. * <<font color=red>schema-name/</font>>
  122. * <<font color=red>column-precision</font>>10<<font color=red>/column-precision</font>>
  123. * <<font color=red>column-scale</font>>0<<font color=red>/column-scale</font>>
  124. * <<font color=red>table-name/</font>>
  125. * <<font color=red>catalog-name/</font>>
  126. * <<font color=red>column-type</font>>1<<font color=red>/column-type</font>>
  127. * <<font color=red>column-type-name</font>>CHAR<<font color=red>/column-type-name</font>>
  128. * <<font color=red>/column-definition</font>>
  129. * <<font color=red>column-definition</font>>
  130. * <<font color=red>column-index</font>>2<<font color=red>/column-index</font>>
  131. * <<font color=red>auto-increment</font>>false<<font color=red>/auto-increment</font>>
  132. * <<font color=red>case-sensitive</font>>false<<font color=red>/case-sensitive</font>>
  133. * <<font color=red>currency</font>>false<<font color=red>/currency</font>>
  134. * <<font color=red>nullable</font>>1<<font color=red>/nullable</font>>
  135. * <<font color=red>signed</font>>true<<font color=red>/signed</font>>
  136. * <<font color=red>searchable</font>>true<<font color=red>/searchable</font>>
  137. * <<font color=red>column-display-size</font>>39<<font color=red>/column-display-size</font>>
  138. * <<font color=red>column-label</font>>COL2<<font color=red>/column-label</font>>
  139. * <<font color=red>column-name</font>>COL2<<font color=red>/column-name</font>>
  140. * <<font color=red>schema-name/</font>>
  141. * <<font color=red>column-precision</font>>38<<font color=red>/column-precision</font>>
  142. * <<font color=red>column-scale</font>>0<<font color=red>/column-scale</font>>
  143. * <<font color=red>table-name/</font>>
  144. * <<font color=red>catalog-name/</font>>
  145. * <<font color=red>column-type</font>>3<<font color=red>/column-type</font>>
  146. * <<font color=red>column-type-name</font>>NUMBER<<font color=red>/column-type-name</font>>
  147. * <<font color=red>/column-definition</font>>
  148. * <<font color=red>/metadata</font>>
  149. * </PRE>
  150. * Having detailed how the properties and metadata are described, the following details
  151. * how the contents of a <code>WebRowSet</code> object is described in XML. Note, that
  152. * this describes a <code>WebRowSet</code> object that has not undergone any
  153. * modifications since its instantiation.
  154. * A <code>currentRow</code> tag is mapped to each row of the table structure that the
  155. * <code>WebRowSet</code> object provides. A <code>columnValue</code> tag may contain
  156. * either the <code>stringData</code> or <code>binaryData</code> tag, according to
  157. * the SQL type that
  158. * the XML value is mapping back to. The <code>binaryData</code> tag contains data in the
  159. * Base64 encoding and is typically used for <code>BLOB</code> and <code>CLOB</code> type data.
  160. * <PRE>
  161. * <<font color=red>data</font>>
  162. * <<font color=red>currentRow</font>>
  163. * <<font color=red>columnValue</font>>
  164. * firstrow
  165. * <<font color=red>/columnValue</font>>
  166. * <<font color=red>columnValue</font>>
  167. * 1
  168. * <<font color=red>/columnValue</font>>
  169. * <<font color=red>/currentRow</font>>
  170. * <<font color=red>currentRow</font>>
  171. * <<font color=red>columnValue</font>>
  172. * secondrow
  173. * <<font color=red>/columnValue</font>>
  174. * <<font color=red>columnValue</font>>
  175. * 2
  176. * <<font color=red>/columnValue</font>>
  177. * <<font color=red>/currentRow</font>>
  178. * <<font color=red>currentRow</font>>
  179. * <<font color=red>columnValue</font>>
  180. * thirdrow
  181. * <<font color=red>/columnValue</font>>
  182. * <<font color=red>columnValue</font>>
  183. * 3
  184. * <<font color=red>/columnValue</font>>
  185. * <<font color=red>/currentRow</font>>
  186. * <<font color=red>currentRow</font>>
  187. * <<font color=red>columnValue</font>>
  188. * fourthrow
  189. * <<font color=red>/columnValue</font>>
  190. * <<font color=red>columnValue</font>>
  191. * 4
  192. * <<font color=red>/columnValue</font>>
  193. * <<font color=red>/currentRow</font>>
  194. * <<font color=red>/data</font>>
  195. * </PRE>
  196. * <h4>2.2 State 2 - Deleting a Row</h4>
  197. * Deleting a row in a <code>WebRowSet</code> object involves simply moving to the row
  198. * to be deleted and then calling the method <code>deleteRow</code>, as in any other
  199. * <code>RowSet</code> object. The following
  200. * two lines of code, in which <i>wrs</i> is a <code>WebRowSet</code> object, delete
  201. * the third row.
  202. * <PRE>
  203. * wrs.absolute(3);
  204. * wrs.deleteRow();
  205. * </PRE>
  206. * The XML description shows the third row is marked as a <code>deleteRow</code>,
  207. * which eliminates the third row in the <code>WebRowSet</code> object.
  208. * <PRE>
  209. * <<font color=red>data</font>>
  210. * <<font color=red>currentRow</font>>
  211. * <<font color=red>columnValue</font>>
  212. * firstrow
  213. * <<font color=red>/columnValue</font>>
  214. * <<font color=red>columnValue</font>>
  215. * 1
  216. * <<font color=red>/columnValue</font>>
  217. * <<font color=red>/currentRow</font>>
  218. * <<font color=red>currentRow</font>>
  219. * <<font color=red>columnValue</font>>
  220. * secondrow
  221. * <<font color=red>/columnValue</font>>
  222. * <<font color=red>columnValue</font>>
  223. * 2
  224. * <<font color=red>/columnValue</font>>
  225. * <<font color=red>/currentRow</font>>
  226. * <<font color=red>deleteRow</font>>
  227. * <<font color=red>columnValue</font>>
  228. * thirdrow
  229. * <<font color=red>/columnValue</font>>
  230. * <<font color=red>columnValue</font>>
  231. * 3
  232. * <<font color=red>/columnValue</font>>
  233. * <<font color=red>/deleteRow</font>>
  234. * <<font color=red>currentRow</font>>
  235. * <<font color=red>columnValue</font>>
  236. * fourthrow
  237. * <<font color=red>/columnValue</font>>
  238. * <<font color=red>columnValue</font>>
  239. * 4
  240. * <<font color=red>/columnValue</font>>
  241. * <<font color=red>/currentRow</font>>
  242. * <<font color=red>/data</font>>
  243. * </PRE>
  244. * <h4>2.3 State 3 - Inserting a Row</h4>
  245. * A <codeWebRowSet</code> object can insert a new row by moving to the insert row,
  246. * calling the appropriate updater methods for each column in the row, and then
  247. * calling the method <code>insertRow</code>.
  248. * <PRE>
  249. * wrs.moveToInsertRow();
  250. * wrs.updateString(1, "fifththrow");
  251. * wrs.updateString(2, "5");
  252. * wrs.insertRow();
  253. * </PRE>
  254. * The following code fragment changes the second column value in the row just inserted.
  255. * Note that this code applies when new rows are inserted right after the current row,
  256. * which is why the method <code>next</code> moves the cursor to the correct row.
  257. * Calling the method <code>acceptChanges</code> writes the change to the data source.
  258. *
  259. * <PRE>
  260. * wrs.moveToCurrentRow();
  261. * wrs.next();
  262. * wrs.updateString(2, "V");
  263. * wrs.acceptChanges();
  264. * :
  265. * </PRE>
  266. * Describing this in XML demonstrates where the Java code inserts a new row and then
  267. * performs an update on the newly inserted row on an individual field.
  268. * <PRE>
  269. * <<font color=red>data</font>>
  270. * <<font color=red>currentRow</font>>
  271. * <<font color=red>columnValue</font>>
  272. * firstrow
  273. * <<font color=red>/columnValue</font>>
  274. * <<font color=red>columnValue</font>>
  275. * 1
  276. * <<font color=red>/columnValue</font>>
  277. * <<font color=red>/currentRow</font>>
  278. * <<font color=red>currentRow</font>>
  279. * <<font color=red>columnValue</font>>
  280. * secondrow
  281. * <<font color=red>/columnValue</font>>
  282. * <<font color=red>columnValue</font>>
  283. * 2
  284. * <<font color=red>/columnValue</font>>
  285. * <<font color=red>/currentRow</font>>
  286. * <<font color=red>currentRow</font>>
  287. * <<font color=red>columnValue</font>>
  288. * newthirdrow
  289. * <<font color=red>/columnValue</font>>
  290. * <<font color=red>columnValue</font>>
  291. * III
  292. * <<font color=red>/columnValue</font>>
  293. * <<font color=red>/currentRow</font>>
  294. * <<font color=red>insertRow</font>>
  295. * <<font color=red>columnValue</font>>
  296. * fifthrow
  297. * <<font color=red>/columnValue</font>>
  298. * <<font color=red>columnValue</font>>
  299. * 5
  300. * <<font color=red>/columnValue</font>>
  301. * <<font color=red>updateValue</font>>
  302. * V
  303. * <<font color=red>/updateValue</font>>
  304. * <<font color=red>/insertRow</font>>
  305. * <<font color=red>currentRow</font>>
  306. * <<font color=red>columnValue</font>>
  307. * fourthrow
  308. * <<font color=red>/columnValue</font>>
  309. * <<font color=red>columnValue</font>>
  310. * 4
  311. * <<font color=red>/columnValue</font>>
  312. * <<font color=red>/currentRow</font>>
  313. * <<font color=red>/date</font>>
  314. * </PRE>
  315. * <h4>2.4 State 4 - Modifying a Row</h4>
  316. * Modifying a row produces specific XML that records both the new value and the
  317. * value that was replaced. The value that was replaced becomes the original value,
  318. * and the new value becomes the current value. The following
  319. * code moves the cursor to a specific row, performs some modifications, and updates
  320. * the row when complete.
  321. * <PRE>
  322. * wrs.absolute(5);
  323. * wrs.updateString(1, "new4thRow");
  324. * wrs.updateString(2, "IV");
  325. * wrs.updateRow();
  326. * </PRE>
  327. * In XML, this is described by the <code>modifyRow</code> tag. Both the original and new
  328. * values are contained within the tag for original row tracking purposes.
  329. * <PRE>
  330. * <<font color=red>data</font>>
  331. * <<font color=red>currentRow</font>>
  332. * <<font color=red>columnValue</font>>
  333. * firstrow
  334. * <<font color=red>/columnValue</font>>
  335. * <<font color=red>columnValue</font>>
  336. * 1
  337. * <<font color=red>/columnValue</font>>
  338. * <<font color=red>/currentRow</font>>
  339. * <<font color=red>currentRow</font>>
  340. * <<font color=red>columnValue</font>>
  341. * secondrow
  342. * <<font color=red>/columnValue</font>>
  343. * <<font color=red>columnValue</font>>
  344. * 2
  345. * <<font color=red>/columnValue</font>>
  346. * <<font color=red>/currentRow</font>>
  347. * <<font color=red>currentRow</font>>
  348. * <<font color=red>columnValue</font>>
  349. * newthirdrow
  350. * <<font color=red>/columnValue</font>>
  351. * <<font color=red>columnValue</font>>
  352. * III
  353. * <<font color=red>/columnValue</font>>
  354. * <<font color=red>/currentRow</font>>
  355. * <<font color=red>currentRow</font>>
  356. * <<font color=red>columnValue</font>>
  357. * fifthrow
  358. * <<font color=red>/columnValue</font>>
  359. * <<font color=red>columnValue</font>>
  360. * 5
  361. * <<font color=red>/columnValue</font>>
  362. * <<font color=red>/currentRow</font>>
  363. * <<font color=red>modifyRow</font>>
  364. * <<font color=red>columnValue</font>>
  365. * fourthrow
  366. * <<font color=red>/columnValue</font>>
  367. * <<font color=red>updateValue</font>>
  368. * new4thRow
  369. * <<font color=red>/updateValue</font>>
  370. * <<font color=red>columnValue</font>>
  371. * 4
  372. * <<font color=red>/columnValue</font>>
  373. * <<font color=red>updateValue</font>>
  374. * IV
  375. * <<font color=red>/updateValue</font>>
  376. * <<font color=red>/modifyRow</font>>
  377. * <<font color=red>/data</font>>
  378. * </PRE>
  379. *
  380. * @see javax.sql.rowset.JdbcRowSet
  381. * @see javax.sql.rowset.CachedRowSet
  382. * @see javax.sql.rowset.FilteredRowSet
  383. * @see javax.sql.rowset.JoinRowSet
  384. */
  385. public interface WebRowSet extends CachedRowSet {
  386. /**
  387. * Reads a <code>WebRowSet</code> object in its XML format from the given
  388. * <code>Reader</code> object.
  389. *
  390. * @param reader the <code>java.io.Reader</code> stream from which this
  391. * <code>WebRowSet</code> object will be populated
  392. * @throws SQLException if a database access error occurs
  393. */
  394. public void readXml(java.io.Reader reader) throws SQLException;
  395. /**
  396. * Reads a stream based XML input to populate this <code>WebRowSet</code>
  397. * object.
  398. *
  399. * @param iStream the <code>java.io.InputStream</code> from which this
  400. * <code>WebRowSet</code> object will be populated
  401. * @throws SQLException if a data source access error occurs
  402. * @throws IOException if an IO exception occurs
  403. */
  404. public void readXml(java.io.InputStream iStream) throws SQLException, IOException;
  405. /**
  406. * Populates this <code>WebRowSet</code> object with
  407. * the contents of the given <code>ResultSet</code> object and writes its
  408. * data, properties, and metadata
  409. * to the given <code>Writer</code> object in XML format.
  410. * <p>
  411. * NOTE: The <code>WebRowSet</code> cursor may be moved to write out the
  412. * contents to the XML data source. If implemented in this way, the cursor <b>must</b>
  413. * be returned to its position just prior to the <code>writeXml()</code> call.
  414. *
  415. * @param rs the <code>ResultSet</code> object with which to populate this
  416. * <code>WebRowSet</code> object
  417. * @param writer the <code>java.io.Writer</code> object to write to.
  418. * @throws SQLException if an error occurs writing out the rowset
  419. * contents in XML format
  420. */
  421. public void writeXml(ResultSet rs, java.io.Writer writer) throws SQLException;
  422. /**
  423. * Populates this <code>WebRowSet</code> object with
  424. * the contents of the given <code>ResultSet</code> object and writes its
  425. * data, properties, and metadata
  426. * to the given <code>OutputStream</code> object in XML format.
  427. * <p>
  428. * NOTE: The <code>WebRowSet</code> cursor may be moved to write out the
  429. * contents to the XML data source. If implemented in this way, the cursor <b>must</b>
  430. * be returned to its position just prior to the <code>writeXml()</code> call.
  431. *
  432. * @param rs the <code>ResultSet</code> object with which to populate this
  433. * <code>WebRowSet</code> object
  434. * @param oStream the <code>java.io.OutputStream</code> to write to
  435. * @throws SQLException if a data source access error occurs
  436. * @throws IOException if a IO exception occurs
  437. */
  438. public void writeXml(ResultSet rs, java.io.OutputStream oStream) throws SQLException, IOException;
  439. /**
  440. * Writes the data, properties, and metadata for this <code>WebRowSet</code> object
  441. * to the given <code>Writer</code> object in XML format.
  442. *
  443. * @param writer the <code>java.io.Writer</code> stream to write to
  444. * @throws SQLException if an error occurs writing out the rowset
  445. * contents to XML
  446. */
  447. public void writeXml(java.io.Writer writer) throws SQLException;
  448. /**
  449. * Writes the data, properties, and metadata for this <code>WebRowSet</code> object
  450. * to the given <code>OutputStream</code> object in XML format.
  451. *
  452. * @param oStream the <code>java.io.OutputStream</code> stream to write to
  453. * @throws SQLException if a data source access error occurs
  454. * @throws IOException if a IO exception occurs
  455. */
  456. public void writeXml(java.io.OutputStream oStream) throws SQLException, IOException;
  457. /**
  458. * The public identifier for the XML Schema definition that defines the XML
  459. * tags and their valid values for a <code>WebRowSet</code> implementation.
  460. */
  461. public static String PUBLIC_XML_SCHEMA =
  462. "--//Sun Microsystems, Inc.//XSD Schema//EN";
  463. /**
  464. * The URL for the XML Schema definition file that defines the XML tags and
  465. * their valid values for a <code>WebRowSet</code> implementation.
  466. */
  467. public static String SCHEMA_SYSTEM_ID = "http://java.sun.com/xml/ns/jdbc/webrowset.xsd";
  468. }