Debian Codegraph @

bundles/org.eclipse.equinox.p2.operations/src/org/eclipse/equinox/p2/operations/ProfileChangeOperation.java

raw
1 /*******************************************************************************
2 * Copyright (c) 2009, 2017 IBM Corporation and others.
3 *
4 * This program and the accompanying materials
5 * are made available under the terms of the Eclipse Public License 2.0
6 * which accompanies this distribution, and is available at
7 * https://www.eclipse.org/legal/epl-2.0/
8 *
9 * SPDX-License-Identifier: EPL-2.0
10 *
11 * Contributors:
12 * IBM Corporation - initial API and implementation
13 ******************************************************************************/
14 package org.eclipse.equinox.p2.operations;
15
16 import org.eclipse.core.runtime.*;
17 import org.eclipse.core.runtime.jobs.Job;
18 import org.eclipse.equinox.internal.p2.director.ProfileChangeRequest;
19 import org.eclipse.equinox.internal.p2.operations.*;
20 import org.eclipse.equinox.p2.engine.*;
21 import org.eclipse.equinox.p2.metadata.IInstallableUnit;
22 import org.eclipse.equinox.p2.planner.IProfileChangeRequest;
23
24 /**
25 * ProfileChangeOperation describes a provisioning operation that modifies a profile.
26 * The operation must first be resolved, followed by the actual provisioning
27 * work being performed. This two-pass nature of the ProfileChangeOperation allows
28 * resolution status to be reported to a client to determine whether the operation
29 * should proceed. Each phase of the operation can be performed synchronously or in
30 * the background as a job. To perform the operation synchronously:
31 *
32 * <pre>
33 * IStatus result = op.resolveModal(monitor);
34 * if (result.isOK())
35 * op.getProvisioningJob(null).runModal(monitor);
36 * else {
37 * // interpret the result
38 * }
39 * </pre>
40 *
41 * To perform the resolution synchronously and the provisioning job in the
42 * background:
43 *
44 * <pre>
45 * IStatus status = op.resolveModal(monitor);
46 * if (status.isOK()) {
47 * ProvisioningJob job = op.getProvisioningJob(monitor);
48 * job.schedule();
49 * } else {
50 * // interpret the result
51 * }
52 * </pre>
53 *
54 * To resolve in the background and perform the job when it is complete:
55 *
56 * <pre>
57 * ProvisioningJob job = op.getResolveJob(monitor);
58 * job.addJobChangeListener(new JobChangeAdapter() {
59 * public void done (JobChangeEvent event) {
60 * if (event.getResult().isOK() {
61 * op.getProvisioningJob(monitor).schedule();
62 * } else {
63 * // interpret the result
64 * }
65 * }
66 * });
67 * job.schedule();
68 *
69 * </pre>
70 *
71 * In general, it is expected that clients create a new ProfileChangeOperation if
72 * the resolution result of the current operation is not satisfactory. However,
73 * subclasses may prescribe a different life cycle where appropriate.
74 *
75 * When retrieving the resolution and provisioning jobs managed by this operation,
76 * a client may supply a progress monitor to be used by the job. When the job is
77 * run by the platform job manager, both the platform job manager progress indicator
78 * and the monitor supplied by the client will be updated.
79 *
80 * @noextend This class is not intended to be subclassed by clients.
81 * @since 2.0
82 */
83 public abstract class ProfileChangeOperation implements IProfileChangeJob {
84
85 ProvisioningSession session;
86 String profileId;
87 ProvisioningContext context;
88 MultiStatus noChangeRequest;
89 PlannerResolutionJob job;
90 ProfileChangeRequest request;
91
92 /**
93 * Create an operation using the provided provisioning session.
94 * Unless otherwise specified by the client, the operation is
95 * performed on the currently running profile.
96 *
97 * @param session the provisioning session providing the services
98 */
99 protected ProfileChangeOperation(ProvisioningSession session) {
100 this.session = session;
101 this.profileId = IProfileRegistry.SELF;
102 this.context = new ProvisioningContext(session.getProvisioningAgent());
103 }
104
105 /**
106 * Resolve the operation in the current thread using the specified progress
107 * monitor. Return a status describing the result of the resolution.
108 *
109 * @param monitor the progress monitor to use
110 * @return a status describing the resolution results
111 */
112 public final IStatus resolveModal(IProgressMonitor monitor) {
113 SubMonitor subMon = SubMonitor.convert(monitor, 2);
114 prepareToResolve();
115 makeResolveJob(subMon.split(1));
116 if (job != null) {
117 IStatus status = job.runModal(subMon.split(1));
118 if (status.getSeverity() == IStatus.CANCEL)
119 return Status.CANCEL_STATUS;
120 }
121 monitor.done();
122 // For anything other than cancellation, we examine the artifacts of the resolution and come
123 // up with an overall summary.
124 return getResolutionResult();
125
126 }
127
128 /**
129 * Set the id of the profile that will be modified by this operation.
130 * @param id the profile id
131 */
132 public void setProfileId(String id) {
133 this.profileId = id;
134 }
135
136 /**
137 * Return a job that can be used to resolve this operation in the background.
138 *
139 * @param monitor a progress monitor that should be used to report the job's progress in addition
140 * to the standard job progress reporting. Can be <code>null</code>. If provided, this monitor
141 * will be called from a background thread.
142 *
143 * @return a job that can be scheduled to perform the provisioning operation.
144 */
145 public final ProvisioningJob getResolveJob(IProgressMonitor monitor) {
146 SubMonitor mon = SubMonitor.convert(monitor, Messages.ProfileChangeOperation_ResolveTaskName, 1000);
147 prepareToResolve();
148 makeResolveJob(mon.newChild(100));
149 if (mon.isCanceled())
150 return null;
151 if (job != null)
152 job.setAdditionalProgressMonitor(mon.newChild(900));
153 return job;
154 }
155
156 /**
157 * Perform any processing that must occur just before resolving this operation.
158 */
159 protected void prepareToResolve() {
160 // default is to do nothing
161 }
162
163 void makeResolveJob(IProgressMonitor monitor) {
164 noChangeRequest = PlanAnalyzer.getProfileChangeAlteredStatus();
165 if (session.hasScheduledOperationsFor(profileId)) {
166 noChangeRequest.add(PlanAnalyzer.getStatus(IStatusCodes.OPERATION_ALREADY_IN_PROGRESS, null));
167 } else {
168 computeProfileChangeRequest(noChangeRequest, monitor);
169 }
170 if (request == null) {
171 if (noChangeRequest.getChildren().length == 0)
172 // No explanation for failure was provided. It shouldn't happen, but...
173 noChangeRequest = new MultiStatus(Constants.BUNDLE_ID, IStatusCodes.UNEXPECTED_NOTHING_TO_DO, new IStatus[] {PlanAnalyzer.getStatus(IStatusCodes.UNEXPECTED_NOTHING_TO_DO, null)}, Messages.ProfileChangeOperation_NoProfileChangeRequest, null);
174 return;
175 }
176 createPlannerResolutionJob();
177 }
178
179 /**
180 * Compute the profile change request for this operation, adding any relevant intermediate status
181 * to the supplied status.
182 *
183 * @param status a multi-status to be used to add relevant status. If a profile change request cannot
184 * be computed for any reason, a status should be added to explain the problem.
185 *
186 * @param monitor the progress monitor to use for computing the profile change request
187 */
188 protected abstract void computeProfileChangeRequest(MultiStatus status, IProgressMonitor monitor);
189
190 private void createPlannerResolutionJob() {
191 job = new PlannerResolutionJob(getResolveJobName(), session, profileId, request, getFirstPassProvisioningContext(), getSecondPassEvaluator(), noChangeRequest);
192 }
193
194 /**
195 * Return an appropriate name for the resolution job.
196 *
197 * @return the resolution job name.
198 */
199 protected abstract String getResolveJobName();
200
201 /**
202 * Return an appropriate name for the provisioning job.
203 *
204 * @return the provisioning job name.
205 */
206 protected abstract String getProvisioningJobName();
207
208 /**
209 * Return a status indicating the result of resolving this
210 * operation. A <code>null</code> return indicates that
211 * resolving has not occurred yet.
212 *
213 * @return the status of the resolution, or <code>null</code>
214 * if resolution has not yet occurred.
215 */
216 public IStatus getResolutionResult() {
217 if (request == null) {
218 if (noChangeRequest != null) {
219 // If there is only one child message, use the specific message
220 if (noChangeRequest.getChildren().length == 1)
221 return noChangeRequest.getChildren()[0];
222 return noChangeRequest;
223 }
224 return null;
225 }
226 if (job != null && job.getResolutionResult() != null)
227 return job.getResolutionResult().getSummaryStatus();
228 return null;
229 }
230
231 /**
232 * Return a string that can be used to describe the results of the resolution
233 * to a client.
234 *
235 * @return a string describing the resolution details, or <code>null</code> if the
236 * operation has not been resolved.
237 */
238 public String getResolutionDetails() {
239 if (job != null && job.getResolutionResult() != null)
240 return job.getResolutionResult().getSummaryReport();
241 // We couldn't resolve, but we have some status describing
242 // why there is no profile change request.
243 IStatus result = getResolutionResult();
244 if (result != null)
245 return result.getMessage();
246 return null;
247
248 }
249
250 /**
251 * Return a string that describes the specific resolution results
252 * related to the supplied {@link IInstallableUnit}.
253 *
254 * @param iu the IInstallableUnit for which resolution details are requested
255 *
256 * @return a string describing the results for the installable unit, or <code>null</code> if
257 * there are no specific results available for the installable unit.
258 */
259 public String getResolutionDetails(IInstallableUnit iu) {
260 if (job != null && job.getResolutionResult() != null)
261 return job.getResolutionResult().getDetailedReport(new IInstallableUnit[] {iu});
262 return null;
263
264 }
265
266 /**
267 * Return the provisioning plan obtained by resolving the receiver.
268 *
269 * @return the provisioning plan. This may be <code>null</code> if the operation
270 * has not been resolved, or if a plan could not be obtained when attempting to
271 * resolve. If the plan is null and the operation has been resolved, then the
272 * resolution result will explain the problem.
273 *
274 * @see #hasResolved()
275 * @see #getResolutionResult()
276 */
277 public IProvisioningPlan getProvisioningPlan() {
278 if (job != null)
279 return job.getProvisioningPlan();
280 return null;
281 }
282
283 /**
284 * Return the profile change request that describes the receiver.
285 *
286 * @return the profile change request. This may be <code>null</code> if the operation
287 * has not been resolved, or if a profile change request could not be assembled given
288 * the operation's state. If the profile change request is null and the operation has
289 * been resolved, the the resolution result will explain the problem.
290 *
291 * @see #hasResolved()
292 * @see #getResolutionResult()
293 * @since 2.1
294 */
295 public IProfileChangeRequest getProfileChangeRequest() {
296 if (job != null)
297 return job.getProfileChangeRequest();
298 return null;
299 }
300
301 /**
302 * Return a provisioning job that can be used to perform the resolved operation. The job is
303 * created using the default values associated with a new job. It is up to clients to configure
304 * the priority of the job and set any appropriate properties, such as
305 * {@link Job#setUser(boolean)},
306 * {@link Job#setSystem(boolean)}, or {@link Job#setProperty(QualifiedName, Object)},
307 * before scheduling it.
308 *
309 * @param monitor a progress monitor that should be used to report the job's progress in addition
310 * to the standard job progress reporting. Can be <code>null</code>. If provided, this monitor
311 * will be called from a background thread.
312 *
313 * @return a job that can be used to perform the provisioning operation. This may be <code>null</code>
314 * if the operation has not been resolved, or if a plan could not be obtained when attempting to
315 * resolve. If the job is null and the operation has been resolved, then the resolution result
316 * will explain the problem.
317 *
318 * @see #hasResolved()
319 * @see #getResolutionResult()
320 */
321 public ProvisioningJob getProvisioningJob(IProgressMonitor monitor) {
322 IStatus status = getResolutionResult();
323 //if status is null we haven't resolved yet, so we must return null here
324 if (status == null)
325 return null;
326 if (status.getSeverity() != IStatus.CANCEL && status.getSeverity() != IStatus.ERROR) {
327 if (job.getProvisioningPlan() != null) {
328 ProfileModificationJob pJob = new ProfileModificationJob(getProvisioningJobName(), session, profileId, job.getProvisioningPlan(), job.getActualProvisioningContext());
329 pJob.setAdditionalProgressMonitor(monitor);
330 return pJob;
331 }
332 }
333 return null;
334 }
335
336 /**
337 * Set the provisioning context that should be used to resolve and perform the provisioning for
338 * the operation. This must be set before an attempt is made to resolve the operation
339 * for it to have any effect.
340 *
341 * @param context the provisioning context.
342 */
343 public void setProvisioningContext(ProvisioningContext context) {
344 this.context = context;
345 if (job != null)
346 updateJobProvisioningContexts(job, context);
347 }
348
349 /**
350 * Get the provisioning context that will be used to resolve and perform the provisioning for
351 * the operation.
352 *
353 * @return the provisioning context
354 */
355 public ProvisioningContext getProvisioningContext() {
356 return context;
357 }
358
359 @Override
360 public String getProfileId() {
361 return profileId;
362 }
363
364 /**
365 * Return a boolean indicating whether the operation has been resolved. This method
366 * should be used to determine whether a client can expect to retrieve a profile
367 * change request, provisioning plan, or resolution result. It is possible that this
368 * method return <code>false</code> while resolution is taking place if it is performed
369 * in the background.
370 *
371 * @return <code>true</code> if the operation has been resolved, <code>false</code>
372 * if it has not resolved.
373 */
374 public boolean hasResolved() {
375 return getResolutionResult() != null;
376 }
377
378 ProvisioningContext getFirstPassProvisioningContext() {
379 return getProvisioningContext();
380 }
381
382 IFailedStatusEvaluator getSecondPassEvaluator() {
383 return failedPlan -> null;
384 }
385
386 protected void updateJobProvisioningContexts(PlannerResolutionJob resolutionJob, ProvisioningContext provisioningContext) {
387 resolutionJob.setFirstPassProvisioningContext(provisioningContext);
388 }
389
390 }