Package com.im.df.api.dml

Interface DFEntityDataProvider

  • public interface DFEntityDataProvider
    Data manager for a single entity. It provides CRUD operations, i.e. methods for inserting, querying, updating and deleting data from the managed entity together with some other supplemental methods.

    Queried data might be cached or might be always obtained directly from a data source. Concrete strategy is up to particular implementations.

    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 Detail

      • getLockable

        com.im.commons.progress.DFLockable getLockable()
        Gets the lock provider only for this EDP. You must lock the EDP before calling data modification methods.
        Returns:
        lockable for this EDP.

      • getSchemaDataProvider

        DFSchemaDataProvider getSchemaDataProvider()
        Gets parent DFSchemaDataProvider.
        Returns:
        schema data provider.

      • getEntity

        DFEntity getEntity()
        Gets the entity which this EDP belongs to.
        Returns:
        entity which this EDP belongs to

      • getRowCount

        int getRowCount​(com.im.commons.progress.DFEnvironmentRO env)
        Gets the number of rows.
        Parameters:
        env - read only environment
        Returns:
        number of rows.

      • queryForIds

        java.util.List<? extends java.lang.Comparable<?>> queryForIds​(DFTermExpression query,
                                                              SortDirective sort,
                                                              com.im.commons.progress.DFEnvironmentRO env)
        Gets the IDs (primary key values) of the entity that match the specified query. If interested in early Results from ongoing query, please use queryForIds(DFTermExpression, SortDirective, EarlyResultsConsumer, DFEnvironmentRO)
        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
        env - environment for reading data
        Returns:
        The values of the ID field of the entity that match the query
        Since:
        15.12.14 throws QueryExecutionException when there is something wrong with data retrieval. Before that such problems were only logged and swallowed.

      • queryForIds

        java.util.List<? extends java.lang.Comparable<?>> queryForIds​(DFTermExpression query,
                                                              SortDirective sort,
                                                              EarlyResultsConsumer consumer,
                                                              com.im.commons.progress.DFEnvironmentRO env)
        Gets the IDs (primary key values) of the entity that match the specified query. You can also provide an instance of EarlyResultsConsumer which allows you to read partial results already during a query execution.
        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
        consumer - Early results consumer provided by caller used by query engine to call back partial results. If it's null then no partial results are reported back.
        env - environment for reading data
        Returns:
        The values of the ID field of the entity that match the query
        Since:
        15.12.14 throws QueryExecutionException when there is something wrong with data retrieval. Before that such problems were only logged and swallowed.

      • queryForValues

        java.util.List<? extends java.lang.Object> queryForValues​(DFTermExpression query,
                                                          DFField selectedField,
                                                          SortDirective sort,
                                                          com.im.commons.progress.DFEnvironmentRO env)
        Gets 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
        env - environment for reading data
        Returns:
        The values of the selectedField field of the entity that match the query

      • queryForData

        @Deprecated
java.util.List<? extends DFRowData> queryForData​(DFTermExpression query,
                                                 java.util.List<? extends DFField> fields,
                                                 SortDirective sort,
                                                 EarlyResultsConsumer consumer,
                                                 boolean filterOutNulls,
                                                 com.im.commons.progress.DFEnvironmentRO env)
        Deprecated.
        since 14.8.18 use the variant without filterOutNulls, the parameter filterOutNulls is ignored since 14.8.18 and the method always behaves as if filterOutNulls = true. The only difference using filterOutNulls = false could make was that this method could bring one more row. Querying WHERE id = NULL doesn't generally make sense and the previous implementation would return at most one row for all nulls anyway.
        Gets the values of selected fields of the entity that match the specified query. You can also provide an instance of EarlyResultsConsumer which allows you to read partial results already during a query execution.
        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
        consumer - Early results consumer provided by caller used by query engine to call back partial results. If it's null then no partial results are reported back.
        env - environment for reading data
        filterOutNulls - Whether to filter null ids. This parameter is now ignored and ids are filtered.
        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.
        See Also:
        queryForData(DFTermExpression, List, SortDirective, EarlyResultsConsumer, DFEnvironmentRO)

      • queryForData

        java.util.List<? extends DFRowData> queryForData​(DFTermExpression query,
                                                 java.util.List<? extends DFField> fields,
                                                 SortDirective sort,
                                                 EarlyResultsConsumer consumer,
                                                 com.im.commons.progress.DFEnvironmentRO env)
        Gets the values of selected fields of the entity that match the specified query. You can also provide an instance of EarlyResultsConsumer which allows you to read partial results already during a query execution.
        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
        consumer - Early results consumer provided by caller used by query engine to call back partial results. If it's null then no partial results are reported back.
        env - environment for reading data
        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.

      • sortIds

        java.util.List<? extends java.lang.Comparable<?>> sortIds​(java.util.List<? extends java.lang.Comparable<?>> ids,
                                                          SortDirective sort,
                                                          com.im.commons.progress.DFEnvironmentRO env)
        Gets 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
        sort - The sort directive describing how returned data should be sorted
        env - environment for reading data
        Returns:
        The values of the ID field of the entity in sorted order

      • getData

        @Deprecated
