Merger and Capabilities

This page should collect information about the (re)design of the Merge and the use of Capabilities.

Problem: Fixed to XMLFormat

Current implementation has the downside that it's fixed to the xmlformat. Sync-Plugins have already lots of traces of the XMLFormat, for convert the "native" capabilities information into XMLFormat-speech, so the XMLFormat-merge can be used. At some later point this makes it really hard to change to a different "common" format -> not future proof?

Current merger implementation would call the merge/demerge function of the "common format" (e.g. XMLFormat and it's merge_xmlformat). (Also see:  http://opensync.org/wiki/trunk/features/mergerFormatConversion). This function assume that the OSyncCapabilities object passed as argument is filled with XMLFormat-named fields. The OSyncCapabilities information get assembled by the Sync-Plugins during the discover-phase. (Later it should be possible to also report capabilities during connect(), connect_done() and get_changes() plugin context).

During this discover-phase and before the assembling of OSyncCapabilities object, the Sync Plugin needs to translate the "native" Capabilities content into XMLFormat-like capabilities. If there would be several "common formats" beside the XMLFormat - there would be no possible to register/assemble OSyncCapabilities dynamically depending on the used "common" format. Since the capabilities get cached via the OSyncCapabilities interface once.

OSyncObjFormat ... OSyncCapsFormat?

Native Capabilities merger/demerge function would allow Synchronization plugins to assemble the an OSyncCapabilities object independent of the XMLFormat plugin (or any other common format). The registration of the merge/demerge function would be slightly different. Instead of assigning the merger to one OSyncObjFormat, it additional gets assigned to a "capabilities format":

OSyncCapabilities *osync_capabilities_new(const char *capsformat, OSyncError **error);

OSyncFormatMerger *osync_merger_new(OSyncObjFormat *base_format, 
                                    const char *capsformat,
                                    OSyncFormatMergeFunc merge_func,
                                    OSyncFormatDemergeFunc demerge_func,
                                    OSyncError **error);

void osync_format_env_register_merger(OSyncFormatEnv *env, OSyncFormatMerger *merger);

A plugin could register in a special format plugin section several mergers for different OSyncObjFormat:

osync_bool get_merger_info(OSyncFormatEnv *formatenv, OSyncError **error)
{

  OSyncObjFormat *xmlformat_evemt = osync_format_env_find_objformat(formatenv, "xmlformat-event");
  OSyncObjFormat *xmlformat_contact = osync_format_env_find_objformat(formatenv, "xmlformat-contact");
  OSyncObjFormat *vcard30 = osync_format_env_Find_objformat(formatenv, "vcard30");

  OSyncFormatMerger *merger1 = osync_merger_new(xmlformat_event, "evo2-caps", evo2_xmlformat_event_merger, evo2_xmlformat_event_demerger, error);
  OSyncFormatMerger *merger2 = osync_merger_new(vcard30, "evo2-caps", evo2_vcard30_contact_merger, evo2_vcard30_contact_demerger, error);
  OSyncFormatMerger *merger2 = osync_merger_new(xmlformat_contact, "evo2-caps", evo2_xmlformat_contact_merger, evo2_xmlformat_contact_demerger, error);

  osync_format_env_register_merger(formatenv, merger1);
  osync_format_env_register_merger(formatenv, merger2);

  [...]

  return TRUE;
}

Sync plugins would then just assemble a OSyncCapabilities object in "native" language - no XMLFormat or other format translation required!:

osync_bool evo2_discover(OSyncPluginInfo *info, void *data, OSyncError **error)
  [...]
  GList *fields = NULL;

  OSyncCapabilities *caps = osync_capabilities_new("evo2-caps", error);
  
  e_book_get_supported_fields (book, &fields, &gerror);
  
  while (fields) {
     osync_capability_new(caps, "contact", field->data, error);
     fields = g_list_remove(fields, fields->data);
   }
   [...]
}

The OpenSync Engine would then lookup the merge/demerge function from the OSyncFormatEnv. And match for the "capsformat" (e.g. "evo2-caps") and the OSyncObjFormat.

The advantages of sync plugin specific merge and demerge function are:

• when assembling OSyncCapabilities no "format" translation inside the sync-plugin is required
• this allows to support several "common formats" without rewriting the sync-plugin (e.g XMLFormat, XMLForamt2, ...)
• the sync plugin specific merge/demerge function can handle more protocol/plugin specific handling of capabilities
• plugin specific caps-format is optional - old / xmlformat-specific behavior can still be requested - by requesting xmlformat specific caps:

  OSyncCapabilities *caps = osync_capabilities_new("xmlformat-caps", error);