com.sun.data.provider
Interface DataProvider

All Known Subinterfaces:

RefreshableDataProvider, TableDataProvider, TransactionalDataProvider

All Known Implementing Classes:

AbstractDataProvider, AbstractTableDataProvider, BasicTransactionalDataProvider, BasicTransactionalTableDataProvider, CachedRowSetDataProvider, MethodResultDataProvider, MethodResultTableDataProvider, ObjectListDataProvider

public interface DataProvider

DataProvider is an interface that describes a single set of data elements, each identified by a FieldKey. Applications may retrieve a list of available FieldKeys supported by a particular DataProvider instance, or acquire a FieldKey for a particular canonical name (whose intrinsic meaning is defined by the particular DataProvider implementation in use). For each supported FieldKey, the corresponding data element's value may be retrieved, and (optionally) modified, or its data type and read-only status may be acquired.

The base DataProvider interface describes access to individual data elements. In addition, specialized subinterfaces are defined for access to multiple data elements.

TableDataProvider provides access to tabular data, with multiple rows each containing data elements corresponding to the same set of FieldKeys.

DataProvider imposes no requirements or limitations related to whether it is legal to access the same DataProvider instance from multiple threads that are operating simultaneously. Thread safety considerations are a feature of particular implementations.

Most methods throw DataProviderException, which is a generic runtime exception indicating something is amiss in the internal state of the DataProvider 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 DataProvider 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

Method Summary

void	addDataListener(DataListener listener) Register a new DataListener to this DataProvider instance.
DataListener[]	getDataListeners()
FieldKey	getFieldKey(java.lang.String fieldId) Returns the FieldKey associated with the specified data element canonical id, if any; otherwise, return null.
FieldKey[]	getFieldKeys()
java.lang.Class	getType(FieldKey fieldKey) Returns the data type of the data element referenced by the specified data key.
java.lang.Object	getValue(FieldKey fieldKey) Returns value of the data element referenced by the specified FieldKey.
boolean	isReadOnly(FieldKey fieldKey) Return a flag indicating whether the value of the data element represented by the specified FieldKey can be modified via the setValue() method.
void	removeDataListener(DataListener listener) Deregister an existing DataListener from this DataProvider instance.
void	setValue(FieldKey fieldKey, java.lang.Object value) Set the value of the data element represented by the specified FieldKey to the specified new value.

Method Detail

getFieldKeys

public FieldKey[] getFieldKeys()
                        throws DataProviderException

Returns:

An array of all FieldKeys supported by this DataProvider. If the set of valid FieldKeys cannot be determined, return null instead.

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 DataProvider implementation for details on what exceptions might be wrapped by a DPE.

getFieldKey

public FieldKey getFieldKey(java.lang.String fieldId)
                     throws DataProviderException

Returns the FieldKey associated with the specified data element canonical id, if any; otherwise, return null.

Parameters:

fieldId - Canonical id of the requested FieldKey

Returns:

the FieldKey associated with the specified data element canonical id, if any; otherwise, return null

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning null. A DPE may also indicate that the passed fieldId is not valid. Consult the documentation of the specific DataProvider implementation for details on what exceptions might be wrapped by a DPE.

getType

public java.lang.Class getType(FieldKey fieldKey)
                        throws DataProviderException

Returns the data type of the data element referenced by the specified data key.

Parameters:

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

Returns:

the data type of the data element referenced by the specified data key

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning null. A DPE may also indicate that the passed fieldKey is not valid. Consult the documentation of the specific DataProvider implementation for details on what exceptions might be wrapped by a DPE.

isReadOnly

public boolean isReadOnly(FieldKey fieldKey)
                   throws DataProviderException

Return a flag indicating whether the value of the data element represented by the specified FieldKey can be modified via the setValue() method.

Parameters:

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

Returns:

a flag indicating whether the value of the data element represented by the specified FieldKey can be modified via the setValue() method

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning true. A DPE may also indicate that the passed fieldKey is not valid. Consult the documentation of the specific DataProvider implementation for details on what exceptions might be wrapped by a DPE.

getValue

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

Returns value of the data element referenced by the specified FieldKey.

Parameters:

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

Returns:

value of the data element referenced by the specified FieldKey

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning null. A DPE may also indicate that the passed fieldKey is not valid. Consult the documentation of the specific DataProvider implementation for details on what exceptions might be wrapped by a DPE.

setValue

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

Set the value of the data element represented by the specified FieldKey to the specified new value.

Parameters:

fieldKey - FieldKey identifying the data element 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) rather than simply returning null. A DPE may also indicate that the passed fieldKey is not valid. Consult the documentation of the specific DataProvider implementation for details on what exceptions might be wrapped by a DPE.

addDataListener

public void addDataListener(DataListener listener)

Register a new DataListener to this DataProvider instance.

Parameters:

listener - New DataListener to register

removeDataListener

public void removeDataListener(DataListener listener)

Deregister an existing DataListener from this DataProvider instance.

Parameters:

listener - Old DataListener to deregister

getDataListeners

public DataListener[] getDataListeners()

Returns:

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