com.sun.data.provider
Interface TableDataProvider

All Superinterfaces:

DataProvider

All Known Implementing Classes:

AbstractTableDataProvider, CachedRowSetDataProvider, MethodResultTableDataProvider

public interface TableDataProvider

extends DataProvider

TableDataProvider is a specialized subinterface of DataProvider that provides access to a scrollable set of "rows" of data elements, with each row being identified by a RowKey. Access to the underlying data elements may be done in a random fashion by using the methods defined in this interface, or you can set the cursor row and use the getType(), getValue(), isReadOnly(), and setValue() methods from the base DataProvider interface to access data elements for the cursor row specified by calling setCursorRow(RowKey).

The set of FieldKeys returned by getFieldKeys() MUST be available on every row supported by this TableDataProvider. This implies a rectangular (matrix) dataset.

The set of RowKeys returned by getRowKeys(...) are expected to uniquely represent the rows contained in the underlying data source. The RowKey objects should remain valid as long as the set of rows in the TableDataProvider has not been re-fetched. Once a re-fetch has happened (by whatever means are supplied by specific TableDataProvider implementations), the previously fetched RowKeys may become invalid. Consult the documentation of the specific TableDataProvider implementation for details on the expected valid lifespan of a RowKey.

Most methods throw DataProviderException, which is a generic runtime exception indicating something is amiss in the internal state of the TableDataProvider implementation. Because DPE is a runtime exception, method calls are not required to be wrapped in a try...catch block, but it is advised to check the documentation of the particular TableDataProvider implementation to see what conditions will cause a DataProviderException to be thrown. It is recommended to always wrap calls to this interface in try...catch blocks in case an unforseen error condition arises at runtime.

Author:

Joe Nuxoll, Matthew Bohm

Method Summary

void	addTableCursorListener(TableCursorListener listener) Register a new TableCursorListener to this TableDataProvider instance.
void	addTableDataListener(TableDataListener listener) Register a new TableDataListener to this TableDataProvider instance.
RowKey	appendRow() Appends a new row at the end of the list and returns the row key for the newly appended row.
boolean	canAppendRow() This method is called to test if this TableDataProvider supports the append operation.
boolean	canInsertRow(RowKey beforeRow) This method is called to test if this TableDataProvider supports resizability.
boolean	canRemoveRow(RowKey rowKey) This method is called to test if this TableDataProvider supports the removeRow operation.
boolean	cursorFirst() Move the cursor to the first row in this TableDataProvider.
boolean	cursorLast() Move the cursor to the last row in this TableDataProvider.
boolean	cursorNext() Move the cursor to the row after the current cursor row, unless the cursor is currently at the last row TableDataProvider.
boolean	cursorPrevious() Move the cursor to the row before the current cursor row, unless the cursor is currently at the first row.
RowKey	getCursorRow()
int	getRowCount()
RowKey	getRowKey(java.lang.String rowId) Returns a RowKey for the specified rowId.
RowKey[]	getRowKeys(int count, RowKey afterRow) Returns an array of RowKey objects representing the requested batch of RowKeys.
TableCursorListener[]	getTableCursorListeners()
TableDataListener[]	getTableDataListeners()
java.lang.Object	getValue(FieldKey fieldKey, RowKey rowKey) Return value of the data element referenced by the specified FieldKey and RowKey.
RowKey	insertRow(RowKey beforeRow) Inserts a new row at the specified row.
boolean	isRowAvailable(RowKey rowKey) Returns true if the specified RowKey represents data elements that are supported by this TableDataProvider; otherwise, return false
void	removeRow(RowKey rowKey) Removes the specified row.
void	removeTableCursorListener(TableCursorListener listener) Deregister an existing TableCursorListener from this TableDataProvider instance.
void	removeTableDataListener(TableDataListener listener) Deregister an existing TableDataListener from this TableDataProvider instance.
void	setCursorRow(RowKey rowKey) Sets the cursor to the row represented by the passed RowKey.
void	setValue(FieldKey fieldKey, RowKey rowKey, java.lang.Object value) Sets the value of the data element represented by the specified FieldKey and RowKey to the specified new value.

Methods inherited from interface com.sun.data.provider.DataProvider

