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