# Provisioning Actions and Touchpoints

## Introduction

A p2 Installable Unit (IU) is installed using the facilities provided by a touchpoint. The IU metadata consists of a reference to the touchpoint (Touchpoint Type) which also defines the version of the touchpoint (i.e an expectancy that it supports a certain set of operations), and describes instructions to execute in various p2 engine phases. The instructions are named after the phases - the phases "install", "uninstall", "configure", "unconfigure" are of interest when authoring, but there are also some internal phases such as "collect" and "checktrust" executed by the engine. Each instruction (e.g. "install") describes a sequence of actions to execute on the referenced touchpoint. Examples of actions are: create and remove directories, change permissions, install and remove bundles. Currently, two touchpoints (native, and eclipse) have been implemented. The native touchpoint has approximately 5 different actions, and the eclipse touchpoint has approximately 20. Most of these actions take parameters.

The instructions are grouped and described in a Touchpoint Data Element. The touchpoint data element uses a Map where the key is the name of a p2 engine phase (such as "install"), and the value is a string representation of a sequence of actions. Using multiple touchpoint data elements is useful as it allows separation between sets of actions for install/uninstall/configure/unconfigure which makes it easier to maintain the meta data.

## Actions

### Fully Qualified Action Names and Importing Actions

Each action has a fully qualified name; for example "org.eclipse.equinox.p2.touchpoint.eclipse.installBundle" is the FQN for the Eclipse touchpoints "installBundle" action. One can use the short name of an action if the action is imported or if the IUs "touchpoint type" matches the action.

Most bundle IUs use the Eclipse touchpoint type so you may be able to use:

     installBundle(bundle:${artifact})

However, if you get an error such as the following, use the fully qualified name.

    java.lang.IllegalArgumentException: No action found for: installBundle.

A valid call of this action using FQN might be something like:

     org.eclipse.equinox.p2.touchpoint.eclipse.installBundle(bundle:${artifact})

### Native Touchpoint Actions

Action Fully Qualified Name:

    org.eclipse.equinox.p2.touchpoint.natives.action_name

action | parameters | description
collect | - | collects all associated artifacts for an IU and places them in a local touchpoint addressable cache. This action may be called explicitly during the collect phase but is typically called as the "default" action called for IUs with the Native Touchpoint Type as part of the main Collect and Sizing phases.
cleanupzip | `source, target` | removes unzipped files and directories that where unzipped from source into target - i.e. an "undo operation" of an unzip instruction.
unzip | source, target | unzips the source into the target directory. The source can be the special value `@artifact`, which denotes the download cache location for the first artifact key in the installable unit.
mkdir | path | Creates the directory specified by the parameter path.
rmdir | path | Removes the directory specified by the parameter path. Action has no effect if the referenced directory contains files. Use the remove action for a forced recursive remove.

ln

targetDir, linkTarget, linkName, force

Performs the system action `ln -s` with the parameters linkTarget being the source-file, targetDir is the directory where the symbolic link will be created, and linkName is the name of the resulting link in the targetDir. The force parameter is a boolean in string form (i.e. "true"/"false") and indicates if an existing link with the same name should be removed before the new link is created.

This action is not available on platforms that do not have this command(i.e. Windows)

chmod

targetDir, targetFile, permissions, options

Changes permission on a file using the system `chmod` command. The targetDir parameter is either a path, or the special `@artifact` which is a reference to the directory where the first artifact included in the installable unit is located. The parameter targetFile is the name of a file, and permissions is written like for the chmod system command. The options parameter allows passing additional options like "-R" for recursive operation. If multiple parameters are needed separate them with a space (like on the command line).

This is not available on platforms that do not have this command (i.e. Windows)

remove | path | Removes a file, or a directory (and all files under this directory) as referenced by the parameter path. (Since 3.5)
copy | source, target, overwrite | Copies a file or a directory (and all of its content) denoted by source path to the target path. The boolean flag overwrite should be set to true if the copy action should overwrite existing files. If overwrite is false the operation will fail with an IO error in the files already exists. (Since 3.5)
cleanupcopy | source, target | Cleans up what was installed earlier with a copy from source to target. I.e. this is an "undo" of a copy operation. (Since 3.5)

checkAndPromptNativePackage

distro, package, [comparator, version]

Prompt the user for the package identified if it is not already installed. distro identifies a distribution for which the package is applicable. package is the package identifier as known by the OS. version an optional string capturing the expected version of the package. comparator an optional string from eq, gt, ge, lt, le to express more specific dependencies on the version to install. Know that at this point only Ubuntu is supported, and we welcome support for other OS.

Example:

      org.eclipse.equinox.p2.touchpoint.natives.checkAndPromptNativePackage(distro:debian,package:sudo);

or

      org.eclipse.equinox.p2.touchpoint.natives.checkAndPromptNativePackage(distro:debian,package:handbrake,comparator:ge,version:0.9);

(Since 4.5)

checkAndPromptNativePackageWindowsRegistry

