====== Compatibility manager ======

Workcraft stores the models in XML format with explicit references to classes implementing particular aspects of the models. This becomes problematic when doing refactoring. If you change the name of a class or a property name that is stored in in the XML file then Workcraft would not be able to read the previously stored files.

In order to partially mitigate this issue use the //compatibility manager// that is accessible trough  ''getCompatibilityManager()'' method of ''Framework'' class. It provides an interface to register refactoring-related modifications and to process the input streams by replacing old class and property names with the new ones. There are two distinctive types of changes that can be handled (explained for plugin called ''example''):

  * **Model-level** - change the name of the main model class, either mathematical or visual. For example, if you rename the model class ''Abc'' into ''Xyz'' then add the following code to your plugin initialisation:

<code java>
    framework.getCompatibilityManager().registerModelReplacement(Xyz.class.getName(),
        "org.workcraft.plugins.example.Abc");
</code>

  * ** Entry-level** - change something about a property. For example, you want to change the name of a color property from ''fillColor'' to ''backgroundColor'', then add the following code to your plugin initialisation:
<code java>
    framework.getCompatibilityManager().registerEntryReplacement(ExampleModel.class.getName(),
        "<property class=\"org.workcraft.plugins.example.Color\" name=\"fillColor\" value=",
        "<property class=\"org.workcraft.plugins.example.Color\" name=\"backgroundColor\" value=");
</code>

The best place to add the above code is into the ''init'' of your plugin implementation for the ''Module'' interface, the same place where the plugin tools are registered. The ''framework'' object is passed as a parameter to the ''init' method.

Note that the compatibility replacements only happen on reading the //.work// files so are not on the critical path and should not impact the performance of model deserialization. 

{{ :devel:design:compatibility.png?nolink |}}