com.im.df.api.util
Class BatchUpdater

java.lang.Object
  com.im.df.api.util.BatchUpdater

public abstract class BatchUpdater
extends Object

Utility class for multi-row update which can simplify loop for updating data in entities. This class provides these functions for you:

• Loop control
• Checking DFFeedback.isCancelled() and stopping the loop
• Updating progress provided by DFEnvironmentRO.getFeedback()
• Undo/redo support according to configuration given in constructor
• Customizable messages for progress, cancel
• Customizable stop criteria (e.g. based on failures of update method calls)

Example of usage:

       DFField field = ....
       DFResultSet.VertexState vs = ...
       DFEntity entity = vs.getVertex().getEntity();
       DFEntityDataProvider edp = DIFUtilities.findEntityDataProvider(entity);
       DFEnvironmentRW env = ...
       DFUndoConfig undoConfig = DFUndoConfig.create("Deleting data in column "+field.getName(), true);
       SelectionDescription sel = vs.getSelection();
       Map data = new HashMap();
       data.put(f.getId(), null);

       BatchUpdater updater = new BatchUpdater(edp, env, undoConfig, sel.getMinSelectionIndex(), sel.getMaxSelectionIndex(), 1) {
           public DFUpdateDescription createUpdate(int index) {
               return DFUpdateDescription.create(entity, vs.getIdAt(index), data);
           }

           public String getProgressMessage(int counter, int total) {
               return "Deleted " + counter + " out of " + total + " rows";
           }

           public String getCancelledMessage(int progressCounter, int failuresCount, int totalCount) {
               return "Delete stopped after " + progressCounter + " out of " + totalCount + "(failures: " + failuresCount + ")";
           }
       };
       updater.run();
       if (updater.hasFailures()) {
           Collection failures = updater.getUpdateFailures().values();
           ....
       }
 

Nested Class Summary

static class

BatchUpdater.StopReason

Constructor Summary

BatchUpdater(DFEntityDataProvider edp, DFEnvironmentRW env, DFUndoConfig undoConfig, int fromIndex, int toIndex, int failLimit)
Creates updater.

BatchUpdater(DFEntityDataProvider edp, DFEnvironmentRW env, DFUndoConfig undoConfig, SelectionDescription selection, int failLimit)

Method Summary

DFUndoConfig	createUndoConfigFor(int index) It's possible to customize the undo config for each loop.
abstract DFUpdateDescription	createUpdate(int index) Subclass must implement this method and provide DFUpdateDescription instance for giver index (typically row).
int	getFailuresCount() Total count of failures: preparation + update calls
List<Integer>	getPreparationFailures() Get list of indexes which failed to prepare DFUpdateDescription instance.
int	getProcessedRows() The count of cycles which were processed so far (including failures).
String	getProgressMessage(int counter, int total) Override this method if you want to provide customized progress message
BatchUpdater.StopReason	getStopReason() Return code of the process: normally finished, cancelled or stopped after too many errors?
int	getSuccessUpdates() Number of successful updates so far
String	getSummaryMessage(BatchUpdater.StopReason reason, int progressCounter, int totalCount, int failuresCount) Override this method if you want to provide customized operation summary message when operations is finished.
int	getTotalUpdatesCount() Total expected count of loop cycles
Map<DFUpdateDescription,DFUpdateResult>	getUpdateFailures() Get all failures during update method call
boolean	hasFailures() Were there already any failures?
boolean	resultsNotify(Map<DFUpdateDescription,DFUpdateResult> results) Notifies about result of batch update method call.
void	run() Starts the process

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BatchUpdater

public BatchUpdater(DFEntityDataProvider edp,
                    DFEnvironmentRW env,
                    DFUndoConfig undoConfig,
                    int fromIndex,
                    int toIndex,
                    int failLimit)

Creates updater. Once the instance is created you should call run() method.

Parameters:

edp - Entity data provider which will be used for updating data

env - The read/write environment with valid lock for DFEntityDataProvider manipulation

undoConfig - Configuration for undo/redo support.

fromIndex - First index of the loop for updating (typically index of row)

toIndex - Last index of the loop

failLimit - Loop will stop if update method calls fails for more rows than this limit. As the update method is called for more rows in a single call (this implementation uses constant DIFUtilities.UPDATE_DESCRIPTORS_RECOMMENDED_LIMIT then it's possible that there will be more fails than this limit.

BatchUpdater

public BatchUpdater(DFEntityDataProvider edp,
                    DFEnvironmentRW env,
                    DFUndoConfig undoConfig,
                    SelectionDescription selection,
                    int failLimit)

Method Detail

run

public void run()

Starts the process

getStopReason

public BatchUpdater.StopReason getStopReason()

Return code of the process: normally finished, cancelled or stopped after too many errors?

getProgressMessage

public String getProgressMessage(int counter,
                                 int total)

Override this method if you want to provide customized progress message

Parameters:

counter - The current number of processed rows

total - Total number rows to be processed

Returns:

The message which is used in progress bar in IJC

getSummaryMessage

public String getSummaryMessage(BatchUpdater.StopReason reason,
                                int progressCounter,
                                int totalCount,
                                int failuresCount)

Override this method if you want to provide customized operation summary message when operations is finished.

Parameters:

reason - Why operation is finished

progressCounter - The current number of processed rows

totalCount - Total number rows which were supposed to be processed

failuresCount - The number of update method calls which failed

Returns:

The message which is used in progress bar in IJC

resultsNotify

public boolean resultsNotify(Map<DFUpdateDescription,DFUpdateResult> results)

Notifies about result of batch update method call. You can override this method and change the decission if process should continue after failures (for example).

Parameters:

results - The partial results

Returns:

True if process should continue otherwise false

getSuccessUpdates

public int getSuccessUpdates()

Number of successful updates so far

getTotalUpdatesCount

public int getTotalUpdatesCount()

Total expected count of loop cycles

getFailuresCount

public int getFailuresCount()

Total count of failures: preparation + update calls

getProcessedRows

public int getProcessedRows()

The count of cycles which were processed so far (including failures).

hasFailures

public boolean hasFailures()

Were there already any failures?

Returns:

True if there is at least one failure of update method call

getUpdateFailures

public Map<DFUpdateDescription,DFUpdateResult> getUpdateFailures()

Get all failures during update method call

getPreparationFailures

public List<Integer> getPreparationFailures()

Get list of indexes which failed to prepare DFUpdateDescription instance.

createUndoConfigFor

public DFUndoConfig createUndoConfigFor(int index)

It's possible to customize the undo config for each loop. You can use it in the case when global DFUndoConfig (passed to constructor) specifies that each update should have its own Undo/Redo operation. In this case you can provide suitable name for each specific update call.

For example if you are using BatchUpdater class for pasting 10 values to different rows and you want to have each row change as separate undo operation (user will need to press Undo button 10 times to revert the operation completely). In this case you can provide DFUndoConfig instance for each update call with different name which will be visible in Undo action name in main menu: e.g. action will have name "Undo change row 10" and when you press it the action renames to "Undo change row 9" and redo will rename to "Redo change row 10".

Parameters:

index -

Returns:

The undo config

createUpdate

public abstract DFUpdateDescription createUpdate(int index)

Subclass must implement this method and provide DFUpdateDescription instance for giver index (typically row).

It's allowed that this method returns null. In this case the current index is added to list of failures during preparation of DFUpdateDescription. This can be useful if you find our you are now able to create DFUpdateDescription for some reason during loop.