package, key, [attributeName, attributeValue, downloadLink, version]

Prompt the user for the Windows library identified in the Windows registry if it is not already installed. package is a descriptive library identifier. version an descriptive version string. key is the full registry key. attributeName and attributeValue are an optional name and value of a registry attribute to check. downloadLink is a an optional URL to show in the UI from where the library can be obtained.

Example:

      org.eclipse.equinox.p2.touchpoint.natives.checkAndPromptNativePackageWindowsRegistry(\
        package:MS VC Runtime,\
        version:2010,\
        key:HKLM\\SOFTWARE\\Wow6432Node\\Microsoft\\VisualStudio\\10.0\\VC\\VCRedist\\x64,\
        attributeName:Installed,\
        attributeValue:1,\
        downloadLink:http${#58}//www.microsoft.com/download/details.aspx?id=14632);

(Since 4.5)

### Eclipse Touchpoint Actions

Action Fully Qualified Name:

    org.eclipse.equinox.p2.touchpoint.eclipse.action_name

instruction | parameters | description
collect | - | collects all associated artifacts for an IU and places them in a local touchpoint addressable cache. This action may be called explicitly during the collect phase but is typically called as the "default" action called for IUs with the Eclipse Touchpoint Type as part of the main Collect and Sizing phases.
installBundle | bundle | Installs a bundle artifact specified by the parameter bundle
uninstallBundle | bundle | Uninstalls a bundle artifact with a bundle-id specified by the paramter bundle
addSourceBundle | bundle | Installs a source bundle artifact with the bundle-id specified by the parameter bundle
removeSourceBundle | bundle | Removes/uninstalls the source bundle artifact with the bundle-id specified by the parameter bundle

installFeature

feature, featureId, version

Installs the feature referenced by the parameter feature (matched against artifacts in the iu). The feature is installed with the id specified by the parameter featureId, or if this parameter has the value `default`, with the id specified in the artifact referenced by feature. The features is installed with the version specified in version, or with the version specified in the artifact referenced by the feature parameter if the version parameter has the value `default`

uninstallFeature | feature, featureId, version | Uninstalls a feature. Parameters have the same meaning as for the command `installFeature`
setLauncherName | name | Sets the name of the launcher to `name`. The launcher name is used to configure launcher name specific ini files.
addProgramArg | programArg | Adds the string specified in the parameter programArg as an argument to the program. If the parameter is the special value `@artifact`, the location of the artifact referenced by the first artifact key in the IU is used as the parameter value.
removeProgramArg | programArg | Removes the program argument specified in the string programArg - if the parameter is the special value `@artifact`, the location of the artifact referenced by the first artifact key in the IU is used as the parameter value.
setStartLevel | startLevel | Sets the start level to the integer value specified in the parameter startValue
markStarted | started | Marks the bundle referenced by the first artifact key in the installable unit as started or not started, as controlled by the boolean parameter started. A parameter value of "true" will mark the bundle as started and "false" will mark the bundle as not started).
setFrameworkDependentProperty | propName, propValue | Sets the framework dependent property named propName to the value specified in propValue. Framework dependent properties are properties specific to the Equinox implementation of the OSGi framework.
setFrameworkIndependentProperty | propName, propValue | Sets the framework independent property named propName to the value specified in propValue. Framework independent properties do not specifically target Eclipse and are generally applicable to other OSGi frameworks.
addProgramProperty | propName, propValue | Adds the given value specified in propValue to the program property named propName. The program property value is treated as a comma-separated list and the given value is added to that list. Program properties are used by the executable program to among other things locate the jars needed to start Eclipse.

removeProgramProperty

propName, propValue

Remove the given value specified in propValue from the program property named propName. The program property value is treated as a comma-separated list and the given value is removed from that list. If there are no more elements in the list, then the property itself is removed. Program properties are used by the executable program to among other things locate the jars needed to start Eclipse.

setProgramProperty | propName, propValue | Sets the program property named propName to the value specified in propValue. Program properties are used by the executable program to among other things locate the jars needed to start Eclipse.
addJvmArg | jvmArg | Adds the string specified in the parameter jvmArg to the arguments passed to the JVM.
removeJvmArg | jvmArg | Removes the string specified in the parameter jvmArg from the arguments passed to the JVM.
setJvm | jvm | Sets the JVM to be the path specified in the parameter jvm. If a value of null is specified then the current JVM path value is removed.
checkTrust | - | collects the set of bundle files on which the signature trust check should be performed. The checkTrust action is not meant to be user callable and is done as part of the CheckTrust phase.

addRepository

location, type, enabled

Adds the repository at location of type type to the list of known repositories. The repository will then be available when installing or updating the profile in the future. The enabled parameter takes a boolean value ("true" or "false") indicating whether the add repository should be enabled. The value of the location parameter must be a well-formed URI. The type parameter value must be the value of one of the IRepository.TYPE_* constants, Specifically, type "0" indicates a metadata repository, and type "1" indicates an artifact repository.

Example:

    instructions.configure=org.eclipse.equinox.p2.touchpoint.eclipse.addRepository(location:http${#58}//download.eclipse.org/birt/update-site/2.5/,type:0,name:BIRT 2.5,enabled:true); \
      org.eclipse.equinox.p2.touchpoint.eclipse.addRepository(location:http${#58}//download.eclipse.org/birt/update-site/2.5/,type:1,name:BIRT 2.5,enabled:true);

removeRepository | location, type | Removes the repository at location of type type from the list of known repositories. The value of the location parameter must be a well-formed URI. The type parameter value must be the value of one of the IRepository.TYPE_* constants, Specifically, type "0" indicates a metadata repository, and type "1" indicates an artifact repository.

## Action Format

The Touchpoint Data Element has a Map that describes the actions to execute in the various p2 engine phases (e.g. "install", "uninstall", "configure", "unconfigure", "collect" and "checktrust"). The key of the Map entry is the name of a phase (i.e. when the actions should be executed), and the value is a statement-sequence:

      statement-sequence :
          | statement ';'
          | statement-sequence statement
          ;

Where a statement is of the format:

      statement :
          | actionName '(' parameters ')'
          ;

      parameters :
          | // empty
          | parameter
          | parameters ',' parameter
          ;

       parameter :
          | paramName ':' paramValue
          ;

     actionName, paramName, paramValue :
          | String
          ;

In the p2 engine, the Phase will lookup the "actionName" using it's own phase specific actions (e.g. "collect") and also those made available by the associated touchpoint (e.g. "mkdir" in the native touchpoint, and "installBundle" in the Eclipse touchpoint) .

As an example - an "install" instruction for a bundle might consist of the following statement:

      installBundle(bundle:${artifact});

- installBundle is the action name
- bundle is the parameter name
- ${artifact} is the parameter value. The value ${artifact} signifies the use of a pre-defined variable named "artifact".

## Built-in Action Variables

What follows is a catalog of the variables made available by the phases and touchpoints. Many of these are mostly useful to the implementor of new actions and touchpoint types.

### Variables Available in All Phases

variable | description

#nnnn

the unicode value of a character.

Note: This is especially important for the six characters that require escaping.

1. $ = ${#36}
2. , = ${#44}
3. : = ${#58}
4. ; = ${#59}
5. { = ${#123}
6. } = ${#125}

profile | the profile being modified.
phaseId | the name of the phase e.g. collect, install, etc.
operand | the actions operand (e.g. IU pair)

### Variables Available in All Installable Unit Phases

e.g. collect, unconfigure, uninstall, install, configure, ...

variable | description
installFolder | the root folder for this profile.
touchpoint | the touchpoint associated with the IUs in the operand if applicable

### Collect Phase Variables

variable | description
artifactRequests | A list that a touchpoints "collect" action will use to add mirroring requests to.

### Unconfigure Phase Variables

variable | description
iu | The IU being unconfigured. This is set from the first IU of the operand pair.
artifact | The artifact id of the first artifact listed in the IU.

### Uninstall Phase Variables

variable | description
iu | The IU being uninstalled. This is set from the first IU of the operand pair.
artifact | The artifact id of the first artifact listed in the IU.

### Install Phase Variables

variable | description
iu | The IU being installed. This is set from the second IU of the operand pair.
artifact | The artifact id of the first artifact listed in the IU.

### Configure Phase Variables

variable | description
iu | The IU being configured. This is set from the second IU of the operand pair.
artifact | The artifact id of the first artifact listed in the IU.

### Eclipse Touchpoint Variables

variable | description
manipulator | an instance of the Manipulator class used to alter the configuration of an Eclipse install.

### Native Touchpoint Variables

variable | description
backup | the BackupStore used to save transaction state during native file operations.

## Additional Notes on Backup for File Operation Actions

The Native Touchpoint stores a temporary backup of files that are deleted or overwritten during the installation process. If an installation succeeds the backup is simply removed. If however the installation fails, the files in backup are restored to their original location. If the restore works as expected, the backup copy is also removed. Two "disaster" cases remain:

- It was not possible to restore files (probably because of faulty hardware, running out of disk, or manual tampering with files during the installation).
- The system crashed during the install

The backup is placed in a directory under the directory referenced by the system property "java.io.tmpdir". The backup directory has a name with the prefix ".p2bu" which is followed by a unique key per running backup instance. Under the ".p2bu..." directory files are stored in a hierarchy that reflects their original location.

In both of the disaster cases, the backup store under java.io.tempdir will contain copies of all files that were not automatically restored. If a restore is wanted, this can be performed manually by copying the content back to their original position (which is evident from the structure under ".p2bu"). This can be made with tools like zip (simply zip everything relative to .p2bu, and then unzip it from the real file system root).

In case something goes wrong during restore of a backup, the event is logged with details of what needs to be manually restored. This is best effort support so in the case of a system crash file loss is possible.