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}™ 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 * @since 1.5
412 */
413
414 public interface WebRowSet extends CachedRowSet {
415
416 /**
417 * Reads a {@code WebRowSet} object in its XML format from the given
418 * {@code Reader} object.
419 *
420 * @param reader the {@code java.io.Reader} stream from which this
421 * {@code WebRowSet} object will be populated
422
423 * @throws SQLException if a database access error occurs
424 */
425 public void readXml(java.io.Reader reader) throws SQLException;
426
427 /**
428 * Reads a stream based XML input to populate this {@code WebRowSet}
429 * object.
430 *
431 * @param iStream the {@code java.io.InputStream} from which this
432 * {@code WebRowSet} object will be populated
433 * @throws SQLException if a data source access error occurs
434 * @throws IOException if an IO exception occurs
435 */
436 public void readXml(java.io.InputStream iStream) throws SQLException, IOException;
437
438 /**
439 * Populates this {@code WebRowSet} object with
440 * the contents of the given {@code ResultSet} object and writes its
441 * data, properties, and metadata
442 * to the given {@code Writer} object in XML format.
443 * <p>
444 * NOTE: The {@code WebRowSet} cursor may be moved to write out the
445 * contents to the XML data source. If implemented in this way, the cursor <b>must</b>
446 * be returned to its position just prior to the {@code writeXml()} call.
447 *
448 * @param rs the {@code ResultSet} object with which to populate this
449 * {@code WebRowSet} object
450 * @param writer the {@code java.io.Writer} object to write to.
451 * @throws SQLException if an error occurs writing out the rowset
452 * contents in XML format
453 */
454 public void writeXml(ResultSet rs, java.io.Writer writer) throws SQLException;
455
456 /**
457 * Populates this {@code WebRowSet} object with
458 * the contents of the given {@code ResultSet} object and writes its
459 * data, properties, and metadata
460 * to the given {@code OutputStream} object in XML format.
461 * <p>
462 * NOTE: The {@code WebRowSet} cursor may be moved to write out the
463 * contents to the XML data source. If implemented in this way, the cursor <b>must</b>
464 * be returned to its position just prior to the {@code writeXml()} call.
465 *
466 * @param rs the {@code ResultSet} object with which to populate this
467 * {@code WebRowSet} object
468 * @param oStream the {@code java.io.OutputStream} to write to
469 * @throws SQLException if a data source access error occurs
470 * @throws IOException if a IO exception occurs
471 */
472 public void writeXml(ResultSet rs, java.io.OutputStream oStream) throws SQLException, IOException;
473
474 /**
475 * Writes the data, properties, and metadata for this {@code WebRowSet} object
476 * to the given {@code Writer} object in XML format.
477 *
478 * @param writer the {@code java.io.Writer} stream to write to
479 * @throws SQLException if an error occurs writing out the rowset
480 * contents to XML
481 */
482 public void writeXml(java.io.Writer writer) throws SQLException;
483
484 /**
485 * Writes the data, properties, and metadata for this {@code WebRowSet} object
486 * to the given {@code OutputStream} object in XML format.
487 *
488 * @param oStream the {@code java.io.OutputStream} stream to write to
489 * @throws SQLException if a data source access error occurs
490 * @throws IOException if a IO exception occurs
491 */
492 public void writeXml(java.io.OutputStream oStream) throws SQLException, IOException;
493
494 /**
495 * The public identifier for the XML Schema definition that defines the XML
496 * tags and their valid values for a {@code WebRowSet} implementation.
497 */
498 public static String PUBLIC_XML_SCHEMA =
499 "--//Oracle Corporation//XSD Schema//EN";
500
501 /**
502 * The URL for the XML Schema definition file that defines the XML tags and
503 * their valid values for a {@code WebRowSet} implementation.
504 */
505 public static String SCHEMA_SYSTEM_ID = "http://java.sun.com/xml/ns/jdbc/webrowset.xsd";
506 }