addDataListener, getDataListeners, getFieldKey, getFieldKeys, getType, getValue, isReadOnly, removeDataListener, setValue

Method Detail

getRowCount

public int getRowCount()
                throws DataProviderException

Returns:

the number of rows represented by this TableDataProvider if this information is available; otherwise, return -1 (indicating unknown row count)

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning -1. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

getRowKeys

public RowKey[] getRowKeys(int count,
                           RowKey afterRow)
                    throws DataProviderException

Returns an array of RowKey objects representing the requested batch of RowKeys. If null is passed as the afterRow parameter, the returned batch of RowKeys will start with the first one.

Parameters:

count - The desired count of RowKeys to fetch. If this number exceeds the total number of rows available, the return array will contain the available number, and no exception will be thrown. Consider this an optimistic request of the TableDataProvider.

afterRow - The RowKey that represents the last row before the set of desired RowKeys to be returned. Typically, this is the last RowKey from the previously fetched set of RowKeys. If null is passed, the returned set will begin with the first row.

Returns:

An array of RowKey objects representing the requested batch of rows.

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning null or an empty array. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

getRowKey

public RowKey getRowKey(java.lang.String rowId)
                 throws DataProviderException

Returns a RowKey for the specified rowId. This allows a RowKey to be stored off as a simple string, which can be resolved into an instance of a RowKey at a later date.

Parameters:

rowId - The cannoncial string ID of the desired RowKey

Returns:

A RowKey object representing the desired row, or null if the specified rowId does not correspond to a row in this TableDataProvider

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning null. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

isRowAvailable

public boolean isRowAvailable(RowKey rowKey)
                       throws DataProviderException

Returns true if the specified RowKey represents data elements that are supported by this TableDataProvider; otherwise, return false

Parameters:

rowKey - RowKey specifying row to be tested

Returns:

true if the row is available, false if not

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning false. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

getValue

public java.lang.Object getValue(FieldKey fieldKey,
                                 RowKey rowKey)
                          throws DataProviderException

Return value of the data element referenced by the specified FieldKey and RowKey.

Parameters:

fieldKey - FieldKey identifying the data element whose value is to be returned

rowKey - RowKey identifying the data row whose value is to be returned

Returns:

value of the data element referenced by the specified FieldKey and RowKey

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning null. A DPE may also indicate that this FieldKey or RowKey does not represent a data element provided by this TableDataProvider. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

setValue

public void setValue(FieldKey fieldKey,
                     RowKey rowKey,
                     java.lang.Object value)
              throws DataProviderException

Sets the value of the data element represented by the specified FieldKey and RowKey to the specified new value.

Parameters:

fieldKey - FieldKey identifying the data element whose value is to be modified

rowKey - RowKey indentifying the data row whose value is to be modified

value - New value for this data element

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException). A DPE may also indicate that this FieldKey or RowKey does not represent a data element provided by this TableDataProvider. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

canInsertRow

public boolean canInsertRow(RowKey beforeRow)
                     throws DataProviderException

This method is called to test if this TableDataProvider supports resizability. If objects can be inserted and removed from the list, this method should return true. If the data provider is not resizable, this method should return false.

The following methods will only be called if this method returns true:

• insertRow(RowKey beforeRow)
• appendRow()
• removeRow(RowKey rowKey)

Parameters:

beforeRow - The desired location to insert the new row in front of

Returns:

true if the data provider is resizable, or false if not.

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning false. A DPE may also indicate that this RowKey does not represent a row provided by this TableDataProvider. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

See Also:

insertRow(RowKey)

insertRow

public RowKey insertRow(RowKey beforeRow)
                 throws DataProviderException

Inserts a new row at the specified row.

NOTE: The method should only be called after testing the canInsertRow(RowKey beforeRow) to see if this TableDataProvider supports resizing.

Parameters:

beforeRow - The desired location to insert the new row in front of

Returns:

A RowKey representing the address of the newly inserted row

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException). A DPE may also indicate that this RowKey does not represent a row provided by this TableDataProvider. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

See Also:

canInsertRow(RowKey)

canAppendRow

public boolean canAppendRow()
                     throws DataProviderException

This method is called to test if this TableDataProvider supports the append operation. If rows can be appended to the list, this method should return true. If the data provider is not resizable, or cannot support an append operation, this method should return false.

