Merging QofBook structures
[Query Object Framework]


Detailed Description

Collision handling principles.

  1. Always check for a GUID first and compare. qofbookmerge only accepts valid QofBook data and therefore ALL objects in the import book will include valid GUID's.
  2. If the original import data did not contain a GUID (e.g. an external non-GnuCash source) the GUID values will have been created during the import and will not match any existing GUID's in the target book so objects that do not have a GUID match cannot be assumed to be MERGE_NEW - parameter values must be checked.
  3. If import contains data from closed books, store the data from the closed books in the current book as active. i.e. re-open the books.

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.


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...


Enumeration Type Documentation

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.

Enumerator:
MERGE_UNDEF  default value before comparison is made.
MERGE_ABSOLUTE  GUID exact match, no new data - ignore
MERGE_NEW  import object does not exist in the target book - add
MERGE_REPORT  import object needs user intervention - report
MERGE_DUPLICATE  import object with different GUID exactly matches existing GUID - ignore
MERGE_UPDATE  import object matches an existing entity but includes new or modified parameter data - update
MERGE_INVALID  import object didn't match registered object or parameter types or user decided to abort - abort

Definition at line 126 of file qofbookmerge.h.

00126              { 
00127         MERGE_UNDEF,     
00128         MERGE_ABSOLUTE,  
00129         MERGE_NEW,       
00131         MERGE_REPORT,    
00132         MERGE_DUPLICATE, 
00134         MERGE_UPDATE,    
00136         MERGE_INVALID    
00138 }QofBookMergeResult;


Generated on Fri May 12 17:57:22 2006 for QOF by  doxygen 1.4.4