com.sun.sql.rowset
Interface CachedRowSetX

All Superinterfaces:

CachedRowSet, Joinable, java.sql.ResultSet, javax.sql.RowSet

All Known Implementing Classes:

CachedRowSetXImpl

public interface CachedRowSetX

extends CachedRowSet

The extened interface that all implementations of CachedRowSetX must implement.

1.0 Overview

An extension to the CachedRowSet interface.

A CachedRowSetX object differs from a CachedRowSet object in the following ways:

• An isExecuted() method will return true if the CachedRowSetX is in a state where navigation and getters and setters can be called on rows returned from the database (i.e., returns true if execute or populate has been called.
• The following "advanced" properties have been added. These properties are useful in the case of incomplete or incorrect information being supplied by JDBC drivers.
  Note: In most cases, these advanced properties do not need to be set (i.e., they can be left set to their default null value (or false in the case of printStatements). For the cases where the advanced properties must be used, it is helpful to set the printStatements property to true first. In that way, one can then determine what advanced properties must be set. By setting the catalog and schema for the table to be upadted and by explicitly setting cataloag, table, schema and column names for each column, one can explicitly set what columns will participate in inserts, updates and deletes. Futher control can be gained by setting the updatableColumns and insertableColumns properties. Note: if updatableColumns is set and insertableColumns is not set, it is assumed that updateableColumns applies to both updates and inserts.
  • catalogName: the name of the catalog that contains the table referred to by tableName
  • schemaName: the name of the schema that contains the table referred to by tableName
  • columnCatalogNames: an array of String, one for each column, which contains the name of catalog of the corresponding column (each element can also be null
  • columnSchemaNames: an array of String, one for each column, which contains the name of the schema of the corresponding column (each element can also be null
  • columnTableNames: an array of String, one for each column, which contains the name of the table of the corresponding column (each element can also be null
  • columnNames: an array of String, one for each column, which contains the name of the corresponding column (each element can also be null
  • insertableColumns: an array of boolean, one for each column, which contains true if the corresponding column can be inserted, else it contains false/code>
  • updatableColumns: an array of boolean, one for each column, which contains true if the corresponding column can be updated, else it contains false/code>
  • printStatements: a boolean{/code> that when true will result in internally generated INSERT, UPDATE, and DELETE SQL statements being written to System.out. This output is useful in determining why inserts,updates and/or deletes are falling and in deciding what advanced properties to set in order to address the problems.
• PropertyChangeListener support
  The following are bound properties:
  • command
  • dataSourceName
  • maxRows
  • password
  • type
  • url
  • username
• support to use the CachedRowSetX after calling close on it.
• by default, a CachedRowSetX's properties are set to:
  • command: null
  • escapeProcessing: true
  • keyColumns: null
  (ignored)
  • maxFieldSize: 0
  • maxRows: 0
  • password: null
  • readOnly: true (ignored)
  • showDeleted: false
  • typeMap: null
  • url: null
  • username: null
• the readOnly property is currently not used
• it is well defined how property changes affect the state of a CachedRowSetX
  • autoCommit: nothing is invalidated
  • command: release() is called
  • concurrency: nohting is invalidated
  • escapeProcessing: nothing is invalidated
  • maxFieldSize: nothing is invalidated
  • maxRows: nothing is invalidated
  • password: nothing is invalidated
  • readOnly: nothing is invalidated
  • showDeleted: nothing is invalidated
  • transactionIsolation: nothing is invalidated
  • type: nothing is invalidated
  • typeMap: nothing is invalidated
  • url: release() is called
  • username: release() is called
• calling close will never throw a SQLException

Field Summary

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

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Add a PropertyChangeListener to the listener list.
void	addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Add a PropertyChangeListener for a specific property.
java.lang.String	getCatalogName() Returns the catalog in which the table referred to by the tableName property resides.
java.lang.String[]	getColumnCatalogNames() Returns an array of String.
java.lang.String	getColumnCatalogNames(int index) Returns a String which contains the catalog name set for the column or null.
java.lang.String[]	getColumnNames() Returns an array of String.
java.lang.String	getColumnNames(int index) Returns a String which contains the column name set for the column or null.
java.lang.String[]	getColumnSchemaNames() Returns an array of String.
java.lang.String	getColumnSchemaNames(int index) Returns a String which contains the schema name set for the column or null.
java.lang.String[]	getColumnTableNames() Returns an array of String.
java.lang.String	getColumnTableNames(int index) Returns a String which contains the table name set for the column or null.
boolean[]	getInsertableColumns() Returns an array of boolean{/code>.
boolean	getInsertableColumns(int index) Returns a boolean{/code> of true if the column should be inserted when when adding rows or null.
boolean	getPrintStatements() Returns the printStatements property.
java.lang.String	getSchemaName() Returns the schema in which the table referred to by the tableName property resides.
boolean[]	getUpdatableColumns() Returns an array of boolean{/code>.
boolean	getUpdatableColumns(int index) Returns a boolean{/code> of true if the column should be updated when when updating rows or null.
boolean	isExecuted() Returns true if this rowset is in an executed state
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Remove a PropertyChangeListener from the listener list.
void	removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Remove a PropertyChangeListener for a specific property.
void	setCatalogName(java.lang.String catalogName) Sets the identifier for catalog of the table referred to in the tableName property.
void	setColumnCatalogNames(int index, java.lang.String columnCatalogName) Set the columnCatalogNames property.
void	setColumnCatalogNames(java.lang.String[] columnCatalogNames) Set the columnCatalogNames property.
void	setColumnNames(int index, java.lang.String columnName) Set the columnNames property.
void	setColumnNames(java.lang.String[] columnNames) Set the columnNames property.
void	setColumnSchemaNames(int index, java.lang.String columnSchemaName) Set the columnSchemaNames property.
void	setColumnSchemaNames(java.lang.String[] columnSchemaNames) Set the columnSchemaNames property.
void	setColumnTableNames(int index, java.lang.String columnTableName) Set the columnTableNames property.
void	setColumnTableNames(java.lang.String[] columnTableNames) Set the columnTableNames property.
void	setInsertableColumns(boolean[] insertableColumns) Set the insertableColumns property.
void	setInsertableColumns(int index, boolean insertableColumn) Set the insertableColumns property.
void	setPrintStatements(boolean printStatements) Sets the printStatements property.
void	setSchemaName(java.lang.String schemaName) Sets the identifier for schema of the table referred to in the tableName property.
void	setUpdatableColumns(boolean[] updatableColumns) Set the updatableColumns property.
void	setUpdatableColumns(int index, boolean updatableColumn) Set the updatableColumns property.

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, 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

Methods inherited from interface javax.sql.rowset.Joinable

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

Method Detail

isExecuted

public boolean isExecuted()
                   throws java.sql.SQLException

Returns true if this rowset is in an executed state

Returns:

a boolean true if the CachedRowSetX is in a state where navigation and getters and setters can be called on rows returned from the database (i.e., returns true if execute() or populate has been called.

Throws:

java.sql.SQLException - if a database access error occurs

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Add a PropertyChangeListener to the listener list. The listener is registered for all bound properties.

Parameters:

listener - The PropertyChangeListener to be added

getCatalogName

public java.lang.String getCatalogName()

Returns the catalog in which the table referred to by the tableName property resides.

Returns:

a String object giving the name of the catalog that contains the table referred to by tableName

Note: This method is called by com.sun.sql.rowset.internal.CachedRowSetXWriter.

See Also:

ResultSetMetaData.getCatalogName(int)

setCatalogName

public void setCatalogName(java.lang.String catalogName)

Sets the identifier for catalog of the table referred to in the tableName property. The writer uses this name to determine which table to use when comparing the values in the data source with the CachedRowSetX object's values during a synchronization attempt. The catalogName property also indicates where modified values from this CachedRowSetX object should be written.

The implementation of this CachedRowSetX object may obtain the the name internally from the RowSetMetaDataXImpl object.

Note: This method is called by com.sun.sql.rowset.internal.CachedRowSetXWriter.

Parameters:

catalogName - a String object identifying the catalog of the table from which this CachedRowSetX object was derived; can be null or an empty String

See Also:

RowSetMetaData.setCatalogName(int, java.lang.String), RowSetWriter, javax.sql.rowset.spi.SyncProviderX

getSchemaName

public java.lang.String getSchemaName()

Returns the schema in which the table referred to by the tableName property resides.

Returns:

a String object giving the name of the catalog that contains the table referred to by tableName

Note: This method is called by com.sun.sql.rowset.internal.CachedRowSetXWriter.

See Also:

ResultSetMetaData.getCatalogName(int)

setSchemaName

public void setSchemaName(java.lang.String schemaName)

Sets the identifier for schema of the table referred to in the tableName property. The writer uses this name to determine which table to use when comparing the values in the data source with the CachedRowSetX object's values during a synchronization attempt. The schemaName property also indicates where modified values from this CachedRowSetX object should be written.

The implementation of this CachedRowSetX object may obtain the the name internally from the RowSetMetaDataXImpl object.

Parameters:

schemaName - a String object identifying the schema of the table from which this CachedRowSetX object was derived; can be null or an empty String

See Also:

RowSetMetaData.setSchemaName(int, java.lang.String), RowSetWriter, javax.sql.rowset.spi.SyncProviderX

getColumnCatalogNames

public java.lang.String[] getColumnCatalogNames()

Returns an array of String. If setColumnCatalogNames was never called, null is returned, else the value set when calling setColumnCatalogNames{/code> is returned. See setColumnCatalogNames for details.

Note, the column is zero based whereas most jdbc calls are one based.

Note: This method is called by com.sun.sql.rowset.internal.CachedRowSetXWriter.

Returns:

an array of String objects or null

getColumnCatalogNames

public java.lang.String getColumnCatalogNames(int index)

Returns a String which contains the catalog name set for the column or null.

Note, the column is zero based whereas most jdbc calls are one based.

Returns:

a String object or null

Throws:

java.lang.NullPointerException - if columnCatalogNames was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= columnCatalogName.length

setColumnCatalogNames

public void setColumnCatalogNames(java.lang.String[] columnCatalogNames)

Set the columnCatalogNames property.

Parameters:

columnCatalogNames - an array of String, one for each column, which contains the name of catalog of the corresponding column (each element can also be null

Note, the column is zero based whereas most jdbc calls are one based.

setColumnCatalogNames

public void setColumnCatalogNames(int index,
                                  java.lang.String columnCatalogName)

Set the columnCatalogNames property.

Parameters:

index - the index of the array to set (zero based)

columnCatalogName - the name of catalog for the column (can also be null

Throws:

java.lang.NullPointerException - if columnCatalogNames was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= columnCatalogName.length

Note, the column is zero based whereas most jdbc calls are one based.

getColumnSchemaNames

public java.lang.String[] getColumnSchemaNames()

Returns an array of String. If setColumnSchemaNames was never called, null is returned, else the value set when calling setColumnSchemaNames{/code> is returned. See setColumnSchemaNames for details.

Note, the column is zero based whereas most jdbc calls are one based.

Note: This method is called by com.sun.sql.rowset.internal.CachedRowSetXWriter.

Returns:

an array of String objects or null

getColumnSchemaNames

public java.lang.String getColumnSchemaNames(int index)

Returns a String which contains the schema name set for the column or null.

Note, the column is zero based whereas most jdbc calls are one based.

Returns:

a String object or null

Throws:

java.lang.NullPointerException - if columnSchemaNames was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= columnSchemaName.length

setColumnSchemaNames

public void setColumnSchemaNames(java.lang.String[] columnSchemaNames)

Set the columnSchemaNames property.

Parameters:

columnSchemaNames - an array of String, one for each column, which contains the name of schema of the corresponding column (each element can also be null

Note, the column is zero based whereas most jdbc calls are one based.

setColumnSchemaNames

public void setColumnSchemaNames(int index,
                                 java.lang.String columnSchemaName)

Set the columnSchemaNames property.

Parameters:

index - the index of the array to set (zero based)

columnSchemaName - the name of schema for the column (can also be null

Throws:

java.lang.NullPointerException - if columnSchemaNames was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= columnSchemaName.length

Note, the column is zero based whereas most jdbc calls are one based.

getColumnTableNames

public java.lang.String[] getColumnTableNames()

Returns an array of String. If setColumnTableNames was never called, null is returned, else the value set when calling setColumnTableNames{/code> is returned. See setColumnTableNames for details.

Note, the column is zero based whereas most jdbc calls are one based.

Note: This method is called by com.sun.sql.rowset.internal.CachedRowSetXWriter.

Returns:

an array of String objects or null

getColumnTableNames

public java.lang.String getColumnTableNames(int index)

Returns a String which contains the table name set for the column or null.

Note, the column is zero based whereas most jdbc calls are one based.

Returns:

a String object or null

Throws:

java.lang.NullPointerException - if columnTableNames was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= columnTableName.length

setColumnTableNames

public void setColumnTableNames(java.lang.String[] columnTableNames)

Set the columnTableNames property.

Parameters:

columnTableNames - an array of String, one for each column, which contains the name of table of the corresponding column (each element can also be null

Note, the column is zero based whereas most jdbc calls are one based.

setColumnTableNames

public void setColumnTableNames(int index,
                                java.lang.String columnTableName)

Set the columnTableNames property.

Parameters:

index - the index of the array to set (zero based)

columnTableName - the name of table for the column (can also be null

Throws:

java.lang.NullPointerException - if columnTableNames was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= columnTableName.length

Note, the column is zero based whereas most jdbc calls are one based.

getColumnNames

public java.lang.String[] getColumnNames()

Returns an array of String. If setColumnNames was never called, null is returned, else the value set when calling setColumnNames{/code> is returned. See setColumnNames for details.

Note, the column is zero based whereas most jdbc calls are one based.

Note: This method is called by com.sun.sql.rowset.internal.CachedRowSetXWriter.

Returns:

an array of String objects or null

getColumnNames

public java.lang.String getColumnNames(int index)

Returns a String which contains the column name set for the column or null.

Note, the column is zero based whereas most jdbc calls are one based.

Returns:

a String object or null

Throws:

java.lang.NullPointerException - if columnNames was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= columnName.length

setColumnNames

public void setColumnNames(java.lang.String[] columnNames)

Set the columnNames property.

Parameters:

columnNames - an array of String, one for each column, which contains the name of column (each element can also be null

Note, the column is zero based whereas most jdbc calls are one based.

setColumnNames

public void setColumnNames(int index,
                           java.lang.String columnName)

Set the columnNames property.

Parameters:

index - the index of the array to set (zero based)

columnName - for the column (can also be null

Throws:

java.lang.NullPointerException - if columnNames was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= columnName.length

Note, the column is zero based whereas most jdbc calls are one based.

getInsertableColumns

public boolean[] getInsertableColumns()

Returns an array of boolean{/code>. If setInsertableColumns was never called, null is returned, else the value set when calling setInsertableColumns{/code> is returned. See setInsertableColumns for details.

Note, the column is zero based whereas most jdbc calls are one based.

Note: This method is called by com.sun.sql.rowset.internal.CachedRowSetXWriter.

Returns:

an array of boolean{/code> objects or null

getInsertableColumns

public boolean getInsertableColumns(int index)

Returns a boolean{/code> of true if the column should be inserted when when adding rows or null.

Note, the column is zero based whereas most jdbc calls are one based.

Returns:

a boolean/code> object or null

Throws:

java.lang.NullPointerException - if insertableColumns was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= insertableColumns.length

setInsertableColumns

public void setInsertableColumns(boolean[] insertableColumns)

Set the insertableColumns property.

Parameters:

insertableColumns - an array of boolean one for each column, which contains a boolean indicating whether or not the column should be inserted when adding rows to the CachedRowSetX

Note, the column is zero based whereas most jdbc calls are one based.

setInsertableColumns

public void setInsertableColumns(int index,
                                 boolean insertableColumn)

Set the insertableColumns property.

Parameters:

index - the index of the array to set (zero based)

insertableColumn - true if column should be inserted for new rows

Throws:

java.lang.NullPointerException - if insertableColumns was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= insertableColumns.length

Note, the column is zero based whereas most jdbc calls are one based.

getUpdatableColumns

public boolean[] getUpdatableColumns()

Returns an array of boolean{/code>. If setUpdatableColumns was never called, null is returned, else the value set when calling setUpdatebleColumns{/code> is returned. See setUpdatableColumns for details.

Note, the column is zero based whereas most jdbc calls are one based.

Note: This method is called by com.sun.sql.rowset.internal.CachedRowSetXWriter.

Returns:

an array of boolean{/code> objects or null

getUpdatableColumns

public boolean getUpdatableColumns(int index)

Returns a boolean{/code> of true if the column should be updated when when updating rows or null.

Note, the column is zero based whereas most jdbc calls are one based.

Returns:

a boolean{/code> object or null

Throws:

java.lang.NullPointerException - if updatableColumns was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= updatableColumns.length

setUpdatableColumns

public void setUpdatableColumns(boolean[] updatableColumns)

Set the updatableColumns property.

Parameters:

updatableColumns - an array of boolean, one for each column, which contains a boolean indicating whether or not the column should be updated when updating rows to the CachedRowSetX

Note, the column is zero based whereas most jdbc calls are one based.

setUpdatableColumns

public void setUpdatableColumns(int index,
                                boolean updatableColumn)

Set the updatableColumns property.

Parameters:

index - the index of the array to set (zero based)

updatableColumn - true if column should be updated when rows are updated

Throws:

java.lang.NullPointerException - if updatableColumns was never set.

java.lang.ArrayIndexOutOfBoundsException - if index is >= updatableColumns.length

Note, the column is zero based whereas most jdbc calls are one based.

getPrintStatements

public boolean getPrintStatements()

Returns the printStatements property.

Returns:

a boolean{/code> object which, if true, causes SQL statements to be written to System.out.

Note: This method is called by com.sun.sql.rowset.internal.CachedRowSetXWriter.

setPrintStatements

public void setPrintStatements(boolean printStatements)

Sets the printStatements property. If this property is true, SQL Insert, UPDATE and DELETE statements will be written to System.out. This property is intended to be set when debugging problems inserting, updating and deleting. With the information gained from examining the output, it is intended that one can set the other advanced properties on the CachedRowSetX to "fix" the SQL statements being generated. In this way, some JDBC driver problems can be overcome.

Parameters:

printStatements - a boolean{/code> object which determines whether SQL Insert, UPDATE and DELETE statements are written to System.out

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String propertyName,
                                      java.beans.PropertyChangeListener listener)

Add a PropertyChangeListener for a specific property. The listener will be invoked only on a change of the specific property.

Parameters:

propertyName - The name of the property to listen on.

listener - The PropertyChangeListener to be added

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Remove a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all bound properties.

Parameters:

listener - The PropertyChangeListener to be removed

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String propertyName,
                                         java.beans.PropertyChangeListener listener)

Remove a PropertyChangeListener for a specific property.

Parameters:

propertyName - The name of the property that was listened on.

listener - The PropertyChangeListener to be removed