Eclipse Platform
Release 3.6

org.eclipse.equinox.p2.engine.spi
Class Touchpoint

java.lang.Object
  extended by org.eclipse.equinox.p2.engine.spi.Touchpoint

public abstract class Touchpoint
extends Object

A touchpoint is responsible for executing the required provisioning steps for each phase corresponding to a particular targeted system (eclipse, native). The order of phases is defined in the IPhaseSet.

Since:
2.0

Constructor Summary
Touchpoint()
           
 
Method Summary
 IStatus commit(IProfile profile)
          This method is called at the end of an engine operation after all phases have been executed.
 IStatus completeOperand(IProfile profile, Map<String,Object> parameters)
          This method is called at the end of processing of a single engine operand (for example a given installable unit being installed or uninstalled).
 IStatus completePhase(IProgressMonitor monitor, IProfile profile, String phaseId, Map<String,Object> parameters)
          This method is called at the end of execution of an engine phase.
 IStatus initializeOperand(IProfile profile, Map<String,Object> parameters)
          This method is called at the beginning of processing of a single engine operand (for example a given installable unit being installed or uninstalled).
 IStatus initializePhase(IProgressMonitor monitor, IProfile profile, String phaseId, Map<String,Object> parameters)
          This method is called at the beginning of execution of an engine phase.
 IStatus prepare(IProfile profile)
          This method is called at the beginning of an engine operation before any phases have been executed.
 String qualifyAction(String actionId)
          This method is for backwards compatibility only, to be used by touchpoints that existed prior to action ids being fully qualified by the engine.
 IStatus rollback(IProfile profile)
          This method is called at the end of an engine operation after all phases have been executed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Touchpoint

public Touchpoint()
Method Detail

qualifyAction

public String qualifyAction(String actionId)
This method is for backwards compatibility only, to be used by touchpoints that existed prior to action ids being fully qualified by the engine.

Parameters:
actionId - the unqualified action id
Returns:
the qualified action id
Restriction:
This method is not intended to be referenced by clients.

initializePhase

public IStatus initializePhase(IProgressMonitor monitor,
                               IProfile profile,
                               String phaseId,
                               Map<String,Object> parameters)
This method is called at the beginning of execution of an engine phase. This is an opportunity for the touchpoint to initialize any phase-specific structures.

The result of this method can be used to abort execution of the entire engine operation, by using a severity of IStatus.ERROR or IStatus.CANCEL. The result can also contain warnings or informational status that will be aggregated and returned to the caller of IEngine.perform(org.eclipse.equinox.p2.engine.IProvisioningPlan, IProgressMonitor).

Parameters:
monitor - a progress monitor, or null if progress reporting and cancellation are not desired
profile - the profile that is being operated on
phaseId - the id of the phase
parameters - data provided by the engine to the touchpoint
Returns:
the result of phase initialization

completePhase

public IStatus completePhase(IProgressMonitor monitor,
                             IProfile profile,
                             String phaseId,
                             Map<String,Object> parameters)
This method is called at the end of execution of an engine phase. This is an opportunity for the touchpoint to clean up any phase-specific structures or perform any final work for the current phase.

The result of this method can be used to abort execution of the entire engine operation, by using a severity of IStatus.ERROR or IStatus.CANCEL. The result can also contain warnings or informational status that will be aggregated and returned to the caller of IEngine.perform(org.eclipse.equinox.p2.engine.IProvisioningPlan, IProgressMonitor).

Parameters:
monitor - a progress monitor, or null if progress reporting and cancellation are not desired
profile - the profile that is being operated on
phaseId - the id of the phase
parameters - data provided by the engine to the touchpoint
Returns:
the result of phase completion

initializeOperand

public IStatus initializeOperand(IProfile profile,
                                 Map<String,Object> parameters)
This method is called at the beginning of processing of a single engine operand (for example a given installable unit being installed or uninstalled). This is an opportunity for the touchpoint to initialize any data structures specific to a single operand.

The result of this method can be used to abort execution of the entire engine operation, by using a severity of IStatus.ERROR or IStatus.CANCEL. The result can also contain warnings or informational status that will be aggregated and returned to the caller of IEngine.perform(org.eclipse.equinox.p2.engine.IProvisioningPlan, IProgressMonitor).

Parameters:
profile - the profile that is being operated on
parameters - data provided by the engine to the touchpoint
Returns:
the result of initialization

completeOperand

public IStatus completeOperand(IProfile profile,
                               Map<String,Object> parameters)
This method is called at the end of processing of a single engine operand (for example a given installable unit being installed or uninstalled). This is an opportunity for the touchpoint to clean up any data structures specific to a single operand.

The result of this method can be used to abort execution of the entire engine operation, by using a severity of IStatus.ERROR or IStatus.CANCEL. The result can also contain warnings or informational status that will be aggregated and returned to the caller of IEngine.perform(org.eclipse.equinox.p2.engine.IProvisioningPlan, IProgressMonitor).

Parameters:
profile - the profile that is being operated on
parameters - data provided by the engine to the touchpoint
Returns:
the result of the completion work

prepare

public IStatus prepare(IProfile profile)
This method is called at the beginning of an engine operation before any phases have been executed. This is an opportunity to perform precondition checks against the profile, or initialize any data structures common to an entire execution of the engine.

The result of this method can be used to abort execution of the entire engine operation, by using a severity of IStatus.ERROR or IStatus.CANCEL. The result can also contain warnings or informational status that will be aggregated and returned to the caller of IEngine.perform(org.eclipse.equinox.p2.engine.IProvisioningPlan, IProgressMonitor).

Parameters:
profile - the profile about to be modified
Returns:
the result of preparation work

commit

public IStatus commit(IProfile profile)
This method is called at the end of an engine operation after all phases have been executed. When this method is invoked, it signals that the engine operation was a complete success, and the touchpoint should commit or persistent any changes it has made to some persistent storage (for example the file system).

The result of this method can be used to report on the success or failure of the commit. However, at this point it is too late for the engine operation to fail, and the result returned from this method will not prevent the engine from completing its work.

Parameters:
profile - the profile that was modified
Returns:
the result of commit work

rollback

public IStatus rollback(IProfile profile)
This method is called at the end of an engine operation after all phases have been executed. When this method is invoked, it signals that the engine operation was a failure, and the touchpoint should discard any changes it has made.

The result of this method can be used to report on the success or failure of the rollback. However, at this point it is too late for the engine operation to be stopped, and the result returned from this method will not prevent the engine from completing its rollback work.

Parameters:
profile - the profile that was modified
Returns:
the result of commit work

Eclipse Platform
Release 3.6

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2010. All rights reserved.