Returns:

true if the data provider supports the append operation, or false if not.

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException). A DPE may also indicate that this RowKey does not represent a row provided by this TableDataProvider. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

See Also:

appendRow()

appendRow

public RowKey appendRow()
                 throws DataProviderException

Appends a new row at the end of the list and returns the row key for the newly appended row.

NOTE: The method should only be called after testing the canAppendRow() method to see if this TableDataProvider supports the append operation.

Returns:

The row key for the newly appended row

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException). Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

See Also:

canAppendRow()

canRemoveRow

public boolean canRemoveRow(RowKey rowKey)
                     throws DataProviderException

This method is called to test if this TableDataProvider supports the removeRow operation. If rows can be removed from the table, this method should return true. If the data provider is does not support removing rows, this method should return false.

Parameters:

rowKey - The desired row to remove

Returns:

true if the data provider supports removing rows, or false if not.

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException). A DPE may also indicate that this RowKey does not represent a row provided by this TableDataProvider. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

See Also:

removeRow(RowKey)

removeRow

public void removeRow(RowKey rowKey)
               throws DataProviderException

Removes the specified row.

NOTE: The method should only be called after testing the canRemoveRow(RowKey) method to see if this TableDataProvider supports removing rows.

Parameters:

rowKey - The desired row key to remove

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException). A DPE may also indicate that this RowKey does not represent a row provided by this TableDataProvider. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

See Also:

canRemoveRow(RowKey)

addTableDataListener

public void addTableDataListener(TableDataListener listener)

Register a new TableDataListener to this TableDataProvider instance.

Parameters:

listener - New TableDataListener to register

removeTableDataListener

public void removeTableDataListener(TableDataListener listener)

Deregister an existing TableDataListener from this TableDataProvider instance.

Parameters:

listener - Old TableDataListener to deregister

getTableDataListeners

public TableDataListener[] getTableDataListeners()

Returns:

An array of the TableDataListeners currently registered on this TableDataProvider. If there are no registered listeners, a zero-length array is returned.

getCursorRow

public RowKey getCursorRow()
                    throws DataProviderException

Returns:

the RowKey of the current cursor row position

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException). Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

setCursorRow

public void setCursorRow(RowKey rowKey)
                  throws TableCursorVetoException

Sets the cursor to the row represented by the passed RowKey.

Parameters:

rowKey - New RowKey to move the cursor to.

Throws:

TableCursorVetoException - if a TableCursorListener decides to veto the cursor navigation

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException). A DPE may also indicate that this RowKey does not represent a row provided by this TableDataProvider. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

cursorFirst

public boolean cursorFirst()
                    throws DataProviderException

Move the cursor to the first row in this TableDataProvider.

Returns:

true if the cursor row was successfully changed; else false

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning false. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

cursorPrevious

public boolean cursorPrevious()
                       throws DataProviderException

Move the cursor to the row before the current cursor row, unless the cursor is currently at the first row.

Returns:

true if the cursor row was successfully changed; else false

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning false. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

cursorNext

public boolean cursorNext()
                   throws DataProviderException

Move the cursor to the row after the current cursor row, unless the cursor is currently at the last row TableDataProvider.

Returns:

true if the cursor row was successfully changed; else false

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning false. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

cursorLast

public boolean cursorLast()
                   throws DataProviderException

Move the cursor to the last row in this TableDataProvider.

Returns:

true if the cursor row was successfully changed; else false

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning false. Consult the documentation of the specific TableDataProvider implementation for details on what exceptions might be wrapped by a DPE.

addTableCursorListener

public void addTableCursorListener(TableCursorListener listener)

Register a new TableCursorListener to this TableDataProvider instance.

Parameters:

listener - New TableCursorListener to register

removeTableCursorListener

public void removeTableCursorListener(TableCursorListener listener)

Deregister an existing TableCursorListener from this TableDataProvider instance.

Parameters:

listener - Old TableCursorListener to deregister

getTableCursorListeners

public TableCursorListener[] getTableCursorListeners()

Returns:

An array of the TableCursorListeners currently registered on this TableDataProvider. If there are no registered listeners, a zero-length array is returned.