1/* 2 * Copyright (c) 2003, 2014, 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 26package javax.sql.rowset; 27 28import java.sql.*; 29import javax.sql.*; 30import javax.naming.*; 31import java.io.*; 32import java.math.*; 33import 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 interoperability. 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.xsd">http://standards.iso.org/iso/9075/2002/12/sqlxml.xsd</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_UNCOMMITTED</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 414public 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} 507