com.im.df.api.dml
Interface DFEntityDataProvider

public interface DFEntityDataProvider

Data provider for a single entity. Data are not cached and are obtained directly from data source. It is recommended to use some caching system on top of this object. If you are interested in data changes, you should register a DFEntityDataListener to this object.

API Status: Partly stable. This class contains a few methods which can be changed/removed in the future. These methods comments contain TODO info.

Method Summary

void	addDFEntityDataListener(DFEntityDataListener listener) Register an listener to be notified about data changes in this entity data provider.
int	deleteIds(List<? extends Comparable<?>> ids, DFEnvironmentRW env) Delete these IDs
String	generateStatistics() Generate a statistical summary of the information in this entity.
Map<Comparable<?>,Map<String,Object>>	getData(List<? extends Comparable<?>> ids, DFEnvironmentRO env) Fetch data for the specified IDs.
DFEntity	getEntity() Get the entity which this EDP belongs to.
DFLockable	getLockable() Get the lock provider only for this EDP.
int	getRowCount(DFEnvironmentRO env) Get the number of rows.
DFSchemaDataProvider	getSchemaDataProvider() Get parent DFSchemaDataProvider.
Map<Comparable<?>,Map<String,Object>>	getWrappedData(List<? extends Comparable<?>> ids, DFEnvironmentRO env)
DFUpdateInfo	insert(Map<String,Object> values, Map<String,Object> insertOptions, DFEnvironmentRW env) Insert a new row with these values.
List<? extends DFRowData>	queryForData(DFTermExpression query, List<? extends DFField> fields, SortDirective sort, DFEnvironmentRO env) Get the values of selected fields of the entity that match the specified query
List<? extends Comparable<?>>	queryForIds(DFDataTree dataTree, DFTermExpression query, SortDirective sort, DFEnvironmentRO env) Get the IDs (primary key values) of the entity that match the specified query
List<? extends Comparable<?>>	queryForIds(DFTermExpression query, SortDirective sort, DFEnvironmentRO env) Get the IDs (primary key values) of the entity that match the specified query
List<? extends Object>	queryForValues(DFTermExpression query, DFField selectedField, SortDirective sort, DFEnvironmentRO env) Get the values of selectedField of the entity that match the specified query
void	reloadData() Reload data for this EDP.
void	removeDFEntityDataListener(DFEntityDataListener listener) Unregister an listener to be notified about data changes in this entity data provider.
List	retrieveDistinctValuesForField(String fieldId) Get the List of distinct values for this field.
List<? extends Comparable<?>>	sortIds(List<? extends Comparable<?>> ids, SortDirective sort, DFEnvironmentRO env) Get these IDs for the entity in sorted order.
Map<DFUpdateDescription,DFUpdateResult>	update(List<DFUpdateDescription> updateDescriptors, DFUndoConfig undoConfig, DFEnvironmentRW env) Update the data where certain value match the defined criteria.
Map<DFUpdateDescription,DFUpdateResult>	update(List<DFUpdateDescription> updateDescriptors, DFUndoConfig undoConfig, DFEnvironmentRW env, boolean fireEvents) The same as update(List, DFUndoConfig, DFEnvironmentRW) with the possibility to turn off the firing of events.

Method Detail

getLockable

DFLockable getLockable()

Get the lock provider only for this EDP. You must lock the EDP before calling data modification methods.

getSchemaDataProvider

DFSchemaDataProvider getSchemaDataProvider()

Get parent DFSchemaDataProvider.

getEntity

DFEntity getEntity()

Get the entity which this EDP belongs to.

getRowCount

int getRowCount(DFEnvironmentRO env)

Get the number of rows.

queryForIds

List<? extends Comparable<?>> queryForIds(DFTermExpression query,
                                          SortDirective sort,
                                          DFEnvironmentRO env)

Get the IDs (primary key values) of the entity that match the specified query

Parameters:

query - The query All elements must be present in this entity, for empty query use DFTermExpression.ALL_DATA constant.

sort - The sort directive describing how returned data should be sorted

Returns:

The values of the ID field of the entity that match the query

queryForValues

List<? extends Object> queryForValues(DFTermExpression query,
                                      DFField selectedField,
                                      SortDirective sort,
                                      DFEnvironmentRO env)

Get the values of selectedField of the entity that match the specified query

Parameters:

query - The query All elements must be present in this entity, for empty query use DFTermExpression.ALL_DATA constant.

selectedField - specify field which values are returned (target)

sort - The sort directive describing how returned data should be sorted

Returns:

The values of the selectedField field of the entity that match the query

queryForData

List<? extends DFRowData> queryForData(DFTermExpression query,
                                       List<? extends DFField> fields,
                                       SortDirective sort,
                                       DFEnvironmentRO env)

Get the values of selected fields of the entity that match the specified query

Parameters:

query - The query All elements must be present in this entity, for empty query use DFTermExpression.ALL_DATA constant.

fields - specify fields which values are returned (target)

sort - The sort directive describing how returned data should be sorted

Returns:

The values of the fields of the entity that match the query. Each list item contains data for a single database row. Each row is represented as Map where keys are ids of selected fields and values are real data values.

queryForIds

List<? extends Comparable<?>> queryForIds(DFDataTree dataTree,
                                          DFTermExpression query,
                                          SortDirective sort,
                                          DFEnvironmentRO env)

