Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Equinox/p2/Engine

Overview

  • The p2 Engine is the component that supports modification to the contents of an installation profile.
  • Key Concepts:
    • Profile - Concrete model of an installation (e.g. install directory and the specific IUs installed)
    • PhaseSet - The collection of in order phases that will be carried out during a call to the Engine.
    • Phase - Phases are typically named to collect similar operations together. For example the "install" phase.
    • Operand - A pair of IUs used to represent (before, after) state. The phases use operands to determine what actions to carry out.
    • Touchpoint - Each IU is associated with a touchpoint which identify for what type of product it's for. For example the bundles for Eclipse are associated with the Eclipse touchpoint.
    • Action - Actions are the unit of work done by the Engine and are used to modify the contents of a profile

Engine API

The primary means of interaction is through the perform method:

 public MultiStatus perform(Profile profile, PhaseSet phaseSet, 
                                       Operand[] operands, IProgressMonitor monitor)
  • profile is the Profile you want to modify
  • phaseSet provides the set of Phase(s) that you want the engine to run through
  • operands is the set of IU pairs you want to operate over
  • monitor is used to provide incremental status feedback.

Each call to the engine is atomic - either all changes happen or in the event of failure no changes occur. To the caller this is indicated by the MultiStatus object returned - OK signals success, ERROR signals a failure.

Usage

Using a custom PhaseSet is supported but in most cases an instance of the "DefaultPhaseSet" should be used for installation operations. The DefaultPhaseSet is made up of the following in-order Phases:

  • Collect is used to mirror any artifacts identified in the IUs so that they are available for later steps in the installation.
  • Unconfigure is used to remove the configuration information for an IU from the profile or touchpoint specific locations.
  • Uninstall removes the IU from the profile and performs any actions required to remove it from the touchpoint.
  • Install adds the IU to the profile and performs any of the actions required by the touchpoint to perform and installation
  • Configure is used to perform any configuration steps required for the IU.

Each Phase is responsible for determining the appropriate Actions to execute for a particular operand. The collect phase has an implicit behaviour to download the associated artifacts. The unconfigure, uninstall, install, and configure Phases will all look for "instructions" in the touchpoint data section with the same name. For example during the "install" phase the IU's touchpoint data section is queried for "install" instructions.

The format for the instruction section is as follows:

  actionName( paramName1 : paramValue1, paramName2 : paramValue2, paramName3 : paramValue3);

An instruction may contain multiple action statements. The Phase will lookup the "actionName" using it's own phase specific actions and also those made available by the associated touchpoint. For example the set of "install" instructions for a bundle might consist of the following:

  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".

Actions and Parameters

What follows is a catalog of the actions and the parameters they accept made available by the phases and touchpoints.

Touchpoints

Eclipse Touchpoint:

  • addJvmArg
    • jvmArg - the JVM Argument to add
  • removeJvmArg
    • jvmArg - the JVM Argument to remove
  • addProgramArg
    • programArg - the program argument to add
  • removeProgramArg
    • programArg - the program argument to remove
  • collect
    • (called implicitly during the "Collect" phase)
  • installBundle
    • bundle - the artifact id of the bundle to install
  • uninstallBundle
    • bundle - the artifact id of the bundle to uninstall
  • markStarted
    • started - true/false value to determine if the bundle should be marked persistently started
  • setFwDependentProp
    • propName - The name of the property to set
    • propValue - The desired value of the property
  • setFwIndependentProp
    • propName - The name of the property to set
    • propValue - The desired value of the property

Native Touchpoint

  • chmod
    • targetFile - the file that needs its permissions adjusted
    • targetDir - the folder that contains the file
    • permissions - the new permissions
  • collect
    • (called implicitly during the "Collect" phase)
  • unzip
    • source - the location of the zip file
    • target - the target folder where the zip file should be unzipped

Variables

What follows is a catalog of the actions and variables made available by the phases and touchpoints.

Phases

All Phases:

  • profile - the profile being modified
  • phaseId - the name of the phase e.g. collect, install, etc.
  • operand - the actions operand (e.g. IU pair)
  • touchpoint - the touchpoint associated with the IUs in the operand

