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
TheWebRowSetImpl
provides the standard reference implementation, which may be extended if required.
The standard WebRowSet XML Schema definition is available at the following URI:
It describes the standard XML document format required when describing aRowSet
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 interoperability. This is an effort currently under way at the ISO organization. The SQL/XML definition is available at the following URI: 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 underlyingjava.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, aWebRowSet
maintains the ability to synchronize changes in its data back to the originating data source.
2.0 WebRowSet States
The following sections demonstrates how aWebRowSet
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_UNCOMMITTED</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 aWebRowSet
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
AWebRowSet
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>
- Since:
- 1.5
- See Also:
-
JdbcRowSet
,CachedRowSet
,FilteredRowSet
,JoinRowSet
Field Summary
Modifier and Type | Field | 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 |
static String | SCHEMA_SYSTEM_ID | The URL for the XML Schema definition file that defines the XML tags and their valid values for a |
Fields declared in interface javax.sql.rowset.CachedRowSet
COMMIT_ON_ACCEPT_CHANGES
Fields declared in 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
Modifier and Type | Method | Description |
---|---|---|
void | readXml(InputStream iStream) | Reads a stream based XML input to populate this |
void | readXml(Reader reader) | Reads a |
void | writeXml(OutputStream oStream) | Writes the data, properties, and metadata for this |
void | writeXml(Writer writer) | Writes the data, properties, and metadata for this |
void | writeXml(ResultSet rs,
OutputStream oStream) | Populates this |
void | writeXml(ResultSet rs,
Writer writer) | Populates this |
Methods declared in 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 declared in interface javax.sql.rowset.Joinable
getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn
Methods declared in 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 declared in 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 declared in interface java.sql.Wrapper
isWrapperFor, unwrap
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
- thejava.io.Reader
stream from which thisWebRowSet
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
- thejava.io.InputStream
from which thisWebRowSet
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
- theResultSet
object with which to populate thisWebRowSet
object -
writer
- thejava.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
- theResultSet
object with which to populate thisWebRowSet
object -
oStream
- thejava.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
- thejava.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
- thejava.io.OutputStream
stream to write to - Throws:
-
SQLException
- if a data source access error occurs -
IOException
- if a IO exception occurs