1 /* 2 * Copyright (c) 2003, 2010, 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</code> 37 * must implement. 38 * <P> 39 * <h3>1.0 Overview</h3> 40 * The <code>WebRowSetImpl</code> 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 * <pre> 47 * <a href="http://java.sun.com/xml/ns/jdbc/webrowset.xsd">http://java.sun.com/xml/ns/jdbc/webrowset.xsd</a> 48 * </pre> 49 * </ul> 50 * It describes the standard XML document format required when describing a 51 * <code>RowSet</code> object in XML and must be used be all standard implementations 52 * of the <code>WebRowSet</code> interface to ensure interoperability. In addition, 53 * the <code>WebRowSet</code> 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 * <pre> 59 * <a href="http://standards.iso.org/iso/9075/2002/12/sqlxml">http://standards.iso.org/iso/9075/2002/12/sqlxml</a> 60 * </pre> 61 * </ul> 62 * The schema definition describes the internal data of a <code>RowSet</code> object 63 * in three distinct areas: 64 * <UL> 65 * <li><b>properties</b></li> 66 * These properties describe the standard synchronization provider properties in 67 * addition to the more general <code>RowSet</code> properties. 68 * <p> 69 * <li><b>metadata</b></li> 70 * This describes the metadata associated with the tabular structure governed by a 71 * <code>WebRowSet</code> object. The metadata described is closely aligned with the 72 * metadata accessible in the underlying <code>java.sql.ResultSet</code> interface. 73 * <p> 74 * <li><b>data</b></li> 75 * This describes the original data (the state of data since the last population 76 * or last synchronization of the <code>WebRowSet</code> object) and the current 77 * data. By keeping track of the delta between the original data and the current data, 78 * a <code>WebRowSet</code> maintains 79 * the ability to synchronize changes in its data back to the originating data source. 80 * </ul> 81 * <P> 82 * <h3>2.0 WebRowSet States</h3> 83 * The following sections demonstrates how a <code>WebRowSet</code> implementation 84 * should use the XML Schema to describe update, insert, and delete operations 85 * and to describe the state of a <code>WebRowSet</code> object in XML. 86 * <p> 87 * <h4>2.1 State 1 - Outputting a <code>WebRowSet</code> Object to XML</h3> 88 * In this example, a <code>WebRowSet</code> object is created and populated with a simple 2 column, 89 * 5 row table from a data source. Having the 5 rows in a <code>WebRowSet</code> object 90 * makes it possible to describe them in XML. The 91 * metadata describing the various standard JavaBeans properties as defined 92 * in the RowSet interface plus the standard properties defined in 93 * the <code>CachedRowSet</code><sup><font size=-2>TM</font></sup> interface 94 * provide key details that describe WebRowSet 95 * properties. Outputting the WebRowSet object to XML using the standard 96 * <code>writeXml</code> methods describes the internal properties as follows: 97 * <PRE> 98 * <<font color=red>properties</font>> 99 * <<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>>Oracle Corporation<<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) throws SQLException, IOException; 430 431 /** 432 * Populates this <code>WebRowSet</code> object with 433 * the contents of the given <code>ResultSet</code> object and writes its 434 * data, properties, and metadata 435 * to the given <code>Writer</code> object in XML format. 436 * <p> 437 * NOTE: The <code>WebRowSet</code> cursor may be moved to write out the 438 * contents to the XML data source. If implemented in this way, the cursor <b>must</b> 439 * be returned to its position just prior to the <code>writeXml()</code> call. 440 * 441 * @param rs the <code>ResultSet</code> object with which to populate this 442 * <code>WebRowSet</code> object 443 * @param writer the <code>java.io.Writer</code> object to write to. 444 * @throws SQLException if an error occurs writing out the rowset 445 * contents in XML format 446 */ 447 public void writeXml(ResultSet rs, java.io.Writer writer) throws SQLException; 448 449 /** 450 * Populates this <code>WebRowSet</code> object with 451 * the contents of the given <code>ResultSet</code> object and writes its 452 * data, properties, and metadata 453 * to the given <code>OutputStream</code> object in XML format. 454 * <p> 455 * NOTE: The <code>WebRowSet</code> cursor may be moved to write out the 456 * contents to the XML data source. If implemented in this way, the cursor <b>must</b> 457 * be returned to its position just prior to the <code>writeXml()</code> call. 458 * 459 * @param rs the <code>ResultSet</code> object with which to populate this 460 * <code>WebRowSet</code> object 461 * @param oStream the <code>java.io.OutputStream</code> to write to 462 * @throws SQLException if a data source access error occurs 463 * @throws IOException if a IO exception occurs 464 */ 465 public void writeXml(ResultSet rs, java.io.OutputStream oStream) throws SQLException, IOException; 466 467 /** 468 * Writes the data, properties, and metadata for this <code>WebRowSet</code> object 469 * to the given <code>Writer</code> object in XML format. 470 * 471 * @param writer the <code>java.io.Writer</code> stream to write to 472 * @throws SQLException if an error occurs writing out the rowset 473 * contents to XML 474 */ 475 public void writeXml(java.io.Writer writer) throws SQLException; 476 477 /** 478 * Writes the data, properties, and metadata for this <code>WebRowSet</code> object 479 * to the given <code>OutputStream</code> object in XML format. 480 * 481 * @param oStream the <code>java.io.OutputStream</code> stream to write to 482 * @throws SQLException if a data source access error occurs 483 * @throws IOException if a IO exception occurs 484 */ 485 public void writeXml(java.io.OutputStream oStream) throws SQLException, IOException; 486 487 /** 488 * The public identifier for the XML Schema definition that defines the XML 489 * tags and their valid values for a <code>WebRowSet</code> implementation. 490 */ 491 public static String PUBLIC_XML_SCHEMA = 492 "--//Oracle Corporation//XSD Schema//EN"; 493 494 /** 495 * The URL for the XML Schema definition file that defines the XML tags and 496 * their valid values for a <code>WebRowSet</code> implementation. 497 */ 498 public static String SCHEMA_SYSTEM_ID = "http://java.sun.com/xml/ns/jdbc/webrowset.xsd"; 499 }