Package org.eclipse.equinox.p2.operations

# Class ProfileChangeOperation

java.lang.Object
org.eclipse.equinox.p2.operations.ProfileChangeOperation

All Implemented Interfaces:
  `IProfileChangeJob`

Direct Known Subclasses:
  `InstallOperation`, `RemediationOperation`, `UninstallOperation`, `UpdateOperation`

public abstract class ProfileChangeOperation extends Object implements IProfileChangeJob
ProfileChangeOperation describes a provisioning operation that modifies a profile. The operation must first be resolved, followed by the actual provisioning work being performed. This two-pass nature of the ProfileChangeOperation allows resolution status to be reported to a client to determine whether the operation should proceed. Each phase of the operation can be performed synchronously or in the background as a job. To perform the operation synchronously:

         IStatus result = op.resolveModal(monitor);
         if (result.isOK())
           op.getProvisioningJob(null).runModal(monitor);
         else {
           // interpret the result
         }

To perform the resolution synchronously and the provisioning job in the background:

         IStatus status = op.resolveModal(monitor);
         if (status.isOK()) {
           ProvisioningJob job = op.getProvisioningJob(monitor);
           job.schedule();
         } else {
           // interpret the result
         }

To resolve in the background and perform the job when it is complete:

         ProvisioningJob job = op.getResolveJob(monitor);
         job.addJobChangeListener(new JobChangeAdapter() {
           public void done (JobChangeEvent event) {
             if (event.getResult().isOK() {
                op.getProvisioningJob(monitor).schedule();
             } else {
                // interpret the result
             }
           }
         });
         job.schedule();

In general, it is expected that clients create a new ProfileChangeOperation if the resolution result of the current operation is not satisfactory. However, subclasses may prescribe a different life cycle where appropriate. When retrieving the resolution and provisioning jobs managed by this operation, a client may supply a progress monitor to be used by the job. When the job is run by the platform job manager, both the platform job manager progress indicator and the monitor supplied by the client will be updated.

Since:
  2.0
Restriction:
  This class is not intended to be subclassed by clients.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`ProfileChangeOperation(ProvisioningSession session)`
Create an operation using the provided provisioning session.

## Method Summary

Modifier and Type
Method
Description
`protected abstract void`
`computeProfileChangeRequest(MultiStatus status, IProgressMonitor monitor)`
Compute the profile change request for this operation, adding any relevant intermediate status to the supplied status.
`IProfileChangeRequest`
`getProfileChangeRequest()`
Return the profile change request that describes the receiver.
`String`
`getProfileId()`
Return the string id of the profile involved in this job.
`ProvisioningContext`
`getProvisioningContext()`
Get the provisioning context that will be used to resolve and perform the provisioning for the operation.
`ProvisioningJob`
`getProvisioningJob(IProgressMonitor monitor)`
Return a provisioning job that can be used to perform the resolved operation.
`protected abstract String`
`getProvisioningJobName()`
Return an appropriate name for the provisioning job.
`IProvisioningPlan`
`getProvisioningPlan()`
Return the provisioning plan obtained by resolving the receiver.
`String`
`getResolutionDetails()`
Return a string that can be used to describe the results of the resolution to a client.
`String`
`getResolutionDetails(IInstallableUnit iu)`
Return a string that describes the specific resolution results related to the supplied `IInstallableUnit`.
`IStatus`
`getResolutionResult()`
Return a status indicating the result of resolving this operation.
`final ProvisioningJob`
`getResolveJob(IProgressMonitor monitor)`
Return a job that can be used to resolve this operation in the background.
`protected abstract String`
`getResolveJobName()`
Return an appropriate name for the resolution job.
`boolean`
`hasResolved()`
Return a boolean indicating whether the operation has been resolved.
`protected void`
`prepareToResolve()`
Perform any processing that must occur just before resolving this operation.
`final IStatus`
`resolveModal(IProgressMonitor monitor)`
Resolve the operation in the current thread using the specified progress monitor.
`void`
`setProfileId(String id)`
Set the id of the profile that will be modified by this operation.
`void`
`setProvisioningContext(ProvisioningContext context)`
Set the provisioning context that should be used to resolve and perform the provisioning for the operation.
`protected void`
`updateJobProvisioningContexts(org.eclipse.equinox.internal.p2.operations.PlannerResolutionJob resolutionJob, ProvisioningContext provisioningContext)`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### ProfileChangeOperation

protected ProfileChangeOperation(ProvisioningSession session)
Create an operation using the provided provisioning session. Unless otherwise specified by the client, the operation is performed on the currently running profile.

Parameters:
  `session` - the provisioning session providing the services

## Method Details

### resolveModal

public final IStatus resolveModal(IProgressMonitor monitor)
Resolve the operation in the current thread using the specified progress monitor. Return a status describing the result of the resolution.

Parameters:
  `monitor` - the progress monitor to use
Returns:
  a status describing the resolution results

### setProfileId

public void setProfileId(String id)
Set the id of the profile that will be modified by this operation.

Parameters:
  `id` - the profile id

### getResolveJob

public final ProvisioningJob getResolveJob(IProgressMonitor monitor)
Return a job that can be used to resolve this operation in the background.

Parameters:
  `monitor` - a progress monitor that should be used to report the job's progress in addition to the standard job progress reporting. Can be `null`. If provided, this monitor will be called from a background thread.
Returns:
  a job that can be scheduled to perform the provisioning operation.

### prepareToResolve

protected void prepareToResolve()
Perform any processing that must occur just before resolving this operation.

### computeProfileChangeRequest

protected abstract void computeProfileChangeRequest(MultiStatus status, IProgressMonitor monitor)
Compute the profile change request for this operation, adding any relevant intermediate status to the supplied status.

Parameters:
  `status` - a multi-status to be used to add relevant status. If a profile change request cannot be computed for any reason, a status should be added to explain the problem.
  `monitor` - the progress monitor to use for computing the profile change request

### getResolveJobName

protected abstract String getResolveJobName()
Return an appropriate name for the resolution job.

Returns:
  the resolution job name.

### getProvisioningJobName

protected abstract String getProvisioningJobName()
Return an appropriate name for the provisioning job.

Returns:
  the provisioning job name.

### getResolutionResult

public IStatus getResolutionResult()
Return a status indicating the result of resolving this operation. A `null` return indicates that resolving has not occurred yet.

Returns:
  the status of the resolution, or `null` if resolution has not yet occurred.

### getResolutionDetails

public String getResolutionDetails()
Return a string that can be used to describe the results of the resolution to a client.

Returns:
  a string describing the resolution details, or `null` if the operation has not been resolved.

### getResolutionDetails

public String getResolutionDetails(IInstallableUnit iu)
Return a string that describes the specific resolution results related to the supplied `IInstallableUnit`.

Parameters:
  `iu` - the IInstallableUnit for which resolution details are requested
Returns:
  a string describing the results for the installable unit, or `null` if there are no specific results available for the installable unit.

### getProvisioningPlan

public IProvisioningPlan getProvisioningPlan()
Return the provisioning plan obtained by resolving the receiver.

Returns:
  the provisioning plan. This may be `null` if the operation has not been resolved, or if a plan could not be obtained when attempting to resolve. If the plan is null and the operation has been resolved, then the resolution result will explain the problem.
See Also:
  - `hasResolved()`
  - `getResolutionResult()`

### getProfileChangeRequest

public IProfileChangeRequest getProfileChangeRequest()
Return the profile change request that describes the receiver.

Returns:
  the profile change request. This may be `null` if the operation has not been resolved, or if a profile change request could not be assembled given the operation's state. If the profile change request is null and the operation has been resolved, the the resolution result will explain the problem.
Since:
  2.1
See Also:
  - `hasResolved()`
  - `getResolutionResult()`

### getProvisioningJob

public ProvisioningJob getProvisioningJob(IProgressMonitor monitor)
Return a provisioning job that can be used to perform the resolved operation. The job is created using the default values associated with a new job. It is up to clients to configure the priority of the job and set any appropriate properties, such as `Job.setUser(boolean)`, `Job.setSystem(boolean)`, or `Job.setProperty(QualifiedName, Object)`, before scheduling it.

Parameters:
  `monitor` - a progress monitor that should be used to report the job's progress in addition to the standard job progress reporting. Can be `null`. If provided, this monitor will be called from a background thread.
Returns:
  a job that can be used to perform the provisioning operation. This may be `null` if the operation has not been resolved, or if a plan could not be obtained when attempting to resolve. If the job is null and the operation has been resolved, then the resolution result will explain the problem.
See Also:
  - `hasResolved()`
  - `getResolutionResult()`

### setProvisioningContext

public void setProvisioningContext(ProvisioningContext context)
Set the provisioning context that should be used to resolve and perform the provisioning for the operation. This must be set before an attempt is made to resolve the operation for it to have any effect.

Parameters:
  `context` - the provisioning context.

### getProvisioningContext

public ProvisioningContext getProvisioningContext()
Get the provisioning context that will be used to resolve and perform the provisioning for the operation.

Returns:
  the provisioning context

### getProfileId

public String getProfileId()
Description copied from interface: `IProfileChangeJob`
Return the string id of the profile involved in this job.

Specified by:
  `getProfileId` in interface `IProfileChangeJob`
Returns:
  the id of the profile

### hasResolved

public boolean hasResolved()
Return a boolean indicating whether the operation has been resolved. This method should be used to determine whether a client can expect to retrieve a profile change request, provisioning plan, or resolution result. It is possible that this method return `false` while resolution is taking place if it is performed in the background.

Returns:
  `true` if the operation has been resolved, `false` if it has not resolved.

### updateJobProvisioningContexts

protected void updateJobProvisioningContexts(org.eclipse.equinox.internal.p2.operations.PlannerResolutionJob resolutionJob, ProvisioningContext provisioningContext)