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 */ getAdditions()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 */ getContext()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 */ getInstallerPlan()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 */ getProfile()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 */ getFutureState()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 */ getRemovals()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 */ getStatus()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 */ isEmpty()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 */ addInstallableUnit(IInstallableUnit iu)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 */ removeInstallableUnit(IInstallableUnit iu)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 */ setInstallableUnitProfileProperty(IInstallableUnit iu, String name, String value)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 */ setInstallerPlan(IProvisioningPlan installerPlan)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 */ setProfileProperty(String name, String value)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 */ setStatus(IStatus status)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 */ updateInstallableUnit(IInstallableUnit from, IInstallableUnit to)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 */ setFuturePlan(IQueryable<IInstallableUnit> futureState)203 public void setFuturePlan(IQueryable<IInstallableUnit> futureState); 204 }