Table of Contents | Next | Previous

This article contains the following sections:

• Eclipse component updates - via new versions using match rules
• Eclipse component updates - via new plugins
• Eclipse component updates - maintaining two versions within a single component
• Choosing the best update option

To cover additional important areas of the development/deployment cycle of composite applications, we now to cover upgrading or updating. When trying to upgrade or update existing composite applications, there are many scenarios that can be encountered. These can include the following (arranged in the order of difficulty from least to most difficult):

• Only the NSF components have changed -- This type of upgrade is not difficult. Only the modified component NSFs are re-deployed. The Eclipse components and the NSF with the CA.XML do not have to be touched.
• Only the CA.XML has changed and no new components or component versions have been added -- This type of upgrade is also not difficult. Only the NSF with the CA.XML needs to be re-deployed.
• Eclipse component updated via new versions using match rules -- In this type of upgrade there are new versions of Eclipse components available. In order to do this you have to use "match rules" appropriately (see below for details). The new versions of Eclipse components need to be added to the production NSF-based update sites.
• Eclipse component updated via new plugins - In this type of upgrade, there are new versions of Eclipse components available and the CA.XML refers to specific versions. In this case the new Eclipse component versions need to be added to the production NSF-based update site and the NSF with the CA.XML needs to be redeployed as well.
• Eclipse component updated by maintaining two versions within a single component - In this type of upgrade, new versions of components are produced with the same name. Older versions will be displaced, but within the components themselves, all of the old code base is maintained.

The last three of the scenarios listed are described in more detail in the next sections.

Eclipse component updated via new versions using match rules

In order to update Eclipse components you first need to understand how "match rules" are used in Eclipse. For more information on using match rules, refer to the "Customizing the Notes install kit to add or remove Eclipse features" section of the Domino Administrator help as well as the "Customizing the Notes install manifest for new or third-party Eclipse features" topic in this section.

Take the example of the following sample component version number:

Sample version number: "1.2.3" where
1 = major number
2 = minor number
3 = service number

The following text is from http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/feature_manifest.html and describes the "version" and "match" definitions used in the feature manifest DTD and would apply to updating components. Additional information may also be found in the "Provisioning manifest DTD" topic at http://infocenters.lotus.com/help9/index.jsp?topic=/com.ibm.rcp.tools.doc.admin/manifestDTD.html.

version - optional plug-in version specification

match - optional matching rule. Valid values and processing are as follows:
- if version attribute is not specified, the match attribute (if specified) is ignored.
- perfect - dependent plug-in version must match exactly the specified version. If "patch" is "true", "perfect" is assumed and other values cannot be set.
Sample: ca xml with 1.0.0 will always provision version 1.0.0
- equivalent - dependent plug-in version must be at least at the version specified, or at a higher service level (major and minor version levels must equal the specified version).
Sample: ca xml with 1.0.0 will provision version 1.0.1, but not 1.1.0
- compatible - dependent plug-in version must be at least at the version specified, or at a higher service level or minor level (major version level must equal the specified version).
Sample: ca xml with 1.0.0 will provision version 1.0.1 and 1.1.0, but not 2.0.0
- greaterOrEqual - dependent plug-in version must be at least at the version specified, or at a higher service, minor or major level.
Sample: ca xml with 1.0.0 will provision version 1.0.1, 1.1.0 and 2.0.0

A lot of choices are available using these match rules so you must decide upfront the upgrade scenario that best covers your situation. Ideally, all Eclipse component versions would be backwards compatible. If all applications could always use the latest version of the Eclipse components, you could always use the match criteria 'greaterOrEqual'. The client would then always check for a newer version than the one currently installed and update to the latest Eclipse component the next time users opened one of the applications using this Eclipse component.

If your application, however, requires a certain special version (for example: perfect version, equivalent or compatible) you need to be aware of the possible side effects to other applications using the same component but requiring different versions. For example if there are two applications (app1 and app2) that have both perfect match rules (app1 to comp1 version 1.0.0 and app2 to comp1 version 2.0.0) the client will always have to install the correct Eclipse version. Only one version of an Eclipse component can be installed at a time. So when a user opens "app1," version 1.0.0 is provisioned. When "app2" is opened, version 2.0.0 is provisioned. When the user then goes back to "app1," version 1.0.0 is provisioned again and 2.0.0 is uninstalled. To make matters worse, the client needs to be restarted between the opening of applications.

Because of this behavior, it might not be possible for you to use only new version numbers. Instead, you may have to actually use new plugins to make sure that you do not impact any existing applications. This and another option are described in the next two sections.

When using version numbers as just described, care should be taken when creating new versions of components to ensure that new functionality is a direct superset of existing functionality. If a property or action operated in a certain way in the old release, it must operate that same way in the new release. New features can be added, but great care should be taken when extending old features.

The key challenge to this approach is ensuring that old functionality is supported where you do not necessarily know all of the ways that a component has been used. Having a solid set of unit tests that can be applied to the old and new versions to ensure identical results is very important. Also advised are wide beta tests where new components are distributed to the application developer community and they are encouraged to test them out on applications and report back any inconsistencies.

