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