Get the IDs (primary key values) of the entity that match the specified query

Parameters:

dataTree - The DataTree that allows the different fields to be resolved to formulate the query

query - The query Elements can be from other entities in the DataTree, for empty query use DFTermExpression.ALL_DATA constant.

sort - The sort directives

env -

Returns:

The values of the ID field of the entity that match the query

sortIds

List<? extends Comparable<?>> sortIds(List<? extends Comparable<?>> ids,
                                      SortDirective sort,
                                      DFEnvironmentRO env)

Get these IDs for the entity in sorted order. The implementation can decide if it is faster to leave database to sort them or sort them inside DIF implementation.

Parameters:

ids - The required IDs

Returns:

The values of the ID field of the entity in sorted order

getData

Map<Comparable<?>,Map<String,Object>> getData(List<? extends Comparable<?>> ids,
                                              DFEnvironmentRO env)

Fetch data for the specified IDs.

Parameters:

ids - The IDs

Returns:

A map of the data, keyed by the row ID. The values of the first level of Map are instances of Map again. In these nested Maps key is DFField's Id and value is the read data value. Nested Maps contain data for each DFField.

getWrappedData

Map<Comparable<?>,Map<String,Object>> getWrappedData(List<? extends Comparable<?>> ids,
                                                     DFEnvironmentRO env)

insert

DFUpdateInfo insert(Map<String,Object> values,
                    Map<String,Object> insertOptions,
                    DFEnvironmentRW env)

Insert a new row with these values.

TODO P2 - getInsertOptions methods doesn't exist and currently only usage (in Import) is a hack to API. The architecture and API for insert options should be improved.

Parameters:

values - A Map of DFField's Id/value pairs

insertOptions - Options specific to this type of entity. Can be null.

Returns:

Update info - id of inserted row and if it's duplicate

deleteIds

int deleteIds(List<? extends Comparable<?>> ids,
              DFEnvironmentRW env)

Delete these IDs

Parameters:

ids - The IDs to delete

env -

Returns:

The number of IDs that were deleted. If not known then -1.

update

Map<DFUpdateDescription,DFUpdateResult> update(List<DFUpdateDescription> updateDescriptors,
                                               DFUndoConfig undoConfig,
                                               DFEnvironmentRW env)

Update the data where certain value match the defined criteria. To recognize if the method was successful you need to check DFUpdateResult.isSuccessful() method of each DFUpdateResult.

However you can update any number of rows in a single call of this method.you should rather balance it. For example if you want to update 1000000 rows and you will call this method once for each row then the performance won't be good. On the other hand if you call it only once with List of 1000000 prepared DFUpdateDescriptions it will require too much memory as whole change must be allocated and is released after operation finishes.

It's recommended that you choose some option in the middle of these two extremes. For this reason there is defined a constant which says what is the recommended size of update batch: DIFUtilities.UPDATE_DESCRIPTORS_RECOMMENDED_LIMIT. Then the code can look something like (it's simplified - it doesn't solve the returned results):

 DFEntityDataProvider edp = ....;
 List updateDescriptors = new ArrayList();
 for (int i = 0; i < rowCount; i++) {
     updateDescriptors.add(DFUpdateDescriptor.create(...));
     if ((updateDescriptors.size() > DIFUtilities.UPDATE_DESCRIPTORS_RECOMMENDED_LIMIT) || (i == rowCount - 1)) {
         Map result = edp.update(updateDescriptors,...);
         updateDescriptors.clear();
         // check results and possibly break loop if there are any errors?
     }
 }
 

There is a utility which can help with writing this code: BatchUpdater.

Parameters:

updateDescriptors - The list of descriptors what to update

env -

undoConfig - The description if and how to use undo/redo support

Returns:

The map of results of the update operation. Each provided updateDescriptors should have its own result in this Map.

update

Map<DFUpdateDescription,DFUpdateResult> update(List<DFUpdateDescription> updateDescriptors,
                                               DFUndoConfig undoConfig,
                                               DFEnvironmentRW env,
                                               boolean fireEvents)

The same as update(List, DFUndoConfig, DFEnvironmentRW) with the possibility to turn off the firing of events.

reloadData

void reloadData()

Reload data for this EDP. This method fires event that all data changed. It works currently only for changed data, but not when some row is deleted!!

TODO: This method may change in the future (perhaps DFEnvironmentRW will be added as parameter).

addDFEntityDataListener

void addDFEntityDataListener(DFEntityDataListener listener)

Register an listener to be notified about data changes in this entity data provider. Preferred way is to use weak listener to prevent memory leaks.

removeDFEntityDataListener

void removeDFEntityDataListener(DFEntityDataListener listener)

Unregister an listener to be notified about data changes in this entity data provider.

retrieveDistinctValuesForField

List retrieveDistinctValuesForField(String fieldId)

Get the List of distinct values for this field.

TODO P3 - this method should probably have DFEnvironmentRO as parameter (it can take some time and 2nd reason - it should be cancellable if someone misuses "distinct values" e.g. for some field with many values in 1000000 rows table).

generateStatistics

String generateStatistics()

Generate a statistical summary of the information in this entity. The returned value is expected to be a human readable string so can be presented in UI.