Expeditor Deployers: Controlling the feature install location

This section explains the available methods for controlling and specifying the target install site for a feature.

The platform provisioning system defines by default the following target sites into which features are installed:

rcp: Contains the features and plug-ins that are part of the Eclipse and client platform.
shared: Contains additional features and plug-ins intended for use by all users of the client platform.
“user”: Located in the workspace, this target site contains additional features and plug-ins intended for use only by a single user of the client platform.

The target install site for a particular feature is determined by evaluating several conditions, including whether the feature is currently installed, colocation-affinity, ability to write a specific directory, and requested target site.

Colocation-affinity is an attribute that can be specified by each feature in the feature.xml descriptor. The colocation-affinity attribute specifies the ID of another feature. It directs the provisioning system to attempt to install the new feature into the same target site that the other feature (the feature whose ID is specified in the feature.xml). Using the Feature Manifest Editor from the Plug-in Development Environment, the colocation-affinity can be specified on the Installation page of the editor.

For example, suppose that feature with an ID of com.ibm.sample has been installed into the shared site. A new feature with an ID of com.ibm.extendedsample can then specify a colocation-affinity of "com.ibm.sample” to request that the feature is installed into the same location as com.ibm.sample:

<feature
      id="com.ibm.extendedsample"
      label="Extendedsample Feature"
      version="1.0.0"
      provider-name="IBM"
      colocation-affinity="com.ibm.sample">

The platform provisioning system uses these decisions to determine the target site for a feature.

If a provisioning system detects a version of the feature that is already installed, the same install site will be used for any additional versions. This only applies when the feature has been installed into the Eclipse, RCP, or shared target sites.
If a deployer installs a feature X version 1.0.0 into the shared site, and later attempts to install feature X version 1.0.1, then version 1.0.1 will be installed into the shared site.

If a user A installs a feature Y into their user site in their workspace A, and later another user B attempts to install feature Y, feature Y will be installed a second time into the workspace B, since workspace A is not visible to user B.
If feature.xml specifies the colocation-affinity attribute, then the following decisions are made:
1. If the feature that was specified in the colocation-affinity attribute is installed, then attempt to install into that site. If that site is not accessible to the user installing the feature, the feature installation will fail.
2. If the feature that was specified in the colocation-affinity attribute is not installed, then continue with step 3 in the decision process.
If a specific target site is requested for the feature, then attempt to install the feature into this site. If that site is not accessible, then continue with step 5. A target site can be specified only for features distributed through the Eclipse feature distribution job using the Device Management server.
If the provisioning manifest or a ProvisioningRequest (provided through an API request) specifies shared = true, then the shared site is the desired target site for installing the feature. If that site is not accessible, then continue with step 5. (Refer to Provisioning manifest DTD for more information on the attributes available through the provisioning manifest.
If the provisioning manifest or a ProvisioningRequest object specifies shared = false, or if because of accessibility issues, the desired target sites for step 3 and step 4 are not available, then attempt to install the feature into the “user” site.

Since the colocation-affinity takes precedence over target site or shared attribute specification, specifying a colocation-affinity is the preferred model for controlling feature install locations. The client platform has defined the following features that can be used as targets for the colocation-affinity attribute:

com.ibm.rcp.site.anchor.shared.feature: This feature is always installed into the shared site.
com.ibm.rcp.site.anchor.user.feature: This feature is always installed into the user site.

If the platform is only ever used by a single user with a single workspace, then the target site for a feature is less important, since all features will always be available. In the multiuser configuration, the target install site becomes much more important, since some applications should be shared among all users of the platform, while other applications should be private to specific users.

As an example, assume a multiuser configuration in which deployers have admin rights to the shared directory, while ordinary users are limited to read-only rights. Feature W does not contain a colocation-affinity attribute. If a deployer attempts to install this feature, it will be installed into the shared directory, since this is the default option with no colocation-affinity and no target site specified. However, if a user attempted to install this feature, it would be installed into the user target site, and could not be shared by all users on the platform. The user site would be selected since the shared site is not accessible.

To limit the ability of a specific user to install feature W into their user site, the deployer could specify a colocation-affinity attribute with the ID “com.ibm.rcp.site.anchor.shared.feature”. The resultant site for a deployer would still be the shared site, chosen now not because it is the default, but because the colocation-affinity selects that site. A user attempting to install the feature would have the feature installation fail, since the site specified by the colocation affinity is not accessible.