Debian Codegraph @

bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/spi/Touchpoint.java

raw
1 /*******************************************************************************
2 * Copyright (c) 2007, 2010 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.engine.spi;
15
16 import java.util.Map;
17 import org.eclipse.core.runtime.*;
18 import org.eclipse.equinox.p2.engine.*;
19
20 /**
21 * A touchpoint is responsible for executing the required provisioning steps
22 * for each phase corresponding to a particular targeted system (eclipse, native).
23 * The order of phases is defined in the {@link IPhaseSet}.
24 * @since 2.0
25 */
26 public abstract class Touchpoint {
27
28 /**
29 * This method is for backwards compatibility only, to be used by touchpoints
30 * that existed prior to action ids being fully qualified by the engine.
31 * @param actionId the unqualified action id
32 * @return the qualified action id
33 * @noreference This method is not intended to be referenced by clients.
34 * @since 2.0
35 */
36 public String qualifyAction(String actionId) {
37 return actionId;
38 }
39
40 /**
41 * This method is called at the beginning of execution of an engine phase. This
42 * is an opportunity for the touchpoint to initialize any phase-specific structures.
43 * <p>
44 * The result of this method can be used to abort execution of the entire engine
45 * operation, by using a severity of {@link IStatus#ERROR} or {@link IStatus#CANCEL}.
46 * The result can also contain warnings or informational status that will be aggregated
47 * and returned to the caller of {@link IEngine#perform(org.eclipse.equinox.p2.engine.IProvisioningPlan, IProgressMonitor)}.
48 * </p>
49 * @param monitor a progress monitor, or <code>null</code> if progress
50 * reporting and cancellation are not desired
51 * @param profile the profile that is being operated on
52 * @param phaseId the id of the phase
53 * @param parameters data provided by the engine to the touchpoint
54 * @return the result of phase initialization
55 */
56 public IStatus initializePhase(IProgressMonitor monitor, IProfile profile, String phaseId, Map<String, Object> parameters) {
57 return Status.OK_STATUS;
58 }
59
60 /**
61 * This method is called at the end of execution of an engine phase. This
62 * is an opportunity for the touchpoint to clean up any phase-specific structures
63 * or perform any final work for the current phase.
64 * <p>
65 * The result of this method can be used to abort execution of the entire engine
66 * operation, by using a severity of {@link IStatus#ERROR} or {@link IStatus#CANCEL}.
67 * The result can also contain warnings or informational status that will be aggregated
68 * and returned to the caller of {@link IEngine#perform(org.eclipse.equinox.p2.engine.IProvisioningPlan, IProgressMonitor)}.
69 * </p>
70 * @param monitor a progress monitor, or <code>null</code> if progress
71 * reporting and cancellation are not desired
72 * @param profile the profile that is being operated on
73 * @param phaseId the id of the phase
74 * @param parameters data provided by the engine to the touchpoint
75 * @return the result of phase completion
76 */
77 public IStatus completePhase(IProgressMonitor monitor, IProfile profile, String phaseId, Map<String, Object> parameters) {
78 return Status.OK_STATUS;
79 }
80
81 /**
82 * This method is called at the beginning of processing of a single engine operand
83 * (for example a given installable unit being installed or uninstalled). This
84 * is an opportunity for the touchpoint to initialize any data structures specific
85 * to a single operand.
86 * <p>
87 * The result of this method can be used to abort execution of the entire engine
88 * operation, by using a severity of {@link IStatus#ERROR} or {@link IStatus#CANCEL}.
89 * The result can also contain warnings or informational status that will be aggregated
90 * and returned to the caller of {@link IEngine#perform(org.eclipse.equinox.p2.engine.IProvisioningPlan, IProgressMonitor)}.
91 * </p>
92 * @param profile the profile that is being operated on
93 * @param parameters data provided by the engine to the touchpoint
94 * @return the result of initialization
95 */
96 public IStatus initializeOperand(IProfile profile, Map<String, Object> parameters) {
97 return Status.OK_STATUS;
98 }
99
100 /**
101 * This method is called at the end of processing of a single engine operand
102 * (for example a given installable unit being installed or uninstalled). This
103 * is an opportunity for the touchpoint to clean up any data structures specific
104 * to a single operand.
105 * <p>
106 * The result of this method can be used to abort execution of the entire engine
107 * operation, by using a severity of {@link IStatus#ERROR} or {@link IStatus#CANCEL}.
108 * The result can also contain warnings or informational status that will be aggregated
109 * and returned to the caller of {@link IEngine#perform(org.eclipse.equinox.p2.engine.IProvisioningPlan, IProgressMonitor)}.
110 * </p>
111 * @param profile the profile that is being operated on
112 * @param parameters data provided by the engine to the touchpoint
113 * @return the result of the completion work
114 */
115 public IStatus completeOperand(IProfile profile, Map<String, Object> parameters) {
116 return Status.OK_STATUS;
117 }
118
119 /**
120 * This method is called at the end of an engine operation after all phases have
121 * been executed but prior to the operation being formally committed/persisted. This is an opportunity to perform any final checks
122 * against the profile, or log any information that might be needed to recover if the operation fails to complete in a regular
123 * manner.
124 * <p>
125 * The result of this method can be used to abort execution of the entire engine
126 * operation, by using a severity of {@link IStatus#ERROR} or {@link IStatus#CANCEL}.
127 * The result can also contain warnings or informational status that will be aggregated
128 * and returned to the caller of {@link IEngine#perform(org.eclipse.equinox.p2.engine.IProvisioningPlan, IProgressMonitor)}.
129 * </p>
130 *
131 * @param profile the profile about to be modified
132 * @return the result of preparation work
133 */
134 public IStatus prepare(IProfile profile) {
135 return Status.OK_STATUS;
136 }
137
138 /**
139 * This method is called at the end of an engine operation after all phases have
140 * been executed and after the touchpoint has had prepare called. When this method is invoked,
141 * it signals that the engine operation was a complete success, and the touchpoint should commit
142 * or persist any changes it has made to some persistent storage (for
143 * example the file system).
144 * <p>
145 * The result of this method can be used to report on the success or failure
146 * of the commit. However, at this point it is too late for the engine operation
147 * to fail, and the result returned from this method will not prevent the engine
148 * from completing its work.
149 * </p>
150 *
151 * @param profile the profile that was modified
152 * @return the result of commit work
153 */
154 public IStatus commit(IProfile profile) {
155 return Status.OK_STATUS;
156 }
157
158 /**
159 * This method is called at the end of an engine operation after all phases have
160 * been executed. When this method is invoked, it signals that the engine
161 * operation was a failure, and the touchpoint should discard any
162 * changes it has made.
163 * <p>
164 * The result of this method can be used to report on the success or failure
165 * of the rollback. However, at this point it is too late for the engine operation
166 * to be stopped, and the result returned from this method will not prevent the engine
167 * from completing its rollback work.
168 * </p>
169 *
170 * @param profile the profile that was modified
171 * @return the result of commit work
172 */
173 public IStatus rollback(IProfile profile) {
174 return Status.OK_STATUS;
175 }
176 }