Working with Addon-Related Objects

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.

Creating an Addon

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);
}

Creating an Upgrade Addon

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);
}

Retrieving Registered Addons

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() );
   }
}

Installing an Addon

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.”);
}

Checking for Superseded Addons

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 + ".");
        }
    }

Retrieving Addon Installation Records

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" 
      );
   }
}

Deleting an Addon

You can delete UpgradeAddOn and AddOn objects from a domain's GCD, under the following conditions:

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);
}