1 /******************************************************************************* 2 * Copyright (c) 2007, 2017 IBM Corporation and others. 3 * 4 * This 5 * program and the accompanying materials are made available under the terms of 6 * the Eclipse Public License 2.0 which accompanies this distribution, and is 7 * available at 8 * https://www.eclipse.org/legal/epl-2.0/ 9 * 10 * SPDX-License-Identifier: EPL-2.0 11 * 12 * Contributors: 13 * IBM Corporation - initial API and implementation 14 * Genuitec, LLC - added license support 15 * EclipseSource - ongoing development 16 ******************************************************************************/ 17 package org.eclipse.equinox.p2.metadata; 18 19 import java.util.Collection; 20 import java.util.Map; 21 import org.eclipse.equinox.p2.metadata.expression.IMatchExpression; 22 23 /** 24 * An installable unit represents an atomic, indivisible unit of installable functionality 25 * in a provisioned system. Everything that can be installed or uninstalled in a system, 26 * including both concrete artifacts and instructions describing steps to be performed 27 * during install, must be expressed as one or more installable units. Thus the set of 28 * installable units present in a system, together with the existing environment 29 * (operating system, etc), completely describes the initial installed state of that system. 30 * <p> 31 * Installable units may have dependencies on functionality provided by other installable 32 * units, such that the unit cannot be installed unless some other installable unit 33 * is present in the installed system that provides a matching capability. Such 34 * dependencies are referred to as <i>required capabilities</i>. Conversely, 35 * installable units may declared <i>provided capabilities</i>, describing the 36 * capabilities that they make available to other units in the system. Note the 37 * weak coupling at work here: installable units never directly depend on each other, 38 * but instead depend on abstract capabilities that any other installable unit may provide. 39 * </p> 40 * <p> 41 * Instances of this class are handle objects and do not necessarily 42 * reflect entities that exist in any particular profile or repository. These handle 43 * objects can be created using {@link MetadataFactory}. 44 * </p> 45 * 46 * @noimplement This interface is not intended to be implemented by clients. 47 * @noextend This interface is not intended to be extended by clients. 48 * @since 2.0 49 * @see MetadataFactory#createInstallableUnit(org.eclipse.equinox.p2.metadata.MetadataFactory.InstallableUnitDescription) 50 */ 51 public interface IInstallableUnit extends IVersionedId, Comparable<IInstallableUnit> { 52 53 /** 54 * A capability namespace representing a particular InstallableUnit by id. 55 * Each InstallableUnit automatically provides a capability in this namespace representing 56 * itself, and other InstallableUnits can require such a capability to state that they 57 * require a particular InstallableUnit to be present. 58 * 59 * @see IInstallableUnit#getId() 60 */ 61 public static final String NAMESPACE_IU_ID = "org.eclipse.equinox.p2.iu"; //$NON-NLS-1$ 62 63 /** 64 * A property key (value <code>"org.eclipse.equinox.p2.partial.iu"</code>) for a 65 * boolean property indicating the IU is generated from incomplete information and 66 * should be replaced by the complete IU if available. 67 * 68 * @see #getProperty(String) 69 */ 70 public static final String PROP_PARTIAL_IU = "org.eclipse.equinox.p2.partial.iu"; //$NON-NLS-1$ 71 72 /** 73 * A property key (value <code>"org.eclipse.equinox.p2.contact"</code>) for a 74 * String property containing a contact address where problems can be reported, 75 * such as an email address. 76 * 77 * @see #getProperty(String) 78 */ 79 public static final String PROP_CONTACT = "org.eclipse.equinox.p2.contact"; //$NON-NLS-1$ 80 /** 81 * A property key (value <code>"org.eclipse.equinox.p2.description"</code>) for a 82 * String property containing a human-readable description of the installable unit. 83 * 84 * @see #getProperty(String) 85 */ 86 public static final String PROP_DESCRIPTION = "org.eclipse.equinox.p2.description"; //$NON-NLS-1$ 87 88 /** 89 * A property key (value <code>"org.eclipse.equinox.p2.description.url"</code>) for a 90 * String property containing a URL to the description of the installable unit. 91 * 92 * @see #getProperty(String) 93 */ 94 public static final String PROP_DESCRIPTION_URL = "org.eclipse.equinox.p2.description.url"; //$NON-NLS-1$ 95 /** 96 * A property key (value <code>"org.eclipse.equinox.p2.doc.url"</code>) for a 97 * String property containing a URL for documentation about the installable unit. 98 * 99 * @see #getProperty(String) 100 */ 101 public static final String PROP_DOC_URL = "org.eclipse.equinox.p2.doc.url"; //$NON-NLS-1$ 102 103 /** 104 * A property key (value <code>"org.eclipse.equinox.p2.bundle.localization"</code>) for a String 105 * property containing the bundle localization property file name 106 */ 107 public static final String PROP_BUNDLE_LOCALIZATION = "org.eclipse.equinox.p2.bundle.localization"; //$NON-NLS-1$ 108 109 /** 110 * A property key (value <code>"org.eclipse.equinox.p2.name"</code>) for a 111 * String property containing a human-readable name for the installable unit. 112 * 113 * @see #getProperty(String) 114 */ 115 public static final String PROP_NAME = "org.eclipse.equinox.p2.name"; //$NON-NLS-1$ 116 /** 117 * A property key (value <code>"org.eclipse.equinox.p2.provider"</code>) for a 118 * String property containing information about the vendor or provider of the 119 * installable unit. 120 * 121 * @see #getProperty(String) 122 */ 123 public static final String PROP_PROVIDER = "org.eclipse.equinox.p2.provider"; //$NON-NLS-1$ 124 125 /** 126 * A property key (value <code>"org.eclipse.equinox.p2.icon"</code>) for a String 127 * property containing a URI for an icon that should be shown when displaying this 128 * installable unit in a user interface. 129 * 130 * @see #getProperty(String) 131 */ 132 public static final String PROP_ICON = "org.eclipse.equinox.p2.icon"; //$NON-NLS-1$ 133 134 /** 135 * Returns the collection of artifacts associated with this installable unit. 136 * Installing this unit into a system will cause these artifacts to be fetched from 137 * a repository and applied to the installed system. Uninstalling this unit 138 * will cause these artifacts to be removed from the system. 139 * 140 * @return The artifacts associated with this installable unit 141 */ getArtifacts()142 public Collection<IArtifactKey> getArtifacts(); 143 144 /** 145 * Returns the filter on this installable unit. The filter is matched against 146 * the properties of the environment the unit is installed into. An installable 147 * unit will not be installed if it has a filter condition that is not satisfied by the 148 * properties of the environment. 149 * 150 * @return The installation filter for this unit, or <code>null</code> 151 * @noreference This method is not intended to be referenced by clients. 152 */ getFilter()153 public IMatchExpression<IInstallableUnit> getFilter(); 154 155 /** 156 * Returns the fragments that have been bound to this installable unit, or 157 * <code>null</code> if this unit is not resolved. 158 * 159 * @see #isResolved() 160 * @return The fragments bound to this installable unit, or <code>null</code> 161 */ getFragments()162 public Collection<IInstallableUnitFragment> getFragments(); 163 164 /** 165 * Returns an <i>unmodifiable copy</i> of the properties 166 * associated with the installable unit. 167 * 168 * @return an <i>unmodifiable copy</i> of the properties of this installable unit. 169 */ getProperties()170 public Map<String, String> getProperties(); 171 172 /** 173 * Returns the untranslated property of this installable unit associated with the given key. 174 * Returns <code>null</code> if no such property is defined. 175 * <p> 176 * If the property value has been externalized, this method will return a string containing 177 * the translation key rather than a human-readable string. For this reason, clients 178 * wishing to obtain the value for a property that is typically translated should use 179 * {@link #getProperty(String, String)} instead. 180 * </p> 181 * 182 * @param key The property key to retrieve a property value for 183 * @return the property that applies to this installable unit or <code>null</code> 184 */ getProperty(String key)185 public String getProperty(String key); 186 187 /** 188 * Returns the property of this installable unit associated with the given key. 189 * Returns <code>null</code> if no such property is defined or no applicable 190 * translation is available. 191 * 192 * @param key The property key to retrieve a property value for 193 * @param locale The locale to translate the property for, or null to use the current locale. 194 * @return the property that applies to this installable unit or <code>null</code> 195 */ getProperty(String key, String locale)196 public String getProperty(String key, String locale); 197 198 /** 199 * Returns the collection of capabilities provided by this installable unit. 200 * 201 * @return The collection of capabilities provided by this installable unit. 202 */ getProvidedCapabilities()203 public Collection<IProvidedCapability> getProvidedCapabilities(); 204 getRequirements()205 public Collection<IRequirement> getRequirements(); 206 getMetaRequirements()207 public Collection<IRequirement> getMetaRequirements(); 208 getTouchpointData()209 public Collection<ITouchpointData> getTouchpointData(); 210 getTouchpointType()211 public ITouchpointType getTouchpointType(); 212 213 /** 214 * Returns whether this installable unit has been resolved. A resolved 215 * installable unit represents the union of an installable unit and some 216 * fragments. 217 * 218 * @see #getFragments() 219 * @see #unresolved() 220 * @return <code>true</code> if this installable unit is resolved, and 221 * <code>false</code> otherwise. 222 */ isResolved()223 public boolean isResolved(); 224 225 /** 226 * Returns whether this installable unit is a singleton. Only one singleton 227 * installable unit with a given id is allowed to exist in a given installed system. 228 * Attempting to install multiple versions of a singleton will fail. 229 * @return <code>true</code> if this unit is a singleton, and <code>false</code> otherwise 230 * @noreference This method is not intended to be referenced by clients. 231 */ isSingleton()232 public boolean isSingleton(); 233 234 /** 235 * Returns whether this unit has a provided capability that satisfies the given 236 * requirement. 237 * @return <code>true</code> if this unit satisfies the given requirement, and <code>false</code> otherwise. 238 */ satisfies(IRequirement candidate)239 public boolean satisfies(IRequirement candidate); 240 241 /** 242 * Returns the unresolved equivalent of this installable unit. If this unit is 243 * already unresolved, this method returns the receiver. Otherwise, this 244 * method returns an installable unit with the same id and version, but without 245 * any fragments attached. 246 * 247 * @see #getFragments() 248 * @see #isResolved() 249 * @return The unresolved equivalent of this unit 250 */ unresolved()251 public IInstallableUnit unresolved(); 252 253 /** 254 * Returns information about what this installable unit is an update of. 255 * @return The lineage information about the installable unit 256 */ getUpdateDescriptor()257 public IUpdateDescriptor getUpdateDescriptor(); 258 259 /** 260 * Returns the untranslated licenses that apply to this installable unit. 261 * <p> 262 * If the license text has been externalized, this method will return strings containing 263 * the translation keys rather than human-readable strings. For this reason, clients 264 * wishing to obtain a license for display to an end user should use {@link #getLicenses(String)} 265 * instead. 266 * </p> 267 * @return the licenses that apply to this installable unit 268 */ getLicenses()269 public Collection<ILicense> getLicenses(); 270 271 /** 272 * Returns the licenses that apply to this installable unit. Any translation of the 273 * licenses for the given locale will be applied. Returns an empty collection if this 274 * unit has no licenses, or if the available licenses are externalized and do not 275 * have translations available for the given locale. 276 * 277 * @param locale The locale to translate the license for, or null to use the current locale. 278 * @return the translated licenses that apply to this installable unit 279 */ getLicenses(String locale)280 public Collection<ILicense> getLicenses(String locale); 281 282 /** 283 * Returns the untranslated copyright that applies to this installable unit. 284 * <p> 285 * If the copyright text has been externalized, this method will return strings containing 286 * the translation keys rather than human-readable strings. For this reason, clients 287 * wishing to obtain a copyright for display to an end user should use {@link #getCopyright(String)} 288 * instead. 289 * </p> 290 * @return the copyright that applies to this installable unit or <code>null</code> 291 */ getCopyright()292 public ICopyright getCopyright(); 293 294 /** 295 * Returns the copyright that applies to this installable unit. Any translation of the 296 * copyright for the given locale will be applied. Returns <code>null</code> if this 297 * unit has no copyright, or if the copyright is externalized and no translations are 298 * available for the given locale. 299 * 300 * @param locale The locale to translate the copyright for, or null to use the current locale. 301 * @return the copyright that applies to this installable unit or <code>null</code> 302 */ getCopyright(String locale)303 public ICopyright getCopyright(String locale); 304 305 /** 306 * Returns whether this InstallableUnit is equal to the given object. 307 * 308 * This method returns <i>true</i> if: 309 * <ul> 310 * <li> Both this object and the given object are of type IInstallableUnit 311 * <li> The result of <b>getId()</b> on both objects are equal 312 * <li> The result of <b>getVersion()</b> on both objects are equal 313 * </ul> 314 */ 315 @Override equals(Object obj)316 public boolean equals(Object obj); 317 }