Evolve your SDK tool properties

As SDK tools age, it is likely that the maintainers of those tools will want to make "breaking changes" to the configuration properties. For example, suppose that you have created NiftyTool, and released version "1.0". That original version had a boolean (checkbox) property "doTheThing".

CODE

@Checkbox
public boolean doTheThing;

Presumably your code would check the value of doTheThing and adjust its behavior. In some later version "1.1", you realize that it would be even better if NiftyTool supported three types of things, so you change this property to a droplist with three values.

CODE

public enum WhatToDo { Nothing, Thing1, Thing2 };
@DropList
public WhatToDo whatToDo;
// Obsolete
//public boolean doTheThing;

Oh snap! You've just broken all of the projects that used NiftyTool. How can you avoid this problem, without doing something unnatural to your code? First, you must actually have a migration path – some equivalence between the old and new properties. In this example, the migration path is clear:

Old property doTheThing	New property whatToDo
false	WhatToDo.Nothing
true	WhatToDo.Thing1

Unfortunately, by the time the RPDM SDK toolkit maps your tool configuration to your property fields, it is too late to make this migration – the old configuration property "doTheThing" has no mapping to your new property field "whatToDo". Enter the version migration interface, which gives you access to a raw form of the configuration before it is used to configure your tool properties.

This feature is available starting in RPDM version 8.3.1

The version migration interface has two methods:

CODE

public interface VersionMigration {
   /**
    * Get the current version of the tool. 
    * This version will be saved with the tool properties in the project file, to assist in later version migration.
    * @return The tool version.  This should be >= 1.0.0.0, because the "default version" is 1.0.0.0.
    */
   public Version getVersion();
   /**
    * Apply any logic necessary to transform a configuration saved for an older version 
    * of the tool, to the appropriate configuration for a the new version.
    * @param config The configuration to migrate
    * @param version The version of the tool that saved the configuration.
    */
   public void migrate(ConfigMap config, Version version);
}

To use this feature, make your class implement the VersionMigration interface. In this example, you would implement it like:

CODE

public class NiftyTool extends Tool implements GeneralTool, VersionMigration {
   public enum WhatToDo { Nothing, Thing1, Thing2 };
   @DropList
   public WhatToDo whatToDo;

   @Override
   public Version getVersion() { return new Version("1.1"); }
   @Override
   public void migrate(ConfigMap config, Version version) {
      if (version.compareTo(new Version("1.1")) < 0) {
         // Migration from pre-1.1 tool version
         if (config.getBoolean("doTheThing")) {
            config.put("whatToDo", WhatToDo.Thing1);
         } else {
            config.put("whatToDo", WhatToDo.Nothing);
         }
      }
   }
}

You'll note that this introduces some new classes that represent the configuration hierarchy, in the package new.redpoint.dataflow.configuration

ConfigElement: Base class, in which most accessor/mutator methods are defined. Invalid access of values never throws exceptions, instead returning "default" values.
ConfigValue: Represents a scalar (Text, Long, Integer, Boolean) value
ConfigList: Represents a list of ConfigElements
ConfigMap: Represents a map from String to ConfigElement.

In addition, the net.redpoint.dataflow.transform.Version class is introduced to assist in comparing versions.

The property field names (in this case "doTheThing" and "whatToDo") are the keys into the raw configuration hierarchy.

Do not change anything in the configuration that you do not need to perform the migration. The configuration hierarchy may contain "hidden" elements that you should not alter.

You are responsible for tracking your tool versions. Note that the RPDM product version cannot be used for this purpose, as SDK tools are developed on an independent release cycle.

Tools that do not implement VersionMigration are assumed to be version 1.0.0.0