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.
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})
|
java.lang.IllegalArgumentException: No action found for: installBundle. |
org.eclipse.equinox.p2.touchpoint.eclipse.installBundle(bundle:${artifact})
|
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.
|
| 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.
|
| 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.
|
| 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) |
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. |
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});
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.
| variable | description |
| #nnnn | the unicode value of a character.
Note: This is especially important for the six characters that require escaping.
|
| profile | the profile being modified. |
| phaseId | the name of the phase e.g. collect, install, etc. |
| operand | the actions operand (e.g. IU pair) |
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 |
| variable | description |
| artifactRequests | A list that a touchpoints "collect" action will use to add mirroring requests to. |
| 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. |
| 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. |
| 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. |
| 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. |
| variable | description |
| manipulator | an instance of the Manipulator class used to alter the configuration of an Eclipse install. |
| variable | description |
| backup | the BackupStore used to save transaction state during native file operations. |
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:
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.