| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html lang="en"> |
| <head> |
| <meta name="copyright" |
| content="Copyright (c) IBM Corporation and others 2010, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <link REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" |
| TYPE="text/css"> |
| <title>Provisioning Actions and Touchpoints</title> |
| </head> |
| <body> |
| <h1>Provisioning Actions and Touchpoints</h1> |
| <h2>Introduction</h2> |
| <p>A p2 Installable Unit (IU) is installed using the facilities |
| provided by a <i>touchpoint</i>. 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.</p> |
| <p>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.</p> |
| <h2>Actions</h2> |
| <h3>Fully Qualified Action Names and Importing Actions</h3> |
| <p>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.</p> |
| Most bundle IUs use the Eclipse touchpoint type so you may be able to |
| use: |
| <table> |
| <tr> |
| <td><pre> installBundle(bundle:${artifact}) |
| </pre></td> |
| </tr> |
| </table> |
| However, if you get an error such as the following, use the fully |
| qualified name. |
| <table> |
| <tr> |
| <td><pre>java.lang.IllegalArgumentException: No action found for: installBundle. |
| </pre></td> |
| </tr> |
| </table> |
| A valid call of this action using FQN might be something like: |
| <table> |
| <tr> |
| <td><pre> org.eclipse.equinox.p2.touchpoint.eclipse.installBundle(bundle:${artifact}) |
| </pre></td> |
| </tr> |
| </table> |
| <h3>Native Touchpoint Actions</h3> |
| <p><b>Action Fully Qualified Name:</b></p> |
| <pre>org.eclipse.equinox.p2.touchpoint.natives.<i>action_name</i> |
| </pre> |
| <table border="1" cellpadding="5" style="border: 1px solid #CCC; border-collapse: collapse;"> |
| |
| <tr valign="top" style="background-color: #eeeeee; color: #444444;"> |
| <td><b>action</b></td> |
| <td><b>parameters</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">collect</td> |
| <td>-</td> |
| <td>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.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold">cleanupzip |
| </td> |
| <td><code>source, target</code></td> |
| <td>removes unzipped files and directories that where unzipped |
| from <i>source</i> into <i>target</i> - i.e. an "undo operation" of an |
| <i>unzip</i> instruction.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">unzip</td> |
| <td>source, target</td> |
| <td>unzips the <i>source</i> into the <i>target</i> directory. |
| The <i>source</i> can be the special value <code>@artifact</code>, |
| which denotes the download cache location for the first artifact |
| key in the installable unit.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">mkdir</td> |
| <td>path</td> |
| <td>Creates the directory specified by the parameter <i>path</i>. |
| </td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">rmdir</td> |
| <td>path</td> |
| <td>Removes the directory specified by the parameter <i>path</i>. |
| Action has no effect if the referenced directory contains files. Use |
| the <i>remove</i> action for a forced recursive remove.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">ln</td> |
| <td>targetDir, linkTarget, |
| linkName, force</td> |
| <td>Performs the system action <code>ln -s</code> with the |
| parameters <i>linkTarget</i> being the source-file, <i>targetDir</i> |
| is the directory where the symbolic link will be created, and <i>linkName</i> |
| is the name of the resulting link in the <i>targetDir</i>. The <i>force</i> |
| 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. |
| <p><em>This action is not available on platforms that do not have this command(i.e. Windows)</em></p> |
| </td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">chmod</td> |
| <td>targetDir, targetFile, |
| permissions, options</td> |
| <td>Changes permission on a file using the system <code>chmod</code> command. |
| The <i>targetDir</i> parameter is either a path, or the special <code>@artifact</code> |
| which is a reference to the directory where the first artifact |
| included in the installable unit is located. The parameter <i>targetFile</i> |
| is the name of a file, and <i>permissions</i> is written like for the |
| <i>chmod</i> 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). |
| <p><em>This is not available on platforms that do not have this command (i.e. Windows)</em></p> |
| </td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">remove</td> |
| <td>path</td> |
| <td>Removes a file, or a directory (and all files under this |
| directory) as referenced by the parameter <i>path</i>. |
| <p><br> |
| (Since 3.5)</p> |
| </td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">copy</td> |
| <td>source, target, overwrite</td> |
| <td>Copies a file or a directory (and all of its content) denoted |
| by <i>source</i> path to the <i>target</i> path. |
| <p>The boolean flag <i>overwrite</i> should be set to <i>true</i> |
| if the copy action should overwrite existing files. If overwrite is <i>false</i> |
| the operation will fail with an IO error in the files already exists. |
| <br> |
| (Since 3.5)</p> |
| </td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">cleanupcopy |
| </td> |
| <td>source, target</td> |
| <td>Cleans up what was installed earlier with a <i>copy</i> from |
| <i>source</i> to <i>target</i>. I.e. this is an "undo" of a <i>copy</i> |
| operation. |
| <p><br> |
| (Since 3.5)</p> |
| </td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">checkAndPromptNativePackage |
| </td> |
| <td>distro, package, [comparator, version]</td> |
| <td>Prompt the user for the package identified if it is not already installed. <i>distro</i> identifies a distribution for which the package is applicable. <i>package</i> is the package identifier as known by the OS. <i>version</i> an optional string capturing the expected version of the package. <i>comparator</i> an optional string from <i>eq, gt, ge, lt, le</i> 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. |
| <p>Example: |
| <pre> |
| org.eclipse.equinox.p2.touchpoint.natives.checkAndPromptNativePackage(distro:debian,package:sudo); |
| </pre> |
| or |
| <pre> |
| org.eclipse.equinox.p2.touchpoint.natives.checkAndPromptNativePackage(distro:debian,package:handbrake,comparator:ge,version:0.9); |
| </pre></p> |
| <p>(Since 4.5)</p> |
| </td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">checkAndPromptNativePackageWindowsRegistry |
| </td> |
| <td>package, key, [attributeName, attributeValue, downloadLink, version]</td> |
| <td>Prompt the user for the Windows library identified in the Windows registry if it is not already installed. <i>package</i> is a descriptive library identifier. <i>version</i> an descriptive version string. <i>key</i> is the full registry key. <i>attributeName</i> and <i>attributeValue</i> are an optional name and value of a registry attribute to check. <i>downloadLink</i> is a an optional URL to show in the UI from where the library can be obtained. |
| <p>Example: |
| <pre> |
| 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); |
| </pre></p> |
| <p>(Since 4.5)</p> |
| </td> |
| </tr> |
| </table> |
| <h3>Eclipse Touchpoint Actions</h3> |
| <p><b>Action Fully Qualified Name:</b></p> |
| <pre>org.eclipse.equinox.p2.touchpoint.eclipse.<i>action_name</i> |
| </pre> |
| <table border="1" cellpadding="5" style="border: 1px solid #CCC; border-collapse: collapse;"> |
| |
| <tr valign="top" style="background-color: #eeeeee; color: #444444;"> |
| <td><b>instruction</b></td> |
| <td><b>parameters</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">collect</td> |
| <td>-</td> |
| <td>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.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">installBundle |
| </td> |
| <td>bundle</td> |
| <td>Installs a bundle artifact specified by the parameter <i>bundle</i> |
| </td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">uninstallBundle |
| </td> |
| <td>bundle</td> |
| <td>Uninstalls a bundle artifact with a bundle-id specified by |
| the paramter <i>bundle</i></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">addSourceBundle |
| </td> |
| <td>bundle</td> |
| <td>Installs a source bundle artifact with the bundle-id |
| specified by the parameter <i>bundle</i></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">removeSourceBundle |
| </td> |
| <td>bundle</td> |
| <td>Removes/uninstalls the source bundle artifact with the |
| bundle-id specified by the parameter <i>bundle</i></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">installFeature |
| </td> |
| <td>feature, featureId, version</td> |
| <td>Installs the feature referenced by the parameter <i>feature</i> |
| (matched against artifacts in the iu). The feature is installed with |
| the id specified by the parameter <i>featureId</i>, or if this |
| parameter has the value <code>default</code>, with the id specified in |
| the artifact referenced by <i>feature</i>. The features is installed |
| with the version specified in <i>version</i>, or with the version |
| specified in the artifact referenced by the <i>feature</i> parameter |
| if the <i>version</i> parameter has the value <code>default</code></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">uninstallFeature |
| </td> |
| <td>feature, featureId, version</td> |
| <td>Uninstalls a feature. Parameters have the same meaning as for |
| the command <code>installFeature</code></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">setLauncherName |
| </td> |
| <td>name</td> |
| <td>Sets the name of the launcher to <code>name</code>. The |
| launcher name is used to configure launcher name specific ini files.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">addProgramArg |
| </td> |
| <td>programArg</td> |
| <td>Adds the string specified in the parameter <i>programArg</i> |
| as an argument to the program. If the parameter is the special value |
| <code>@artifact</code>, the location of the artifact referenced by the |
| first artifact key in the IU is used as the parameter value.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">removeProgramArg |
| </td> |
| <td>programArg</td> |
| <td>Removes the program argument specified in the string <i>programArg</i> |
| - if the parameter is the special value <code>@artifact</code>, the |
| location of the artifact referenced by the first artifact key in the |
| IU is used as the parameter value.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">setStartLevel |
| </td> |
| <td>startLevel</td> |
| <td>Sets the start level to the integer value specified in the |
| parameter <i>startValue</i></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">markStarted |
| </td> |
| <td>started</td> |
| <td>Marks the bundle referenced by the first artifact key in the |
| installable unit as started or not started, as controlled by the boolean parameter <i>started</i>. |
| A parameter value of "true" will mark the bundle as started and "false" will mark the bundle as not started).</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">setFrameworkDependentProperty |
| </td> |
| <td>propName, propValue</td> |
| <td>Sets the framework dependent property named <i>propName</i> |
| to the value specified in <i>propValue</i>. Framework dependent |
| properties are properties specific to the Equinox implementation of |
| the OSGi framework.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">setFrameworkIndependentProperty |
| </td> |
| <td>propName, propValue</td> |
| <td>Sets the framework independent property named <i>propName</i> |
| to the value specified in <i>propValue</i>. Framework independent |
| properties do not specifically target Eclipse and are generally |
| applicable to other OSGi frameworks.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">addProgramProperty |
| </td> |
| <td>propName, propValue</td> |
| <td>Adds the given value specified in <i>propValue</i> to the program |
| property named <i>propName</i>. 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.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">removeProgramProperty |
| </td> |
| <td>propName, propValue</td> |
| <td>Remove the given value specified in <i>propValue</i> from the program |
| property named <i>propName</i>. 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.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">setProgramProperty |
| </td> |
| <td>propName, propValue</td> |
| <td>Sets the program property named <i>propName</i> to the value |
| specified in <i>propValue</i>. Program properties are used by the |
| executable program to among other things locate the jars needed to |
| start Eclipse.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">addJvmArg |
| </td> |
| <td>jvmArg</td> |
| <td>Adds the string specified in the parameter <i>jvmArg</i> to |
| the arguments passed to the JVM.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">removeJvmArg |
| </td> |
| <td>jvmArg</td> |
| <td>Removes the string specified in the parameter <i>jvmArg</i> |
| from the arguments passed to the JVM.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">setJvm</td> |
| <td>jvm</td> |
| <td>Sets the JVM to be the path specified in the parameter <i>jvm</i>. |
| If a value of <i>null</i> is specified then the current JVM path value |
| is removed.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">checkTrust |
| </td> |
| <td>-</td> |
| <td>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.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">addRepository |
| </td> |
| <td>location, type, enabled</td> |
| <td>Adds the repository at <i>location</i> of type <i>type</i> to |
| the list of known repositories. The repository will then be available |
| when installing or updating the profile in the future. The <i>enabled</i> |
| parameter takes a boolean value ("true" or "false") indicating whether |
| the add repository should be enabled. The value of the <i>location</i> |
| parameter must be a well-formed URI. The <i>type</i> 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. |
| <p><i>Example:</i></p> |
| <pre>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); |
| </pre></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">removeRepository |
| </td> |
| <td>location, type</td> |
| <td>Removes the repository at <i>location</i> of type <i>type</i> |
| from the list of known |
| <p>repositories. The value of the <i>location</i> parameter must |
| be a well-formed URI. The <i>type</i> 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.</p> |
| </td> |
| </tr> |
| </table> |
| <h2>Action Format</h2> |
| <p>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 <i>statement-sequence</i>:</p> |
| <pre> statement-sequence : |
| | statement ';' |
| | statement-sequence statement |
| ; |
| </pre> |
| <p>Where a statement is of the format:</p> |
| <pre> statement : |
| | actionName '(' parameters ')' |
| ; |
| </pre> |
| <pre> parameters : |
| | // empty |
| | parameter |
| | parameters ',' parameter |
| ; |
| </pre> |
| <pre> parameter : |
| | paramName ':' paramValue |
| ; |
| |
| actionName, paramName, paramValue : |
| | String |
| ; |
| </pre> |
| <p>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) .</p> |
| <p>As an example - an "install" instruction for a bundle might |
| consist of the following statement:</p> |
| <pre> installBundle(bundle:${artifact}); |
| </pre> |
| <ul> |
| <li><i>installBundle</i> is the action name</li> |
| <li><i>bundle</i> is the parameter name</li> |
| <li><i>${artifact}</i> is the parameter value. The value |
| ${artifact} signifies the use of a pre-defined variable named |
| "artifact".</li> |
| </ul> |
| <h2>Built-in Action Variables</h2> |
| <p>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.</p> |
| <h3>Variables Available in all phases</h3> |
| <table border="1" cellpadding="5" style="border: 1px solid #CCC; border-collapse: collapse;"> |
| |
| <tr valign="top" style="background-color: #eeeeee; color: #444444;"> |
| <td><b>variable</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">#nnnn</td> |
| <td>the unicode value of a character. |
| <p><i>Note: This is especially important for the six |
| characters that require escaping.</i></p> |
| <ol> |
| <li>$ = ${#36}</li> |
| <li>, = ${#44}</li> |
| <li> : = ${#58}</li> |
| <li> ; = ${#59}</li> |
| <li>{ = ${#123}</li> |
| <li>} = ${#125}</li> |
| </ol> |
| </td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">profile</td> |
| <td>the profile being modified.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">phaseId</td> |
| <td>the name of the phase e.g. collect, install, etc.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">operand</td> |
| <td>the actions operand (e.g. IU pair)</td> |
| </tr> |
| </table> |
| <h3>Variables Available in all installable unit phases</h3> |
| <p><i>e.g. collect, unconfigure, uninstall, install, configure, |
| ...</i></p> |
| <table border="1" cellpadding="5" style="border: 1px solid #CCC; border-collapse: collapse;"> |
| |
| <tr valign="top" style="background-color: #eeeeee; color: #444444;"> |
| <td><b>variable</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">installFolder |
| </td> |
| <td>the root folder for this profile.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">touchpoint |
| </td> |
| <td>the touchpoint associated with the IUs in the operand if |
| applicable</td> |
| </tr> |
| </table> |
| <h3>Collect Phase Variables</h3> |
| <table border="1" cellpadding="5" style="border: 1px solid #CCC; border-collapse: collapse;"> |
| |
| <tr valign="top" style="background-color: #eeeeee; color: #444444;"> |
| <td><b>variable</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">artifactRequests |
| </td> |
| <td>A list that a touchpoints "collect" action will use to add |
| mirroring requests to.</td> |
| </tr> |
| </table> |
| <h3>Unconfigure Phase Variables</h3> |
| <table border="1" cellpadding="5" style="border: 1px solid #CCC; border-collapse: collapse;"> |
| |
| <tr valign="top" style="background-color: #eeeeee; color: #444444;"> |
| <td><b>variable</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">iu</td> |
| <td>The IU being unconfigured. This is set from the first IU of |
| the operand pair.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">artifact</td> |
| <td>The artifact id of the first artifact listed in the IU.</td> |
| </tr> |
| </table> |
| <h3>Uninstall Phase Variables</h3> |
| <table border="1" cellpadding="5" style="border: 1px solid #CCC; border-collapse: collapse;"> |
| |
| <tr valign="top" style="background-color: #eeeeee; color: #444444;"> |
| <td><b>variable</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">iu</td> |
| <td>The IU being uninstalled. This is set from the first IU of |
| the operand pair.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">artifact</td> |
| <td>The artifact id of the first artifact listed in the IU.</td> |
| </tr> |
| </table> |
| <h3>Install Phase Variables</h3> |
| <table border="1" cellpadding="5" style="border: 1px solid #CCC; border-collapse: collapse;"> |
| |
| <tr valign="top" style="background-color: #eeeeee; color: #444444;"> |
| <td><b>variable</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">iu</td> |
| <td>The IU being installed. This is set from the second IU of the |
| operand pair.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">artifact</td> |
| <td>The artifact id of the first artifact listed in the IU.</td> |
| </tr> |
| </table> |
| <h3>Configure Phase Variables</h3> |
| <table border="1" cellpadding="5" style="border: 1px solid #CCC; border-collapse: collapse;"> |
| |
| <tr valign="top" style="background-color: #eeeeee; color: #444444;"> |
| <td><b>variable</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">iu</td> |
| <td>The IU being configured. This is set from the second IU of |
| the operand pair.</td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">artifact</td> |
| <td>The artifact id of the first artifact listed in the IU.</td> |
| </tr> |
| </table> |
| <h3>Eclipse Touchpoint Variables</h3> |
| <table border="1" cellpadding="5" style="border: 1px solid #CCC; border-collapse: collapse;"> |
| |
| <tr valign="top" style="background-color: #eeeeee; color: #444444;"> |
| <td><b>variable</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">manipulator |
| </td> |
| <td>an instance of the Manipulator class used to alter the |
| configuration of an Eclipse install.</td> |
| </tr> |
| </table> |
| <h3>Native Touchpoint Variables</h3> |
| <table border="1" cellpadding="5" style="border: 1px solid #CCC; border-collapse: collapse;"> |
| |
| <tr valign="top" style="background-color: #eeeeee; color: #444444;"> |
| <td><b>variable</b></td> |
| <td><b>description</b></td> |
| </tr> |
| <tr valign="top"> |
| <td style="font-weight: bold;">backup</td> |
| <td>the BackupStore used to save transaction state during native |
| file operations.</td> |
| </tr> |
| </table> |
| <h2>Additional Notes on Backup for File Operation Actions</h2> |
| <p>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:</p> |
| <ul> |
| <li>It was not possible to restore files (probably because of |
| faulty hardware, running out of disk, or manual tampering with files |
| during the installation).</li> |
| <li>The system crashed during the install</li> |
| </ul> |
| <p>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.</p> |
| <p>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).</p> |
| <p>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.</p> |
| </body> |
| </html> |
