WebLogic Server 8.1 API Reference

weblogic.jdbc.rowset
Interface WLCachedRowSet

public interface WLCachedRowSet

extends javax.sql.RowSet, java.io.Serializable

WLCachedRowSet is an extension to the javax.sql.RowSet interface.

WLCachedRowSet is a disconnected RowSet. Data is read into the RowSet from a JDBC query, an existing java.sql.ResultSet, or an XML document. The RowSet then has the data in memory and does not maintain any open connections or transactions in the database.

All reads, writes, deletes, and inserts occur in memory. When the acceptChanges method is called, the WLCachedRowSet writes any inserts, updates, or deletes to the database.

Since the WLCachedRowSet does not hold open any transactions between reading and updating the data, it uses optimistic concurrency control to verify the state of the underlying database row has not changed.

The WLCachedRowSet interface extends java.io.Serializable so a WLCachedRowSet may be serialized and sent across a network connection to a client.

The WLCachedRowSet may be written as an XML instance document. This XML document captures the row(s) currently cached in the WLCachedRowSet

A WLCachedRowSet is created from the RowSetFactory class.

 RowSetFactory factory = RowSetFactory.newInstance();
 WLCachedRowSet rowSet = factory.newCachedRowSet(); 
 

A detailed discussion of the WLCachedRowSet's optimistic concurrency control options can be found in the WLRowSetMetaData javadocs.

Author:

Copyright © 2004 BEA Systems, Inc. All Rights Reserved.

See Also:

WLRowSetMetaData

Field Summary

static int	ALL_ROWS XML Document includes all rows with both their changed and original values
static int	CHANGED_ALL XML Document includes the current and original values for all changed rows.
static int	CHANGED_CURRENT XML Document includes only changed rows with their current values.
static int	CHANGED_ORIGINAL XML Document includes only changed rows with their original values.
static int	CURRENT_ALL XML Document includes the current values for all rows.
static int	UNCHANGED_CURRENT XML Document includes only unchanged rows.

Fields inherited from class 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

void	acceptChanges() acceptChanges asks the RowSet to write its values back to the underlying database.
java.lang.String	executeAndGuessTableName() Executes the command, parses it, and sets the table name as the first word following the SQL keyword "from".
boolean	executeAndGuessTableNameAndPrimaryKeys() Executes the command, parses it, sets the table name as the first word following the SQL keyword "from", and then looks up the table in DatabaseMetaData to determine the primary keys.
java.util.Map	getCurrentRow() Returns a Map representing the current row in the RowSet.
javax.sql.DataSource	getDataSource() Returns the current javax.sql.DataSource for this RowSet.
java.util.Map	getRow(int index) Returns a Map representing the row at the specified index
java.util.Map[]	getRows() Returns an array of Maps representing all rows in the rowset
java.util.Map[]	getRows(int startIndex, int endIndex) Returns an array of Maps representing the rows in the rowset from [startIndex...endIndex-1]
boolean	isComplete() Returns whether the populating query read all matching rows, or it hit the maxRows limit.
void	loadXML(XMLInputStream xis) Populates the RowSet from an XML document in the XMLInputStream.
void	populate(java.sql.ResultSet rs) Loads the RowSet with data from an existing java.sql.ResultSet.
void	populate(java.sql.ResultSetMetaData md) Loads a ResultSet from an existing java.sql.ResultSetMetaData.
void	setDataSource(javax.sql.DataSource dataSource) Sets the javax.sql.DataSource used for establishing JDBC Connections.
int	size() Returns the number of rows in the WLCachedRowSet.
void	writeXML(XMLOutputStream xos) Writes the RowSet to the XMLOutputStream as an XML document.
void	writeXML(XMLOutputStream xos, int rowStates) Writes the RowSet as an XML document.

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, setBigDecimal, setBinaryStream, setBlob, setBoolean, setByte, setBytes, setCharacterStream, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDouble, setEscapeProcessing, setFloat, setInt, setLong, setMaxFieldSize, setMaxRows, setNull, setNull, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setShort, setString, setTime, setTime, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, 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, getInt, getInt, getLong, getLong, getMetaData, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getShort, getShort, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateShort, updateShort, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull

Field Detail

UNCHANGED_CURRENT

public static final int UNCHANGED_CURRENT

XML Document includes only unchanged rows. A row is unchanged if it has not been inserted, updated, or deleted in the rowset.

CHANGED_CURRENT

public static final int CHANGED_CURRENT

XML Document includes only changed rows with their current values. A changed row has been inserted, updated, or deleted in the rowset.

CHANGED_ORIGINAL

public static final int CHANGED_ORIGINAL

XML Document includes only changed rows with their original values. A changed row has been inserted, updated, or deleted in the rowset.

CURRENT_ALL

public static final int CURRENT_ALL

XML Document includes the current values for all rows.

CHANGED_ALL

public static final int CHANGED_ALL

XML Document includes the current and original values for all changed rows. A changed row has been inserted, updated, or deleted in the rowset.

ALL_ROWS

public static final int ALL_ROWS

XML Document includes all rows with both their changed and original values

Method Detail

populate

public void populate(java.sql.ResultSetMetaData md)
              throws java.sql.SQLException

Loads a ResultSet from an existing java.sql.ResultSetMetaData. This method produces an empty RowSet that can be used to insert new rows.

Throws:

java.sql.SQLException - if there is an error processing the ResultSetMetaData

populate

public void populate(java.sql.ResultSet rs)
              throws java.sql.SQLException

Loads the RowSet with data from an existing java.sql.ResultSet. This method is an alternative to using a SQL query to load the WLCachedRowSet.

Throws:

java.sql.SQLException - if there is an error processing the ResultSet

executeAndGuessTableName

