This topic provides code examples for installing and upgrading feature addons. For an overview of addons, see Feature Addon Concepts.
To start the installation process, you must first create an addon, which registers it into a specified domain's Global Configuration Data (GCD) database. You can retrieve addons from the domain, and delete addons if they haven't already been installed on an object store.
Once registered in a domain, you can install an addon to new or existing object stores. You can later replace one or more installed addons with a single upgrade operation. When you install an addon, an install record is created for it. You can retrieve addon installation records from an object store.
The following Java™ and C# examples show how to create an AddOn object. A new instance of an AddOn
is created by passing the Domain object and a unique GUID that will identify the AddOn
in the domain's GCD. The data to be imported is set on the AddOn
object as a FileInputStream
. Then the object's properties are set, including the Prerequisites property. The prerequisite AddOn
specified by the GUID will have to be installed prior to the installation of this new AddOn
object. Lastly, the new AddOn
object is saved, which registers it in the domain's GCD. You can retrieve a list of registered addons from the Domain
object.
Java Example
public void createAddon(Domain domain) { // Create AddOn object AddOn addon = Factory.AddOn.createInstance(domain, new Id("{70f5fb79-32fb-412f-930f-ce5d40fa5c9a}") ); // Create FileInputStream for data to be imported // and set it on AddOn object. File xmlManifest = new File("C:\\temp\\Addon_v1.xml"); FileInputStream fis = null; try { fis = new FileInputStream(xmlManifest); } catch (FileNotFoundException fnfe) { fnfe.printStackTrace(); } addon.setImportDataStream(fis); // Set properties of AddOn object. IdList preRequisiteList = Factory.IdList.createList(); preRequisiteList.add(new Id("{a3b865d4-41c4-4e9d-8e97-e9eb54e5752c}") ); addon.set_Prerequisites(preRequisiteList); addon.set_AddOnType(AddOnType.OPTIONAL); addon.set_DisplayName("Addon_v2"); addon.set_DescriptiveText("Installs classes and properties necessary for v2 functionality"); addon.set_Creator("CEMP Integrators"); addon.save(RefreshMode.NO_REFRESH); }
C# Example
public void createAddon(IDomain domain) { IAddOn addon = Factory.AddOn.CreateInstance(domain, new Id("{70f5fb79-32fb-412f-930f-ce5d40fa5c9a}") ); // Create Stream for data to be imported // and set it on IAddOn object. Stream fileStream = File.OpenRead("C:\\temp\\Addon_v1.xml"); addon.SetImportDataStream(fileStream); // Set properties of IAddOn object. IIdList preRequisiteList = Factory.IdList.CreateList(); preRequisiteList.Add(new Id("{a3b865d4-41c4-4e9d-8e97-e9eb54e5752c}")); addon.Prerequisites = preRequisiteList; addon.AddOnType = AddOnType.OPTIONAL; addon.DisplayName = "C#Addon_v2"; addon.DescriptiveText = "Installs classes and properties necessary for v2 functionality"); addon.Creator = "CEMP Integrators"; addon.Save(RefreshMode.NO_REFRESH); }
An UpgradeAddOn
object is the vehicle used to move a superseded addon to its current, upwardly compatible version. The following Java and C# examples show how to create an UpgradeAddOn object. The process is nearly identical to creating an AddOn object, with the following exceptions: although present on the UpgradeAddOn
object by way of inheritance, the SupersededAddOnIds property does not apply to UpgradeAddOn
objects and thus is not involved in the process; and an UpgradeAddOn
object includes two additional properties to set, FromVersion and ToVersion, both of which take an IdList
object. As shown, two IdList
objects are created, one for a list of currently installed addons to be upgraded, and the other for a list of new addons that will replace the existing ones. Note that the new addons will have to be registered in the domain's GCD before the UpgradeAddOn
object can be installed in an object store. When the new UpgradeAddOn
object is saved, it's registered in the domain's GCD.
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 addons 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 addons that will replace existing addons. 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 xmlManifest = new File("C:\\temp\\Upgrade_v1_to_v2.xml"); FileInputStream fis = null; try { fis = new FileInputStream(xmlManifest); } 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 addons 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 addons that will replace existing addons. 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); }
You can retrieve all of the AddOn objects registered in a domain's GCD. As shown in the following Java and C# examples, you get the Domain object's AddOns
property, which holds the AddOnSet
collection.
Java Example
public void retrieveInstallableAddons(Domain domain) { AddOnSet aos = domain.get_AddOns(); Iterator iter = aos.iterator(); while (iter.hasNext()) { AddOn addon = (AddOn)iter.next(); System.out.println("AddOn name: " + addon.get_DisplayName() + "\n" + "Install ID: " + "\n" + addon.get_Id().toString() ); } }
C# Example
public void retrieveInstallableAddons(IDomain domain) { IAddOnSet ads = domain.AddOns; System.Collections.IEnumerator addOnsIter = ads.GetEnumerator(); while (addOnsIter.MoveNext()) { IAddOn addon = (IAddOn)addOnsIter.Current; System.Console.WriteLine("AddOn name: " + addon.DisplayName + "\n" + "Install ID: " + "\n" + addon.Id.ToString() ); } }
When an AddOn
or UpgradeAddOn
object has been registered in a domain GCD, you can install it to new or existing object stores. As shown in the Java and C# examples below, you call the ObjectStore.installAddOn
method to install an AddOn
or UpgradeAddOn
to an object store. When you save the ObjectStore
object, an AddOnInstallationRecord
object is created, from which you can get the status of the installation. See Retrieving Addon Installation Records.
This example determines whether the Publishing Extensions addon is installed and if it is not, installs all addons necessary (including itself).
The determinePrerequisiteAddOnIds
method checks for the presence of the specified AddOn
ID. (For more information, see the reference help for ObjectStore.determinePrerequisiteAddOnIds
.)
Java Example
public void verifyPublishingExtensions() { System.out.println("Checking for required AddOns ..."); IdList requiredAddOnIds = objectStore.determinePrerequisiteAddOnIds(SystemAddOnId.PUBLISHING); for (int i = 0; i < requiredAddOnIds.size(); i++ ) { Id addOnIds = (Id)requiredAddOnIds.get(i); AddOn addOn = Factory.AddOn.getInstance(domain, addOnId); System.out.println("Installing AddOn: " + addOn.get_DisplayName() + " ... "); objectStore.installAddOn(addOn); objectStore.save(RefreshMode.REFRESH); System.out.println("Installed AddOn: " + addOn.get_DisplayName() + "."); } System.out.println("Required AddOns installed."); }
C# Example
public void verifyPublishingExtensions() { System.Console.WriteLine(“Checking for required AddOns …”); IIdList requiredAddOnIds = objectStore.DeterminePrerequisiteAddOnIds(SystemAddOnId.PUBLISHING); for (int i = 0; i < requiredAddOnIds.Count; i++ ) { Id addOnId = (Id)requiredAddOnIds[i]; IAddOn addOn = Factory.AddOn.GetInstance(domain,addOnId); System.Console.WriteLine(“Installing AddOn: “ + addOn.DisplayName + “…”); objectStore.InstallAddOn(addOn); objectStore.Save(RefreshMode.REFRESH); System.Console.WriteLine(“Installed AddOn: " + addOn.DisplayName + “.”); } System.Console.WriteLine(“Required AddOns installed.”); }
A well-written application might need to determine if functionality it requires (in a previous, superseded AddOn) is currently available in the IBM FileNet P8 domain. In this case, the application can call Factory.AddOn.fetchSupersedingInstance
, which checks for a superseding addon based on the ID you pass in. If a superseding addon does not exist, the method returns the addon you requested and its ID should match the ID you specified in the method call. If the addon does have a superseding addon, then the method returns the superseding addon (which will have a different ID than the one you specified in the method call).
Once the application knows that a compatible addon exists in the domain, the application can call the ObjectStore.isAddOnInstalled method to determine whether a given addon is installed in an object store. This method takes an Id object, which can be either the ID of a currently installed addon or a superseded addon. The method returns false in cases where an upwardly compatible addon does not exist in the IBM FileNet P8 domain. The following code snippet illustrates the use of this method:
Java Example
void installOn(Domain domain, AddOn addOn) { if ( objectStore.isAddOnInstalled(addOn.get_Id()) == false ) { System.out.println("+++ Installing " + addOn.get_DisplayName() + " into object store " + objectStore.get_DisplayName() + " ..."); objectStore.installAddOn(addOn); objectStore.save(RefreshMode.REFRESH); } else { System.out.println("--- " + addOn.get_DisplayName() + " already installed in object store " + objectStore.get_DisplayName() + "."); } }
C# Example
void installOn(IDomain domain, IAddOn addOn) { if ( objectStore.IsAddOnInstalled(addOn.Id) == False ) { System.Console.WriteLine("+++ Installing " + addOn.DisplayName + " into object store " + objectStore.DisplayName + " ..."); objectStore.InstallAddOn(addOn); objectStore.Save(RefreshMode.REFRESH); } else { System.Console.WriteLine("--- " + addOn.DisplayName + " already installed in object store " + objectStore.DisplayName + "."); } }
You can retrieve addon installation records for all of the addons and upgrade addons installed on an object store. Represented as an AddOnInstallationRecord
object, the record provides various installation-related properties.
As shown in the following Java and C# examples, you must retrieve the AddOnInstallationRecordList
collection from an ObjectStore
and iterate through it to access individual AddOnInstallationRecord
objects.
Java Example
public void retrieveInstalledAddons(ObjectStore objectStore) { AddOnInstallationRecordList installList = objectStore.get_AddOnInstallationRecords(); AddOnInstallationRecord aoir = null; Iterator iter = installList.iterator(); while (iter.hasNext()) { aoir = (AddOnInstallationRecord)iter.next(); System.out.println("Addon name: " + aoir.get_AddOnName() + "\n" + "Install ID: " + aoir.get_Id().toString() + "\n" + "Install date: " + aoir.get_InstallationDate() + "\n" + "Installer: " + aoir.get_Installer() + "\n" + "Install status: " + aoir.get_InstallationStatus() + "\n" + "Install report: " + aoir.get_InstallationReport() + "\n" ); } }
C# Example
public void retrieveInstalledAddons(IObjectStore objectStore) { IAddOnInstallationRecordList installList = objectStore.AddOnInstallationRecords; IAddOnInstallationRecord aoir = null; System.Collections.IEnumerator installIter = installList.GetEnumerator(); while (installIter.MoveNext()) { aoir = (IAddOnInstallationRecord)installIter.Current; System.Console.WriteLine("Addon name: " + aoir.AddOnName + "\n" + "Install ID: " + aoir.Id.ToString() + "\n" + "Install date: " + aoir.InstallationDate + "\n" + "Installer: " + aoir.Installer + "\n" + "Install status: " + aoir.InstallationStatus + "\n" + "Install report: " + aoir.InstallationReport + "\n" ); } }
You can delete UpgradeAddOn
and AddOn
objects from a domain's GCD, under the following conditions:
UpgradeAddOn
has been installed.AddOn
object has not been installed.The following examples show deletion of an AddOn
object.
Java Example
public void deleteInstallableAddon(Domain domain) { AddOn addon = Factory.AddOn.getInstance(domain, "{CE400ADD-AAAA-BBBB-CCCC-000000000008}"); addon.delete(); addon.save(RefreshMode.NO_REFRESH); }
C# Example
public void deleteInstallableAddon(IDomain domain) { IAddOn addon = Factory.AddOn.GetInstance(domain, "{CE400ADD-AAAA-BBBB-CCCC-000000000008}"); addon.Delete(); addon.Save(RefreshMode.NO_REFRESH); }