Collect Phase:

  • artifactRequests - A list that a touchpoints "collect" action will use to add mirroring requests to.

Unconfigure Phase:

  • iu - The IU being unconfigured. This is the first/before IU of the operand.
  • artifact - The artifact id of the first artifact listed in the IU.

Uninstall Phase:

  • iu - The IU being uninstalled. This is the first/before IU of the operand.
  • artifact - The artifact id of the first artifact listed in the IU.

Install Phase:

  • iu - The IU being installed. This is the second/after IU of the operand.
  • artifact - The artifact id of the first artifact listed in the IU.

Configure Phase:

  • iu - The IU being configured. This is the second/after IU of the operand.
  • artifact - The artifact id of the first artifact listed in the IU.

Touchpoints

Eclipse Touchpoint:

  • manipulator - an instance of the Manipulator class used to alter the configuration of an Eclipse install.
  • installFolder - the root folder for this profile

Native Touchpoint

  • installFolder - the root folder for this profile


Extra Notes

(Be aware that much of this discussion is out of date)

  • Is the engine only invoked for provisioning related operations? For example could it be used to obtain the log file of a particular touchpoint.
    • For now the answer is no. The engine is only used for provisioning related operations that cause modification of the set of IUs installed in a profile.
  • Some additonal operations that we *might* need to invoke on the engine. Current thinking is that introspection operations should occur outside of the scope of an Engine session. We have not dug too deeply here so this might change.
    • Reboot the targeted touchpoint.
    • Compute the size of things being downloaded. It would invoke the touchpoint to actually know whether or not the IU should be obtained.
    • Validation of checks contained in IUs
    • Qualification, for example discovery of an eclipse install
  • Engine API:
    • The OSGi DMT Admin service has an interesting API that we should mimic. Specifically DMTAdmin.getSession
      • A mapping of some of the DMT Admin concepts would require us to look at the API as acting on a single profile instead of a sub-tree.
      • The DMT Admin service has the concept of a DMTSession for holding the current state for deployment activity. This might be useful internally to track transactional state. It's not clear yet if we want to expose the transactionactional state in the public API however we should leave that option open.
    • The parameters passed to the engine do not give us flexibility for other operations than Install and Uninstall. {Done}
      • We still want to keep this grammar as small as possible: install / update / uninstall until we have concrete requirements for more operations.
      • We're currently passing a "single" operation and set of operands. We should move to a model where we pass a set of operations with internal operands. This allows us to "perform" a mixture of the various operations in a single call to the Engine.
      • The scope of an Engine "perform" command is a single profile and only one Engine provisioning session should be active on a profile at one time. This has some consequences for transactions that we will need to think about.
  • Engine processing model and phases:
    • The engine is built on a model where there is a "fixed" set of phases
    • When running a partiuclar set of operations each operation is in turn asked if it will participate in a particular phase.
    • Currently the processing is done breadth first, in that first all the IUs are being fetched, then they are all installed and finally configured (where fetch, install, and configure are phases). Is that too strict? Should we allow for some phases to specify how they should be run?
    • One benefit of breadth first is that ordering of operations is no longer a problem however the phase ordering is static.
    • Depth first more or less has the opposite characteristics where we have greater control of the ordering of phases that make up an operation however this is at the expense of greater complexity in terms of ordering a set of provisioning operations.
    • A first try at an in-order set of phases is as follows:
      • collect
      • validate
      • uninstall / unconfigure
      • update / migrate
      • install / initconfig
      • configure
      • verify
  • Operations / Phases / Actions:
    • Phase-data is represented in an IUs touchpoint data. An IU's phase-data will eventually consist of a series of atomic "actions". The actual definition of actions should probable be declarative. Currently this is done in JavaScript.
    • Our mapping of operations to phases is as follows.
      • Install - Collect, Validate, Install / InitConfig, Configure, Verify.
      • Update - Collect, Validate, Update / Migrate, Configure, Verify.
      • Uninstall - Validate, Uninstall / UnConfigure, Verify.

Back to the top