Debian Codegraph @

bundles/org.eclipse.equinox.p2.engine/src/org/eclipse/equinox/p2/engine/IProvisioningPlan.java

raw
1 /*******************************************************************************
2 * Copyright (c) 2009, 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;
15
16 import org.eclipse.core.runtime.IStatus;
17 import org.eclipse.equinox.p2.metadata.IInstallableUnit;
18 import org.eclipse.equinox.p2.query.IQueryable;
19
20 /**
21 * A provisioning plan describes a proposed set of changes to a profile. The
22 * proposed changes may represent a valid and consistent set of changes, or it
23 * may represent a set of changes that would cause errors if executed. In this
24 * case the plan contains information about the severity and explanation for the
25 * problems.
26 *
27 * @noimplement This interface is not intended to be implemented by clients.
28 * @noextend This interface is not intended to be extended by clients.
29 * @since 2.0
30 */
31 public interface IProvisioningPlan {
32
33 /**
34 * Returns the proposed set of installable units to be added to the profile.
35 *
36 * @return The proposed profile additions
37 */
38 public IQueryable<IInstallableUnit> getAdditions();
39
40 /**
41 * Returns the provisioning context in which this plan was created.
42 *
43 * @return The plan's provisioning context
44 */
45 public ProvisioningContext getContext();
46
47 /**
48 * Returns a plan describing the proposed set of changes to the provisioning infrastructure
49 * required by this plan. The installer changes must be performed before this plan
50 * can be successfully executed.
51 *
52 * @return The installer plan.
53 */
54 public IProvisioningPlan getInstallerPlan();
55
56 /**
57 * Returns the profile that this plan will operate on.
58 *
59 * @return The target profile for this plan
60 */
61 public IProfile getProfile();
62
63 /**
64 * Returns the set of IUs that will constitute the profile if the plan is executed successfully.
65 *
66 * @return The set of the IUs that will constitute the profile after the plan is executed successfully, or @null if the
67 * plan is in error or the value has not been set.
68 * @since 2.2
69 */
70 public IQueryable<IInstallableUnit> getFutureState();
71
72 /**
73 * Returns the proposed set of installable units to be removed from this profile.
74 *
75 * @return The proposed profile removals.
76 */
77 public IQueryable<IInstallableUnit> getRemovals();
78
79 /**
80 * Returns the overall plan status. The severity of this status indicates
81 * whether the plan can be successfully executed or not:
82 * <ul>
83 * <li>A status of {@link IStatus#OK} indicates that the plan can be executed successfully.</li>
84 * <li>A status of {@link IStatus#INFO} or {@link IStatus#WARNING} indicates
85 * that the plan can be executed but may cause problems.</li>
86 * <li>A status of {@link IStatus#ERROR} indicates that the plan cannot be executed
87 * successfully.</li>
88 * <li>A status of {@link IStatus#CANCEL} indicates that the plan computation was
89 * canceled and is incomplete. A canceled plan cannot be executed.</li>
90 * </ul>
91 *
92 * @return The overall plan status.
93 */
94 public IStatus getStatus();
95
96 /**
97 * Returns <code>true</code> if the plan contains no operations, <code>false</code> otherwise.
98 *
99 * @return <code>true</code> if the plan contains no operations, <code>false</code> otherwise.
100 */
101 public boolean isEmpty();
102
103 /**
104 * Adds an installable unit to the plan. This will cause the given installable unit
105 * to be installed into the profile when this plan is executed by the engine.
106 * <p>
107 * This is an advanced operation that should only be performed by clients crafting
108 * their own custom plan. Most clients should instead use a planner service
109 * to construct a valid plan based on a profile change request.
110 * </p>
111 * @param iu the installable unit to add
112 */
113 public void addInstallableUnit(IInstallableUnit iu);
114
115 /**
116 * Removes an installable unit from the plan. This will cause the given installable unit
117 * to be remove from the profile when this plan is executed by the engine.
118 * <p>
119 * This is an advanced operation that should only be performed by clients crafting
120 * their own custom plan. Most clients should instead use a planner service
121 * to construct a valid plan based on a profile change request.
122 * </p>
123 * @param iu the installable unit to add
124 */
125 public void removeInstallableUnit(IInstallableUnit iu);
126
127 /**
128 * Adds a profile property corresponding to the given installable unit to the plan.
129 * This will cause the given installable unit property to be installed into the profile
130 * when this plan is executed by the engine.
131 * <p>
132 * This is an advanced operation that should only be performed by clients crafting
133 * their own custom plan. Most clients should instead use a planner service
134 * to construct a valid plan based on a profile change request.
135 * </p>
136 * @param iu the installable unit to set a property for
137 * @param name the property name
138 * @param value the property value
139 */
140 public void setInstallableUnitProfileProperty(IInstallableUnit iu, String name, String value);
141
142 /**
143 * Sets the installer plan for this plan. The installer plan describes the set of changes
144 * that must be made to the provisioning agent in order for this plan to execute
145 * successfully.
146 * <p>
147 * This is an advanced operation that should only be performed by clients crafting
148 * their own custom plan. Most clients should instead use a planner service
149 * to construct a valid plan based on a profile change request.
150 * </p>
151 * @param installerPlan the plan describing changes to the provisioning agent
152 */
153 public void setInstallerPlan(IProvisioningPlan installerPlan);
154
155 /**
156 * Sets a profile property in the plan. This will cause the given property
157 * to be added to the profile when this plan is executed by the engine.
158 * <p>
159 * This is an advanced operation that should only be performed by clients crafting
160 * their own custom plan. Most clients should instead use a planner service
161 * to construct a valid plan based on a profile change request.
162 * </p>
163 * @param name the profile property name
164 * @param value the profile property value
165 */
166 public void setProfileProperty(String name, String value);
167
168 /**
169 * Sets the overall plan status, describing whether the planner constructing
170 * this plan believes it will install successfully, or whether it contains errors
171 * or the plan computation has been canceled.
172 * <p>
173 * This is an advanced operation that should only be performed by clients crafting
174 * their own custom plan. Most clients should instead use a planner service
175 * to construct a valid plan based on a profile change request.
176 * </p>
177 * @param status the plan status
178 */
179 public void setStatus(IStatus status);
180
181 /**
182 * Adds an instruction to replace one installable unit in the profile with another.
183 * This will cause the 'from' installable unit property to be uninstalled from the profile
184 * and the 'to' installable unit to be added to the profile when this plan is executed
185 * by the engine.
186 * <p>
187 * This is an advanced operation that should only be performed by clients crafting
188 * their own custom plan. Most clients should instead use a planner service
189 * to construct a valid plan based on a profile change request.
190 * </p>
191 * @param from the installable unit to remove
192 * @param to the installable unit to add
193 */
194 public void updateInstallableUnit(IInstallableUnit from, IInstallableUnit to);
195
196 /**
197 * Sets the value that is returned by the method getFutureState.
198 * Note that this method is a simple setter and will not cause any update to the other fields of this object.
199 * This field can be set to @null.
200 * @param futureState A set of IU representing the future plan if the plan is executed successfully.
201 * @since 2.2
202 */
203 public void setFuturePlan(IQueryable<IInstallableUnit> futureState);
204 }