Interface WebRowSet
- All Superinterfaces:
AutoCloseable,CachedRowSet,Joinable,ResultSet,RowSet,Wrapper
- All Known Subinterfaces:
FilteredRowSet,JoinRowSet
The standard interface that all implementations of a 2.1 State 1 - Outputting a
In this example, 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
RowSetproperties. - metadata - This describes the metadata associated with the tabular structure governed by a
WebRowSetobject. The metadata described is closely aligned with the metadata accessible in the underlyingjava.sql.ResultSetinterface. - data - This describes the original data (the state of data since the
last population
or last synchronization of the
WebRowSetobject) and the current data. By keeping track of the delta between the original data and the current data, aWebRowSetmaintains 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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringThe public identifier for the XML Schema definition that defines the XML tags and their valid values for aWebRowSetimplementation.static final StringThe URL for the XML Schema definition file that defines the XML tags and their valid values for aWebRowSetimplementation.Fields declared in interface javax.sql.rowset.CachedRowSet
COMMIT_ON_ACCEPT_CHANGESFields 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 TypeMethodDescriptionvoidreadXml(InputStream iStream) Reads a stream based XML input to populate thisWebRowSetobject.voidReads aWebRowSetobject in its XML format from the givenReaderobject.voidwriteXml(OutputStream oStream) Writes the data, properties, and metadata for thisWebRowSetobject to the givenOutputStreamobject in XML format.voidWrites the data, properties, and metadata for thisWebRowSetobject to the givenWriterobject in XML format.voidwriteXml(ResultSet rs, OutputStream oStream) Populates thisWebRowSetobject with the contents of the givenResultSetobject and writes its data, properties, and metadata to the givenOutputStreamobject in XML format.voidPopulates thisWebRowSetobject with the contents of the givenResultSetobject and writes its data, properties, and metadata to the givenWriterobject in XML format.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, undoUpdateMethods declared in interface javax.sql.rowset.Joinable
getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumnMethods 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, wasNullMethods 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, setUsernameMethods declared in interface java.sql.Wrapper
isWrapperFor, unwrap
-
Field Details
-
PUBLIC_XML_SCHEMA
The public identifier for the XML Schema definition that defines the XML tags and their valid values for aWebRowSetimplementation.- See Also:
-
SCHEMA_SYSTEM_ID
The URL for the XML Schema definition file that defines the XML tags and their valid values for aWebRowSetimplementation.- See Also:
-
-
Method Details
-
readXml
Reads aWebRowSetobject in its XML format from the givenReaderobject.- Parameters:
reader- thejava.io.Readerstream from which thisWebRowSetobject will be populated- Throws:
SQLException- if a database access error occurs
-
readXml
Reads a stream based XML input to populate thisWebRowSetobject.- Parameters:
iStream- thejava.io.InputStreamfrom which thisWebRowSetobject will be populated- Throws:
SQLException- if a data source access error occursIOException- if an IO exception occurs
-
writeXml
Populates thisWebRowSetobject with the contents of the givenResultSetobject and writes its data, properties, and metadata to the givenWriterobject in XML format.NOTE: The
WebRowSetcursor 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 thewriteXml()call.- Parameters:
rs- theResultSetobject with which to populate thisWebRowSetobjectwriter- thejava.io.Writerobject to write to.- Throws:
SQLException- if an error occurs writing out the rowset contents in XML format
-
writeXml
Populates thisWebRowSetobject with the contents of the givenResultSetobject and writes its data, properties, and metadata to the givenOutputStreamobject in XML format.NOTE: The
WebRowSetcursor 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 thewriteXml()call.- Parameters:
rs- theResultSetobject with which to populate thisWebRowSetobjectoStream- thejava.io.OutputStreamto write to- Throws:
SQLException- if a data source access error occursIOException- if a IO exception occurs
-
writeXml
Writes the data, properties, and metadata for thisWebRowSetobject to the givenWriterobject in XML format.- Parameters:
writer- thejava.io.Writerstream to write to- Throws:
SQLException- if an error occurs writing out the rowset contents to XML
-
writeXml
Writes the data, properties, and metadata for thisWebRowSetobject to the givenOutputStreamobject in XML format.- Parameters:
oStream- thejava.io.OutputStreamstream to write to- Throws:
SQLException- if a data source access error occursIOException- if a IO exception occurs
-