An UpgradeAddOn object is the vehicle that is used to move a superseded add-on to its current, upwardly compatible version.
Upgrading an add-on is nearly identical to creating an AddOn object, except for a couple of differences. First, the SupersededAddOnIds property that is inherited from Addon is not used by the UpgradeAddOn object. Second, an UpgradeAddOn object includes two additional properties to set, FromVersion and ToVersion, both of which take an IdList object. As shown in the Java™ and C# examples, two IdList objects are created, one for a list of currently installed add-ons to be upgraded, and the other for a list of new add-ons that will replace the existing ones.
When the new UpgradeAddOn object is saved, it is registered in the domain's Global Configuration Database (GCD). Note that the new add-ons that are referenced by the UpgradeAddOn object must be registered in the domain's GCD before the UpgradeAddOn object can be installed in an object store.
Java Example
public void createUpgradeAddon(Domain domain)
{
// Create Upgrade AddOn object.
UpgradeAddOn UAO = Factory.UpgradeAddOn.createInstance(domain,
new Id("{1dbfc769-d033-46dc-804f-ad603fa07282}") );
// Create list with installed add-ons to be upgraded.
IdList fromList = Factory.IdList.createList();
fromList.add(new Id("{ce400add-aaaa-bbbb-cccc-00000000000a}") );
fromList.add(new Id("{ce400add-aaaa-bbbb-cccc-00000000000b}") );
fromList.add(new Id("{ce400add-aaaa-bbbb-cccc-00000000000c}") );
// Create list with new add-ons that will replace existing add-ons.
IdList toList = Factory.IdList.createList();
toList.add(new Id("{70f5fb79-32fb-412f-930f-ce5d40fa5c9a}") );
toList.add(new Id("{70f5fb79-32fb-412f-930f-ce5d40fa5c9b}") );
toList.add(new Id("{70f5fb79-32fb-412f-930f-ce5d40fa5c9c}") );
// Create FileInputStream for upgrade data to be imported
// and set it on UpgradeAddOn object.
File importDataset = new File("C:\\temp\\Upgrade_v1_to_v2.xml");
// non-Windows: File importDataset = new File("/tmp/Upgrade_v1_to_v2.xml");
FileInputStream fis = null;
try
{
fis = new FileInputStream(importDataset);
}
catch (FileNotFoundException fnfe)
{
fnfe.printStackTrace();
}
UAO.setImportDataStream(fis);
// Set properties of UpgradeAddOn object.
UAO.set_FromVersions(fromList);
UAO.set_ToVersions(toList);
UAO.set_AddOnType(AddOnType.OPTIONAL);
UAO.set_DisplayName("Upgrade_v1_To_v2");
UAO.set_DescriptiveText("Updates classes and properties added by addon v1 to required functionality provided by addon v2, and adds new classes and properties as appropriate.");
UAO.set_Creator("CEMP Integrators");
UAO.save(RefreshMode.REFRESH);
}
C# Example
public void createUpgradeAddon(IDomain domain)
{
// Create UpgradeAddOn object.
IUpgradeAddOn UAO = Factory.UpgradeAddOn.CreateInstance(domain,
new Id("{1dbfc769-d033-46dc-804f-ad603fa07282}"));
// Create list with installed add-ons to be upgraded.
IIdList fromList = Factory.IdList.CreateList();
fromList.Add(new Id("{ce400add-aaaa-bbbb-cccc-00000000000a}"));
fromList.Add(new Id("{ce400add-aaaa-bbbb-cccc-00000000000b}"));
fromList.Add(new Id("{ce400add-aaaa-bbbb-cccc-00000000000c}"));
// Create list with new add-ons that will replace existing add-ons.
IIdList toList = Factory.IdList.CreateList();
toList.Add(new Id("{70f5fb79-32fb-412f-930f-ce5d40fa5c9a}"));
toList.Add(new Id("{70f5fb79-32fb-412f-930f-ce5d40fa5c9b}"));
toList.Add(new Id("{70f5fb79-32fb-412f-930f-ce5d40fa5c9c}"));
// Create Stream for upgrade data to be imported
// and set it on IUpgradeAddOn object.
Stream fileStream = File.OpenRead("C:\\temp\\Upgrade_v1_to_v2.xml");
UAO.SetImportDataStream(fileStream);
// Set properties of IUpgradeAddOn object.
UAO.FromVersions = fromList;
UAO.ToVersions = toList;
UAO.AddOnType = AddOnType.OPTIONAL;
UAO.DisplayName = "Upgrade_v1_To_v2";
UAO.DescriptiveText = "Updates classes and properties added by addon v1 to required functionality provided by addon v2, and adds new classes and properties as appropriate.";
UAO.Creator = "CEMP Integrators";
UAO.Save(RefreshMode.REFRESH);
}