public java.lang.String executeAndGuessTableName()
                                          throws java.sql.SQLException

Executes the command, parses it, and sets the table name as the first word following the SQL keyword "from".

Returns:

Returns the guessed table name or null, if unsuccessful.

Throws:

java.sql.SQLException - if a database access error occurs or any of the properties necessary for making a connection and creating a statement have not been set

executeAndGuessTableNameAndPrimaryKeys

public boolean executeAndGuessTableNameAndPrimaryKeys()
                                               throws java.sql.SQLException

Executes the command, parses it, sets the table name as the first word following the SQL keyword "from", and then looks up the table in DatabaseMetaData to determine the primary keys.

Throws:

java.sql.SQLException - if a database access error occurs or any of the properties necessary for making a connection and creating a statement have not been set

isComplete

public boolean isComplete()

Returns whether the populating query read all matching rows, or it hit the maxRows limit.

When execute is called, it runs the query specified by the setCommand method. The user may optionally specify a maximum number of rows to return from the query with the setMaxRows method.

Returns:

Returns true if the setMaxRows has been set, and the query returned all rows. It also returns true if maxRows has not been set, or the rowset was not populated via the execute method.

Returns false if MaxRows has been set, and the query hit the maxRows limit without returning all matching rows

acceptChanges

public void acceptChanges()
                   throws java.sql.SQLException,
                          OptimisticConflictException

acceptChanges asks the RowSet to write its values back to the underlying database.

If no updates have been made, the WLCachedRowSet does no database writes.

If there is an active global JTA transaction, the updates done in acceptChanges can participate in that transaction. Ensure that you have have specified a transaction-aware DataSource (TxDataSource) for this to occur.

If there is no active global JTA transaction, a local JDBC transaction is used for the updates.

Throws:

java.sql.SQLException - if there is an error while writing to the database

OptimisticConflictException - if an update fails because its data has been updated since it was read into the RowSet. If the acceptChanges runs in a global JTA transaction, the OptimisticConflictException aborts the transaction. If there was no global JTA transaction, the OptimisticConflictException aborts the local transaction.

size

public int size()

Returns the number of rows in the WLCachedRowSet.

This size includes all of the rows which were read during the initial population from the ResultSet, SQL query, or XML. It also includes any rows which have been inserted.

Deleted rows are also included in this size() count. This means offsets or indexes into the rowset are stable even if rows are deleted.

Returns:

the number of rows in the WLCachedRowSet

getCurrentRow

public java.util.Map getCurrentRow()
                            throws java.sql.SQLException

Returns a Map representing the current row in the RowSet.

Like java.sql.ResultSet, a RowSet acts like a cursor or Iterator with next() and previous() methods. This method returns a java.util.Map instance representing the row at the current position.

The returned Map has keys of the column names and values of the column values. The column values may be read with the get(Object key) method and updated with put(Object key, Object value) method. The user must call updateRow() after updating the Map for the RowSet to accept the updated values.

Returns:

a Map representing the current row in the RowSet.

Throws:

java.sql.SQLException - if the current RowSet position is not a valid row

getRow

public java.util.Map getRow(int index)
                     throws java.sql.SQLException

Returns a Map representing the row at the specified index

Parameters:

index - row index into the row set. Valid values are [0 ... row.size() -1]

Returns:

a Map representing the row at the specified index

Throws:

java.sql.SQLException - if the index is not a valid row

getRows

public java.util.Map[] getRows(int startIndex,
                               int endIndex)
                        throws java.sql.SQLException

Returns an array of Maps representing the rows in the rowset from [startIndex...endIndex-1]

Parameters:

startIndex - the starting rowset index

endIndex - the end rowset index

Returns:

an array of Maps representing the Rows in the specified range

Throws:

java.sql.SQLException - if startIndex or endIndex out of bounds or if startIndex > endIndex

getRows

public java.util.Map[] getRows()
                        throws java.sql.SQLException

Returns an array of Maps representing all rows in the rowset

Returns:

an array of Maps representing all rows in the rowset

Throws:

java.sql.SQLException - if there is an error creating the Map array

setDataSource

public void setDataSource(javax.sql.DataSource dataSource)
                   throws java.sql.SQLException

Sets the javax.sql.DataSource used for establishing JDBC Connections. This method is prefered to setDataSourceName when the caller already has a DataSource instance.

Parameters:

javax.sql.DataSource - a DataSource

getDataSource

public javax.sql.DataSource getDataSource()
                                   throws java.sql.SQLException

Returns the current javax.sql.DataSource for this RowSet. If setDataSourceName or setDataSource have been called, a DataSource is returned. If no DataSource has been set, null is returned.

Returns:

javax.sql.DataSource the current DataSource

Throws:

java.sql.SQLException - if the DataSource name given to setDataSourceName cannot be found or is invalid.

loadXML

public void loadXML(XMLInputStream xis)
             throws java.io.IOException,
                    java.sql.SQLException

Populates the RowSet from an XML document in the XMLInputStream.

Parameters:

XMLInputStream - an XMLInputStream containing a XML document with the RowSet data.

writeXML

public void writeXML(XMLOutputStream xos)
              throws java.io.IOException,
                     java.sql.SQLException

Writes the RowSet to the XMLOutputStream as an XML document. This call is equivalent to calling writeXML(XMLOutputStream,ALL_ROWS)

Parameters:

XMLOutputStream - an XMLOutputStream where the RowSet will be written

Throws:

java.io.IOException - if there is an error writing to the XMLOutputStream

java.sql.SQLException - if there is an error retrieving data from the RowSet

writeXML

public void writeXML(XMLOutputStream xos,
                     int rowStates)
              throws java.io.IOException,
                     java.sql.SQLException

Writes the RowSet as an XML document.