QOF
0.8.7
|
Files | |
file | qofbookmerge.h |
API for merging two QofBook structures with collision handling. | |
Data Structures | |
struct | QofBookMergeRule |
One rule per entity, built into a single GList for the entire merge. More... | |
struct | QofBookMergeData |
mergeData contains the essential context data for any merge. More... | |
Enumerations | |
enum | QofBookMergeResult { MERGE_UNDEF, MERGE_ABSOLUTE, MERGE_NEW, MERGE_REPORT, MERGE_DUPLICATE, MERGE_UPDATE, MERGE_INVALID } |
Results of collisions and user resolution. More... | |
qof_book_merge API | |
typedef void(* | QofBookMergeRuleForeachCB) (QofBookMergeData *, QofBookMergeRule *, guint) |
Definition of the dialogue control callback routine. More... | |
QofBookMergeData * | qof_book_merge_init (QofBook *importBook, QofBook *targetBook) |
Initialise the QofBookMerge process. More... | |
void | qof_book_merge_rule_foreach (QofBookMergeData *mergeData, QofBookMergeRuleForeachCB callback, QofBookMergeResult mergeResult) |
Dialogue Control Callback. More... | |
QofBookMergeData * | qof_book_merge_update_result (QofBookMergeData *mergeData, QofBookMergeResult tag) |
called by dialogue callback to set the result of user intervention More... | |
gint | qof_book_merge_commit (QofBookMergeData *mergeData) |
Commits the import data to the target book. More... | |
void | qof_book_merge_abort (QofBookMergeData *mergeData) |
Abort the merge and free all memory allocated by the merge. More... | |
Collision handling principles.
If a GUID match exists, set qof_book_merge_rule::mergeAbsolute to TRUE.
If the import object GUID does not match an existing object, mergeAbsolute is unchanged from the default FALSE The parameter values of the object are compared to other objects of the same type in the target book.
More information is at http://code.neil.williamsleesmill.me.uk/
Each foreach function uses g_return_if_fail checks to protect the target book. If any essential data is missing, the loop returns without changing the target book. Note that this will not set or return an error value. However, g_return is only used for critical errors that arise from programming errors, not for invalid import data which should be cleaned up before creating the import QofBook.
Only qof_book_merge_update_result and qof_book_merge_commit return any error values to the calling process. qof_book_merge_init returns a pointer to the QofBookMergeData struct - the calling process needs to make sure this is non-NULL to know that the Init has been successful.
typedef void(* QofBookMergeRuleForeachCB) (QofBookMergeData *, QofBookMergeRule *, guint) |
Definition of the dialogue control callback routine.
All MERGE_REPORT rules must be offered for user intervention using this template.
Commit will fail if any rules are still tagged as MERGE_REPORT.
Calling processes are free to also offer MERGE_NEW, MERGE_UPDATE, MERGE_DUPLICATE and MERGE_ABSOLUTE for user intervention. Attempting to query MERGE_INVALID rules will cause an error.
For an example, consider test_rule_loop, declared as:
void test_rule_loop(QofBookMergeData *mergeData, QofBookMergeRule *rule, guint remainder);
void test_rule_loop(QofBookMergeData *mergeData, QofBookMergeRule *rule, guint remainder)
{
g_return_if_fail(rule != NULL);
g_return_if_fail(mergeData != NULL); printf("Rule Result %s", rule->mergeType);
qof_book_merge_update_result(mergeData, rule, MERGE_UPDATE);
}
The dialogue is free to call qof_book_merge_update_result in the loop or at the end as long as the link between the rule and the result is maintained, e.g. by using a GHashTable.
The parameters are:
Definition at line 321 of file qofbookmerge.h.
enum QofBookMergeResult |
Results of collisions and user resolution.
All rules are initialised as MERGE_UNDEF. Once the comparison is complete, each object within the import will be updated.
MERGE_ABSOLUTE, MERGE_NEW, MERGE_DUPLICATE and MERGE_UPDATE can be reported to the user along with all MERGE_REPORT objects for confirmation. It may be useful later to allow MERGE_ABSOLUTE, MERGE_NEW, MERGE_DUPLICATE and MERGE_UPDATE to not be reported, if the user sets a preferences option for each result. (Always accept new items: Y/N default NO, ignores all MERGE_NEW if set to Y etc.) This option would not require any changes to qofbookmerge.
MERGE_NEW, MERGE_DUPLICATE and MERGE_UPDATE are only actioned after conflicts are resolved by the user using a dialog and all MERGE_REPORT objects are re-assigned to one of MERGE_NEW, MERGE_DUPLICATE or MERGE_UPDATE. There is no automatic merge, even if no entities are tagged as MERGE_REPORT, the calling process must still check for REPORT items using qof_book_merge_rule_foreach and call qof_book_merge_commit.
MERGE_INVALID data should be rare and allows for user-abort - the imported file/source may be corrupted and the prescence of invalid data should raise concerns that the rest of the data may be corrupted, damaged or otherwise altered. If any entity is tagged as MERGE_INVALID, the merge operation will abort and leave the target book completely unchanged.
MERGE_ABSOLUTE is only used for a complete match. The import object contains the same data in the same parameters with no omissions or amendments. If any data is missing, amended or added, the data is labelled MERGE_UPDATE.
Every piece of data has a corresponding result. Only when the count of items labelled MERGE_REPORT is equal to zero are MERGE_NEW and MERGE_UPDATE items added to the existing book.
MERGE_DUPLICATE items are silently ignored. Aborting the dialogue/process (by the user or in a program crash) at any point before the final commit leaves the existing book completely untouched.
Definition at line 125 of file qofbookmerge.h.
void qof_book_merge_abort | ( | QofBookMergeData * | mergeData | ) |
Abort the merge and free all memory allocated by the merge.
Sometimes, setting MERGE_INVALID is insufficient: e.g. if the user aborts the merge from outside the functions dealing with the merge ruleset. This function causes an immediate abort - the calling process must start again at Init if a new merge is required.
Definition at line 937 of file qofbookmerge.c.
gint qof_book_merge_commit | ( | QofBookMergeData * | mergeData | ) |
Commits the import data to the target book.
The last function in the API and the final part of any QofBookMerge operation.
qof_book_merge_commit will abort the entire merge operation if any rule is set to MERGE_INVALID. It is the responsibility of the calling function to handle the error code from ::qof_book_mergeCommit, close the dialogue and return. qof_book_merge_commit will already have halted the merge operation and freed any memory allocated to all merge structures before returning the error code. There is no way for the dialogue process to report back to qof_book_merge in this situation.
qof_book_merge_commit checks for any entities still tagged as MERGE_REPORT and then proceeds to import all entities tagged as MERGE_UPDATE or MERGE_NEW into the target book.
This final process cannot be UNDONE!
mergeData | the merge context, QofBookMergeData* |
Definition at line 998 of file qofbookmerge.c.
QofBookMergeData* qof_book_merge_init | ( | QofBook * | importBook, |
QofBook * | targetBook | ||
) |
Initialise the QofBookMerge process.
First function of the QofBookMerge API. Every merge must begin with init.
Requires the book to import (QofBook *) and the book to receive the import, the target book (QofBook *). Returns a pointer to QofBookMergeData which must be checked for a NULL before continuing.
Process:
-# Invoke the callback ::qof_book_merge_foreach_type on every registered object class definition. -# Callback obtains the registered parameter list for each object type. This provides run time access to all registered objects and all object parameters without any changes to QofBookMerge - no registered object or parameter is omitted from any merge operation. -# Use ::qof_object_foreach to invoke the callback ::qof_book_merge_foreach, one object at a time on every instance stored in mergeBook. This is the first point where real data from the import book is accessed. -# qof_book_merge_foreach obtains the ::GUID for the object from the import book and runs the first check on the original book, checking for any exact GUID match. With the full parameter list, the rules for this object can be created. If there is a GUID match, the data in each parameter of the import object is compared with the same semantic object in the original book. If there is no GUID in the import object or no GUID match with the original book, the original book is searched to find a parameter match - checking for a ::MERGE_DUPLICATE result. -# ::qof_book_merge_compare sets the ::QofBookMergeResult of the comparison. -# Inserts the completed rule into QofBookMergeData::mergeList GSList.
Definition at line 900 of file qofbookmerge.c.
void qof_book_merge_rule_foreach | ( | QofBookMergeData * | mergeData, |
QofBookMergeRuleForeachCB | callback, | ||
QofBookMergeResult | mergeResult | ||
) |
Dialogue Control Callback.
This function is designed to be used to iterate over all rules tagged with a specific QofBookMergeResult value.
callback | external loop of type QofBookMergeRuleForeachCB |
mergeResult | QofBookMergeResult value to look up. |
mergeData | QofBookMergeData merge context. |
Note : MERGE_NEW causes a new entity to be created in the target book at commit which is then assigned as the targetEnt of that rule. If mergeResult == MERGE_NEW, the rules returned by qof_book_merge_rule_foreach will have a NULL set for the targetEnt. This is because commit has not yet been called and no changes can be made to the target book. The calling process must handle the NULL targetEnt and NOT call any param_getfcn routines for the target entity. The import entity is available for display.
Uses qof_book_get_collection with the QofBookMergeRule::mergeType object type to return a collection of QofEntity entities from either the QofBookMergeData::mergeBook or QofBookMergeData::targetBook. Then uses qof_collection_lookup_entity to lookup the QofBookMergeRule::importEnt and again the qof_book_mergeRule::targetEnt to return the two specific entities.
Definition at line 1050 of file qofbookmerge.c.
QofBookMergeData* qof_book_merge_update_result | ( | QofBookMergeData * | mergeData, |
QofBookMergeResult | tag | ||
) |
called by dialogue callback to set the result of user intervention
Set any rule result to MERGE_INVALID to abort the import when qof_book_merge_commit is called, without changing the target book.
The calling process should make it absolutely clear that a merge operation cannot be undone and that a backup copy should always be available before a merge is initialised.
Recommended method: Only offer three options to the user per rule:
Handle the required result changes in code: Check the value of qof_book_mergeRule::mergeAbsolute and use these principles:
To ignore entities tagged as:
To merge entities that are not pre-set to MERGE_NEW, set MERGE_UPDATE.
Attempting to merge an entity when the pre-set value was MERGE_NEW will force a change back to MERGE_NEW because no suitable target exists for the merge.
To add entities, check mergeAbsolute is FALSE and set MERGE_NEW.
An entity only be added if mergeAbsolute is FALSE. Attempting to add an entity when mergeAbsolute is TRUE will always force a MERGE_UPDATE.
It is not possible to update the same rule more than once.
qof_book_merge_commit only commits entities tagged with MERGE_NEW and MERGE_UPDATE results.
Entities tagged with MERGE_ABSOLUTE and MERGE_DUPLICATE results are ignored.
The calling process must check the return value and call ::qof_book_merge_abort(mergeData) if non-zero.
mergeData | the merge context, QofBookMergeData* |
tag | the result to attempt to set, QofBookMergeResult |
Definition at line 966 of file qofbookmerge.c.