The main benefit to this approach is that if strict backward compatibility is maintained then these components can just be rolled out in the production environment. Existing applications need no changes and the new versions will filter down to all the clients that use them. A drawback to this approach is that application developers cannot chose to "opt out" of a new release. If any application on a client's machine uses the updated component, all other applications on that machine will use that component.

Important: A known problem is that provisioning may not check for new versions of features/plugins when there is a match for a given matching rule already on the system. Currently, when an application is installed and provisioning has dependencies on a feature or features, the matching rule will be used to retrieve the highest/latest version available for a given feature that satisfies the matching rule.

Newer versions of that feature will not be downloaded unless the corresponding matching rule is updated in a way that does not match the currently installed version, but matches the updated version. This can be done by updating the client application via the Composite Application Editor. By opening the application in the Composite Application Editor and accessing the Advanced Component Properties, you can change the version number to the correct updated version number. Refer to the Composite Application Editor documentation for more information.

Additional information and guidelines when using match rules

The Lotus Expeditor documentation also covers how provisioning works for installing, updating, and uninstalling while using match rules as well as describes how and when updates sites will be searched. Refer to the "Using the provisioning interfaces to manage the platform" section in the Assembling and Deploying Lotus Expeditor Applications portion of the help (http://publib.boulder.ibm.com/infocenter/ledoc/v6r11/topic/com.ibm.rcp.tools.doc.admin/provisioningappusingProvisioninginterfaces.html)

In Lotus Expeditor, since the Composite Application Infrastructure (CAI) calls the XML provisioning APIs, provisioning behavior is essentially the same. First, a check is made on the system to see if a feature version that satisfies the matching rule is currently on the system. If so, there is no further checking of the update site(s) to see if a more recent version is available (that action would impact system performance).

The safest way to ensure the most recent plugin is provisioned on the system is to use the "perfect" matching rule when specifying the composite application feature dependencies. When specifying the feature dependencies for a composite application, the following information is required:

• Feature Id
• Feature version
• matching rule
• Provisioning URL

To ensure that the latest version that is supported by the composite application is provisioned, the following requirements must be in place:
1. The latest version must be added to the update site
2. The feature version in the composite application dependency must match the latest supported version. The updated version needs to be specified and the matching rule must be perfect. When Lotus Expeditor provisioning sees this combination, it checks to see if that version is available on the system. If it is not, it will download it from the update site.

Updating the CA.XML is the preferred way of getting the latest updates provisioned. This method is consistent with the rest of CAI provisioning. As a more convenient method, you can use the Lotus Expeditor Application Manager to check for updates since the CA.XML does not need to be updated. Refer to the "Updating applications" topic in the Using Lotus Expeditor Client portion of the help (http://publib.boulder.ibm.com/infocenter/ledoc/v6r11/topic/com.ibm.pvc.runtime.doc.user/tasks/user_device_updating_apps.html) This method, however, can bring down versions of updates for features and plugins that are not consistent with the CA.XML, which can result in your composite application not working.

As a final note, uninstalled features/plugins remain on the user's system after an uninstall action. They are removed after the client is restarted. This occurs due to some Eclipse restrictions.

Eclipse component updated via new plugins

A client can only maintain a single version of any component at any one time. Newer versions displace older versions. However if the component names are different, then the system sees them as two different components rather than two versions of one component. The simplest way to achieve this is to embed the version number of a component in the name of the component.

The benefit to this approach is that each application can exactly choose the version of the components it uses. When they are ready to upgrade they can indicate that the new component is to be used and that will filter down to the clients. Multiple applications can each use a separate version of the same component and each will be maintained on the client in parallel.

A drawback to this approach is that you may end up with many versions of each component on each client, for as long as they are in use by any application. If two applications use two different versions of one component, each will have to load the component. This can impact application launch times and total memory usage.

Eclipse component updated by maintaining two versions within a single component

In this approach, new versions of components are produced with the same name. Older versions will be displaced, but within the components themselves all of the old code base is maintained. Existing applications referring to the old entry points will get the old code and the old behavior. Applications that refer to the new entry points will get the newer versions. So each individual application cannot opt out of the new code being downloaded, but they can choose to accept or reject the new functionality.

The benefit to this approach is that you can get the automatic updates but minimize the potential impact of that new code to your application. A drawback to this approach is that a large part of the code base is still being touched; particularly if the change is in a deeper routine that is used commonly across many components.

Choosing the best update option

To summarize this section, you need to choose the update strategy that is right for you. The options described here each have their own "pros and cons." One method of assessment is to examine the importance of the various composite applications you use. If you have many composite applications that are critical for your business, than downtime can lead to important revenue loss. If a more common model is their use as information extensions to existing applications, then downtime just results in a loss of productivity.

Another factor to look at is the size of the user base for your composite applications. If they are used throughout your enterprise, are on everyone's desktop and used daily, then their importance is high. If they are used mostly in situational applications that are most often just deployed to individual desktops, then disturbance from change will be less critical.

Lastly, you might ask how risk averse you are as an organization. If your administration resources are in-house and are frequently involved in Notes application development, then the skills for dealing with any arising issues are immediately at hand. If you contract out your system and application administration, then more care needs to be taken.

Table of Contents | Next | Previous