java.util.Map<java.lang.Comparable<?>,​java.util.Map<java.lang.String,​java.lang.Object>> getData​(java.util.List<? extends java.lang.Comparable<?>> ids,
                                                                                                            com.im.commons.progress.DFEnvironmentRO env)
        Deprecated.
        getData(List, Set, DFEnvironmentRO) is replacement for this method
        Fetches data for the specified IDs.
        Parameters:
        ids - the IDs
        env - environment for reading data
        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 id of DFField and value is the read data value. Nested Maps contain only data for each DFField specified in fields parameter.

      • getData

        java.util.Map<java.lang.Comparable<?>,​java.util.Map<java.lang.String,​java.lang.Object>> getData​(java.util.List<? extends java.lang.Comparable<?>> ids,
                                                                                                            java.util.Set<? extends DFField> fields,
                                                                                                            com.im.commons.progress.DFEnvironmentRO env)
        Fetches data for the specified IDs.
        Parameters:
        ids - the IDs
        fields - set of fields to retrieve the values from. If null or empty all fields of the entity are retrieved
        env - environment for reading data
        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 id of DFField and value is the read data value. Nested Maps contain only data for each DFField specified in fields parameter.
        Since:
        5.12

      • getWrappedData

        java.util.Map<java.lang.Comparable<?>,​java.util.Map<java.lang.String,​java.lang.Object>> getWrappedData​(java.util.List<? extends java.lang.Comparable<?>> ids,
                                                                                                                   com.im.commons.progress.DFEnvironmentRO env)
        Fetches data for the specified IDs. Values which needs time consuming calculation are wrapped to DFWrappedValue.
        Parameters:
        ids - The IDs
        env - environment for reading data
        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.

      • insert

        DFUpdateInfo insert​(java.util.Map<java.lang.String,​java.lang.Object> values,
                    java.util.Map<java.lang.String,​java.lang.Object> insertOptions,
                    com.im.commons.progress.DFEnvironmentRW env)
        Inserts 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.
        env - environment for writing data
        Returns:
        Update info - id of inserted row and if it's duplicate

      • insert

        java.util.List<DFUpdateInfo> insert​(java.util.List<java.util.Map<java.lang.String,​java.lang.Object>> values,
                                    java.util.Map<java.lang.String,​java.lang.Object> insertOptions,
                                    com.im.commons.progress.DFEnvironmentRW env)
        Insert multiple new rows with these values.
        Parameters:
        values - list of fieldId/value pairs
        insertOptions - options specific to this type of entity. Can be null.
        env - environment for writing data
        Returns:
        list of update info

      • deleteIds

        int deleteIds​(java.util.List<? extends java.lang.Comparable<?>> ids,
              com.im.commons.progress.DFEnvironmentRW env)
        Deletes these IDs.
        Parameters:
        ids - The IDs to delete
        env - environment for writing data
        Returns:
        The number of IDs that were deleted. If not known then -1.

      • update

        java.util.Map<DFUpdateDescription,​DFUpdateResult> update​(java.util.List<DFUpdateDescription> updateDescriptions,
                                                               DFUndoManager undoManager,
                                                               java.lang.String undoMsg,
                                                               com.im.commons.progress.DFEnvironmentRW env)
        Updates 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<DFUpdateDescription> updateDescriptions = new ArrayList<DFUpdateDescription>();
 for (int i = 0; i < rowCount; i++) {
     updateDescriptions.add(DFUpdateDescription.create(...));
     if ((updateDescriptions.size() > DIFUtilities.UPDATE_DESCRIPTORS_RECOMMENDED_LIMIT) || (i == rowCount - 1)) {
         Map<DFUpdateDescription, DFUpdateResult> result = edp.update(updateDescriptions,...);
         updateDescriptions.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:
        updateDescriptions - The list of descriptions what to update
        env - environment for writing data
        undoManager - undo/redo support
        undoMsg - label of undoable edit
        Returns:
        The map of results of the update operation. Each provided updateDescription should have its own result in this Map.
        Since:
        20.12.0

      • reloadData

        void reloadData()
        Reloads 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)
        Registers an listener to be notified about data changes in this entity data provider. Preferred way is to use weak listener to prevent memory leaks.
        Parameters:
        listener - listener for data modification

      • removeDFEntityDataListener

        void removeDFEntityDataListener​(DFEntityDataListener listener)
        Unregisters an listener to be notified about data changes in this entity data provider.
        Parameters:
        listener - listener for data modification

      • retrieveDistinctValuesForField

        @Deprecated
java.util.List retrieveDistinctValuesForField​(java.lang.String fieldId)
        Deprecated.
        This method doesn't respect the entity SQL filter parameter, use retrieveDistinctValuesForField(com.im.df.api.ddl.DFField, com.im.commons.progress.DFEnvironmentRO)
        Gets the List of distinct values for this field.

        Even though this method doesn't take environment as a parameter, it hits the database and is potentially long running.

        To obtain field values which should be used for query, edit or insert use DFFieldPickListCapability (since 6.3).

        Parameters:
        fieldId - fieldId for query
        Returns:
        list of distinct values for field

      • retrieveDistinctValuesForField

        java.util.List<?> retrieveDistinctValuesForField​(DFField field,
                                                 com.im.commons.progress.DFEnvironmentRO env)
        Gets the List of distinct values for this field.

        To obtain field values which should be used for query, edit or insert use DFFieldPickListCapability (since 6.3).

        Parameters:
        field - field whose values should be retrieved, must belong to this entity
        env - the environment
        Returns:
        list of distinct values for field

      • generateStatistics

        java.lang.String generateStatistics()
        Generates 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.
        Returns:
        human readable string with statistical summary of the information this entity.