WebRowSet (Java Platform SE 8 )
Keywords: javax.sql.rowset.WebRowSet interface
Date: 2020-03-26

compact3
javax.sql.rowset

## Interface WebRowSet

- All Superinterfaces:
    AutoCloseable, CachedRowSet, Joinable, ResultSet, RowSet, Wrapper
  All Known Subinterfaces:
    FilteredRowSet, JoinRowSet

      public interface WebRowSet
      extends CachedRowSet

  The standard interface that all implementations of a `WebRowSet` must implement.

  ### 1.0 Overview

  The `WebRowSetImpl` provides the standard reference implementation, which may be extended if required.

  The standard WebRowSet XML Schema definition is available at the following URI:

  - http://java.sun.com/xml/ns/jdbc/webrowset.xsd
  It describes the standard XML document format required when describing a `RowSet` object in XML and must be used be all standard implementations of the `WebRowSet` interface to ensure interoperability. In addition, the `WebRowSet` schema uses specific SQL/XML Schema annotations, thus ensuring greater cross platform inter-operability. This is an effort currently under way at the ISO organization. The SQL/XML definition is available at the following URI:
  - http://standards.iso.org/iso/9075/2002/12/sqlxml
  The schema definition describes the internal data of a `RowSet` object in three distinct areas:
  - properties - These properties describe the standard synchronization provider properties in addition to the more general `RowSet` properties.
  - metadata - This describes the metadata associated with the tabular structure governed by a `WebRowSet` object. The metadata described is closely aligned with the metadata accessible in the underlying `java.sql.ResultSet` interface.
  - data - This describes the original data (the state of data since the last population or last synchronization of the `WebRowSet` object) and the current data. By keeping track of the delta between the original data and the current data, a `WebRowSet` maintains the ability to synchronize changes in its data back to the originating data source.

  ### 2.0 WebRowSet States

  The following sections demonstrates how a `WebRowSet` implementation should use the XML Schema to describe update, insert, and delete operations and to describe the state of a `WebRowSet` object in XML.

  #### 2.1 State 1 - Outputting a `WebRowSet` Object to XML

  In this example, a `WebRowSet` object is created and populated with a simple 2 column, 5 row table from a data source. Having the 5 rows in a `WebRowSet` object makes it possible to describe them in XML. The metadata describing the various standard JavaBeans properties as defined in the RowSet interface plus the standard properties defined in the `CachedRowSet`™ interface provide key details that describe WebRowSet properties. Outputting the WebRowSet object to XML using the standard `writeXml` methods describes the internal properties as follows:

       <properties>
             <command>select co1, col2 from test_table</command>
            <concurrency>1</concurrency>
            <datasource/>
            <escape-processing>true</escape-processing>
            <fetch-direction>0</fetch-direction>
            <fetch-size>0</fetch-size>
            <isolation-level>1</isolation-level>
            <key-columns/>
            <map/>
            <max-field-size>0</max-field-size>
            <max-rows>0</max-rows>
            <query-timeout>0</query-timeout>
            <read-only>false</read-only>
            <rowset-type>TRANSACTION_READ_UNCOMMITED</rowset-type>
            <show-deleted>false</show-deleted>
            <table-name/>
            <url>jdbc:thin:oracle</url>
            <sync-provider>
                    <sync-provider-name>.com.rowset.provider.RIOptimisticProvider</sync-provider-name>
                    <sync-provider-vendor>Oracle Corporation</sync-provider-vendor>
                    <sync-provider-version>1.0</sync-provider-name>
                    <sync-provider-grade>LOW</sync-provider-grade>
                    <data-source-lock>NONE</data-source-lock>
            </sync-provider>
       </properties>

  The meta-data describing the make up of the WebRowSet is described in XML as detailed below. Note both columns are described between the `column-definition` tags.

       <metadata>
            <column-count>2</column-count>
            <column-definition>
                    <column-index>1</column-index>
                    <auto-increment>false</auto-increment>
                    <case-sensitive>true</case-sensitive>
                    <currency>false</currency>
                    <nullable>1</nullable>
                    <signed>false</signed>
                    <searchable>true</searchable>
                    <column-display-size>10</column-display-size>
                    <column-label>COL1</column-label>
                    <column-name>COL1</column-name>
                    <schema-name/>
                    <column-precision>10</column-precision>
                    <column-scale>0</column-scale>
                    <table-name/>
                    <catalog-name/>
                    <column-type>1</column-type>
                    <column-type-name>CHAR</column-type-name>
            </column-definition>
            <column-definition>
                    <column-index>2</column-index>
                    <auto-increment>false</auto-increment>
                    <case-sensitive>false</case-sensitive>
                    <currency>false</currency>
                    <nullable>1</nullable>
                    <signed>true</signed>
                    <searchable>true</searchable>
                    <column-display-size>39</column-display-size>
                    <column-label>COL2</column-label>
                    <column-name>COL2</column-name>
                    <schema-name/>
                    <column-precision>38</column-precision>
                    <column-scale>0</column-scale>
                    <table-name/>
                    <catalog-name/>
                    <column-type>3</column-type>
                    <column-type-name>NUMBER</column-type-name>
            </column-definition>
       </metadata>

  Having detailed how the properties and metadata are described, the following details how the contents of a `WebRowSet` object is described in XML. Note, that this describes a `WebRowSet` object that has not undergone any modifications since its instantiation. A `currentRow` tag is mapped to each row of the table structure that the `WebRowSet` object provides. A `columnValue` tag may contain either the `stringData` or `binaryData` tag, according to the SQL type that the XML value is mapping back to. The `binaryData` tag contains data in the Base64 encoding and is typically used for `BLOB` and `CLOB` type data.

       <data>
            <currentRow>
                    <columnValue>
                            firstrow
                    </columnValue>
                    <columnValue>
                            1
                    </columnValue>
            </currentRow>
            <currentRow>
                    <columnValue>
                            secondrow
                    </columnValue>
                    <columnValue>
                            2
                    </columnValue>
            </currentRow>
            <currentRow>
                    <columnValue>
                            thirdrow
                    </columnValue>
                    <columnValue>
                            3
                    </columnValue>
            </currentRow>
            <currentRow>
                    <columnValue>
                            fourthrow
                    </columnValue>
                    <columnValue>
                            4
                    </columnValue>
            </currentRow>
       </data>

  #### 2.2 State 2 - Deleting a Row

  Deleting a row in a `WebRowSet` object involves simply moving to the row to be deleted and then calling the method `deleteRow`, as in any other `RowSet` object. The following two lines of code, in which wrs is a `WebRowSet` object, delete the third row.

           wrs.absolute(3);
           wrs.deleteRow();

  The XML description shows the third row is marked as a `deleteRow`, which eliminates the third row in the `WebRowSet` object.

       <data>
            <currentRow>
                    <columnValue>
                            firstrow
                    </columnValue>
                    <columnValue>
                            1
                    </columnValue>
            </currentRow>
            <currentRow>
                    <columnValue>
                            secondrow
                    </columnValue>
                    <columnValue>
                            2
                    </columnValue>
            </currentRow>
            <deleteRow>
                    <columnValue>
                            thirdrow
                    </columnValue>
                    <columnValue>
                            3
                    </columnValue>
            </deleteRow>
            <currentRow>
                    <columnValue>
                            fourthrow
                    </columnValue>
                    <columnValue>
                            4
                    </columnValue>
            </currentRow>
       </data>

  #### 2.3 State 3 - Inserting a Row

  A `WebRowSet` object can insert a new row by moving to the insert row, calling the appropriate updater methods for each column in the row, and then calling the method `insertRow`.

       wrs.moveToInsertRow();
       wrs.updateString(1, "fifththrow");
       wrs.updateString(2, "5");
       wrs.insertRow();

  The following code fragment changes the second column value in the row just inserted. Note that this code applies when new rows are inserted right after the current row, which is why the method `next` moves the cursor to the correct row. Calling the method `acceptChanges` writes the change to the data source.

        wrs.moveToCurrentRow();
       wrs.next();
       wrs.updateString(2, "V");
       wrs.acceptChanges();

  Describing this in XML demonstrates where the Java code inserts a new row and then performs an update on the newly inserted row on an individual field.

       <data>
            <currentRow>
                    <columnValue>
                            firstrow
                    </columnValue>
                    <columnValue>
                            1
                    </columnValue>
            </currentRow>
            <currentRow>
                    <columnValue>
                            secondrow
                    </columnValue>
                    <columnValue>
                            2
                    </columnValue>
            </currentRow>
            <currentRow>
                    <columnValue>
                            newthirdrow
                    </columnValue>
                    <columnValue>
                            III
                    </columnValue>
            </currentRow>
            <insertRow>
                    <columnValue>
                            fifthrow
                    </columnValue>
                    <columnValue>
                            5
                    </columnValue>
                    <updateValue>
                            V
                    </updateValue>
            </insertRow>
            <currentRow>
                    <columnValue>
                            fourthrow
                    </columnValue>
                    <columnValue>
                            4
                    </columnValue>
            </currentRow>
       </date>

  #### 2.4 State 4 - Modifying a Row

  Modifying a row produces specific XML that records both the new value and the value that was replaced. The value that was replaced becomes the original value, and the new value becomes the current value. The following code moves the cursor to a specific row, performs some modifications, and updates the row when complete.

       wrs.absolute(5);
       wrs.updateString(1, "new4thRow");
       wrs.updateString(2, "IV");
       wrs.updateRow();

  In XML, this is described by the `modifyRow` tag. Both the original and new values are contained within the tag for original row tracking purposes.

       <data>
            <currentRow>
                    <columnValue>
                            firstrow
                    </columnValue>
                    <columnValue>
                            1
                    </columnValue>
            </currentRow>
            <currentRow>
                    <columnValue>
                            secondrow
                    </columnValue>
                    <columnValue>
                            2
                    </columnValue>
            </currentRow>
            <currentRow>
                    <columnValue>
                            newthirdrow
                    </columnValue>
                    <columnValue>
                            III
                    </columnValue>
            </currentRow>
            <currentRow>
                    <columnValue>
                            fifthrow
                    </columnValue>
                    <columnValue>
                            5
                    </columnValue>
            </currentRow>
            <modifyRow>
                    <columnValue>
                            fourthrow
                    </columnValue>
                    <updateValue>
                            new4thRow
                    </updateValue>
                    <columnValue>
                            4
                    </columnValue>
                    <updateValue>
                            IV
                    </updateValue>
            </modifyRow>
       </data>

  See Also:
    `JdbcRowSet`, `CachedRowSet`, `FilteredRowSet`, `JoinRowSet`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `PUBLIC_XML_SCHEMA` The public identifier for the XML Schema definition that defines the XML tags and their valid values for a `WebRowSet` implementation.
    `static String` | `SCHEMA_SYSTEM_ID` The URL for the XML Schema definition file that defines the XML tags and their valid values for a `WebRowSet` implementation.

    - ### Fields inherited from interface javax.sql.rowset.CachedRowSet

      `COMMIT_ON_ACCEPT_CHANGES`

    - ### Fields inherited from interface java.sql.ResultSet

      `CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `readXml(InputStream iStream)` Reads a stream based XML input to populate this `WebRowSet` object.
    `void` | `readXml(Reader reader)` Reads a `WebRowSet` object in its XML format from the given `Reader` object.
    `void` | `writeXml(OutputStream oStream)` Writes the data, properties, and metadata for this `WebRowSet` object to the given `OutputStream` object in XML format.
    `void` | `writeXml(ResultSet rs, OutputStream oStream)` Populates this `WebRowSet` object with the contents of the given `ResultSet` object and writes its data, properties, and metadata to the given `OutputStream` object in XML format.
    `void` | `writeXml(ResultSet rs, Writer writer)` Populates this `WebRowSet` object with the contents of the given `ResultSet` object and writes its data, properties, and metadata to the given `Writer` object in XML format.
    `void` | `writeXml(Writer writer)` Writes the data, properties, and metadata for this `WebRowSet` object to the given `Writer` object in XML format.

    - ### Methods inherited from interface javax.sql.rowset.CachedRowSet

      `acceptChanges, acceptChanges, columnUpdated, columnUpdated, commit, createCopy, createCopyNoConstraints, createCopySchema, createShared, execute, getKeyColumns, getOriginal, getOriginalRow, getPageSize, getRowSetWarnings, getShowDeleted, getSyncProvider, getTableName, nextPage, populate, populate, previousPage, release, restoreOriginal, rollback, rollback, rowSetPopulated, setKeyColumns, setMetaData, setOriginalRow, setPageSize, setShowDeleted, setSyncProvider, setTableName, size, toCollection, toCollection, toCollection, undoDelete, undoInsert, undoUpdate`

    - ### Methods inherited from interface javax.sql.RowSet

      `addRowSetListener, clearParameters, execute, getCommand, getDataSourceName, getEscapeProcessing, getMaxFieldSize, getMaxRows, getPassword, getQueryTimeout, getTransactionIsolation, getTypeMap, getUrl, getUsername, isReadOnly, removeRowSetListener, setArray, setAsciiStream, setAsciiStream, setAsciiStream, setAsciiStream, setBigDecimal, setBigDecimal, setBinaryStream, setBinaryStream, setBinaryStream, setBinaryStream, setBlob, setBlob, setBlob, setBlob, setBlob, setBlob, setBoolean, setBoolean, setByte, setByte, setBytes, setBytes, setCharacterStream, setCharacterStream, setCharacterStream, setCharacterStream, setClob, setClob, setClob, setClob, setClob, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDate, setDate, setDouble, setDouble, setEscapeProcessing, setFloat, setFloat, setInt, setInt, setLong, setLong, setMaxFieldSize, setMaxRows, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNClob, setNClob, setNClob, setNClob, setNClob, setNClob, setNString, setNString, setNull, setNull, setNull, setNull, setObject, setObject, setObject, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setRowId, setRowId, setShort, setShort, setSQLXML, setSQLXML, setString, setString, setTime, setTime, setTime, setTime, setTimestamp, setTimestamp, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, setURL, setUrl, setUsername`

    - ### Methods inherited from interface java.sql.ResultSet

      `absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, close, deleteRow, findColumn, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getHoldability, getInt, getInt, getLong, getLong, getMetaData, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getRowId, getRowId, getShort, getShort, getSQLXML, getSQLXML, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull`

    - ### Methods inherited from interface java.sql.Wrapper

      `isWrapperFor, unwrap`

    - ### Methods inherited from interface javax.sql.rowset.Joinable

      `getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn`

- - ### Field Detail

    - #### PUBLIC_XML_SCHEMA

          static final String PUBLIC_XML_SCHEMA

      The public identifier for the XML Schema definition that defines the XML tags and their valid values for a `WebRowSet` implementation.
      See Also:
        Constant Field Values

    - #### SCHEMA_SYSTEM_ID

          static final String SCHEMA_SYSTEM_ID

      The URL for the XML Schema definition file that defines the XML tags and their valid values for a `WebRowSet` implementation.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### readXml

          void readXml(Reader reader)
                throws SQLException

      Reads a `WebRowSet` object in its XML format from the given `Reader` object.
      Parameters:
        `reader` - the `java.io.Reader` stream from which this `WebRowSet` object will be populated
      Throws:
        `SQLException` - if a database access error occurs

    - #### readXml

          void readXml(InputStream iStream)
                throws SQLException,
                       IOException

      Reads a stream based XML input to populate this `WebRowSet` object.
      Parameters:
        `iStream` - the `java.io.InputStream` from which this `WebRowSet` object will be populated
      Throws:
        `SQLException` - if a data source access error occurs
        `IOException` - if an IO exception occurs

    - #### writeXml

          void writeXml(ResultSet rs,
                        Writer writer)
                 throws SQLException

      Populates this `WebRowSet` object with the contents of the given `ResultSet` object and writes its data, properties, and metadata to the given `Writer` object in XML format.

      NOTE: The `WebRowSet` cursor may be moved to write out the contents to the XML data source. If implemented in this way, the cursor must be returned to its position just prior to the `writeXml()` call.

      Parameters:
        `rs` - the `ResultSet` object with which to populate this `WebRowSet` object
        `writer` - the `java.io.Writer` object to write to.
      Throws:
        `SQLException` - if an error occurs writing out the rowset contents in XML format

    - #### writeXml

          void writeXml(ResultSet rs,
                        OutputStream oStream)
                 throws SQLException,
                        IOException

      Populates this `WebRowSet` object with the contents of the given `ResultSet` object and writes its data, properties, and metadata to the given `OutputStream` object in XML format.

      NOTE: The `WebRowSet` cursor may be moved to write out the contents to the XML data source. If implemented in this way, the cursor must be returned to its position just prior to the `writeXml()` call.

      Parameters:
        `rs` - the `ResultSet` object with which to populate this `WebRowSet` object
        `oStream` - the `java.io.OutputStream` to write to
      Throws:
        `SQLException` - if a data source access error occurs
        `IOException` - if a IO exception occurs

    - #### writeXml

          void writeXml(Writer writer)
                 throws SQLException

      Writes the data, properties, and metadata for this `WebRowSet` object to the given `Writer` object in XML format.
      Parameters:
        `writer` - the `java.io.Writer` stream to write to
      Throws:
        `SQLException` - if an error occurs writing out the rowset contents to XML

    - #### writeXml

          void writeXml(OutputStream oStream)
                 throws SQLException,
                        IOException

      Writes the data, properties, and metadata for this `WebRowSet` object to the given `OutputStream` object in XML format.
      Parameters:
        `oStream` - the `java.io.OutputStream` stream to write to
      Throws:
        `SQLException` - if a data source access error occurs
        `IOException` - if a IO exception occurs

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2020, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.