Eclipse Platform
Release 3.6

org.eclipse.equinox.p2.metadata
Interface IInstallableUnit

All Superinterfaces:
Comparable<IInstallableUnit>, IVersionedId
All Known Subinterfaces:
IInstallableUnitFragment, IInstallableUnitPatch

public interface IInstallableUnit
extends IVersionedId, Comparable<IInstallableUnit>

An installable unit represents an atomic, indivisible unit of installable functionality in a provisioned system. Everything that can be installed or uninstalled in a system, including both concrete artifacts and instructions describing steps to be performed during install, must be expressed as one or more installable units. Thus the set of installable units present in a system, together with the existing environment (operating system, etc), completely describes the initial installed state of that system.

Installable units may have dependencies on functionality provided by other installable units, such that the unit cannot be installed unless some other installable unit is present in the installed system that provides a matching capability. Such dependencies are referred to as required capabilities. Conversely, installable units may declared provided capabilities, describing the capabilities that they make available to other units in the system. Note the weak coupling at work here: installable units never directly depend on each other, but instead depend on abstract capabilities that any other installable unit may provide.

Since:
2.0
Restriction:
This interface is not intended to be implemented by clients.
Restriction:
This interface is not intended to be extended by clients.

Field Summary
static String NAMESPACE_IU_ID
          A capability namespace representing a particular InstallableUnit by id.
static String PROP_BUNDLE_LOCALIZATION
          A property key (value "org.eclipse.equinox.p2.bundle.localization") for a String property containing the bundle localization property file name
static String PROP_CONTACT
          A property key (value "org.eclipse.equinox.p2.contact") for a String property containing a contact address where problems can be reported, such as an email address.
static String PROP_DESCRIPTION
          A property key (value "org.eclipse.equinox.p2.description") for a String property containing a human-readable description of the installable unit.
static String PROP_DESCRIPTION_URL
          A property key (value "org.eclipse.equinox.p2.description.url") for a String property containing a URL to the description of the installable unit.
static String PROP_DOC_URL
          A property key (value "org.eclipse.equinox.p2.doc.url") for a String property containing a URL for documentation about the installable unit.
static String PROP_ICON
          A property key (value "org.eclipse.equinox.p2.icon") for a String property containing a URI for an icon that should be shown when displaying this installable unit in a user interface.
static String PROP_NAME
          A property key (value "org.eclipse.equinox.p2.name") for a String property containing a human-readable name for the installable unit.
static String PROP_PARTIAL_IU
          A property key (value "org.eclipse.equinox.p2.partial.iu") for a boolean property indicating the IU is generated from incomplete information and should be replaced by the complete IU if available.
static String PROP_PROVIDER
          A property key (value "org.eclipse.equinox.p2.provider") for a String property containing information about the vendor or provider of the installable unit.
 
Method Summary
 boolean equals(Object obj)
          Returns whether this InstallableUnit is equal to the given object.
 Collection<IArtifactKey> getArtifacts()
          Returns the collection of artifacts associated with this installable unit.
 ICopyright getCopyright()
          Returns the untranslated copyright that applies to this installable unit.
 ICopyright getCopyright(String locale)
          Returns the copyright that applies to this installable unit.
 IMatchExpression<IInstallableUnit> getFilter()
          Returns the filter on this installable unit.
 Collection<IInstallableUnitFragment> getFragments()
          Returns the fragments that have been bound to this installable unit, or null if this unit is not resolved.
 Collection<ILicense> getLicenses()
          Returns the untranslated licenses that apply to this installable unit.
 Collection<ILicense> getLicenses(String locale)
          Returns the licenses that apply to this installable unit.
 Collection<IRequirement> getMetaRequirements()
           
 Map<String,String> getProperties()
          Returns an unmodifiable copy of the properties associated with the installable unit.
 String getProperty(String key)
          Returns the untranslated property of this installable unit associated with the given key.
 String getProperty(String key, String locale)
          Returns the property of this installable unit associated with the given key.
 Collection<IProvidedCapability> getProvidedCapabilities()
          Returns the collection of capabilities provided by this installable unit.
 Collection<IRequirement> getRequirements()
           
 Collection<ITouchpointData> getTouchpointData()
           
 ITouchpointType getTouchpointType()
           
 IUpdateDescriptor getUpdateDescriptor()
          Returns information about what this installable unit is an update of.
 boolean isResolved()
          Returns whether this installable unit has been resolved.
 boolean isSingleton()
          Returns whether this installable unit is a singleton.
 boolean satisfies(IRequirement candidate)
          Returns whether this unit has a provided capability that satisfies the given requirement.
 IInstallableUnit unresolved()
          Returns the unresolved equivalent of this installable unit.
 
Methods inherited from interface org.eclipse.equinox.p2.metadata.IVersionedId
getId, getVersion
 
Methods inherited from interface java.lang.Comparable
compareTo
 

Field Detail

NAMESPACE_IU_ID

static final String NAMESPACE_IU_ID
A capability namespace representing a particular InstallableUnit by id. Each InstallableUnit automatically provides a capability in this namespace representing itself, and other InstallableUnits can require such a capability to state that they require a particular InstallableUnit to be present.

See Also:
IVersionedId.getId(), Constant Field Values

PROP_PARTIAL_IU

static final String PROP_PARTIAL_IU
A property key (value "org.eclipse.equinox.p2.partial.iu") for a boolean property indicating the IU is generated from incomplete information and should be replaced by the complete IU if available.

See Also:
getProperty(String), Constant Field Values

PROP_CONTACT

static final String PROP_CONTACT
A property key (value "org.eclipse.equinox.p2.contact") for a String property containing a contact address where problems can be reported, such as an email address.

See Also:
getProperty(String), Constant Field Values

PROP_DESCRIPTION

static final String PROP_DESCRIPTION
A property key (value "org.eclipse.equinox.p2.description") for a String property containing a human-readable description of the installable unit.

See Also:
getProperty(String), Constant Field Values

PROP_DESCRIPTION_URL

static final String PROP_DESCRIPTION_URL
A property key (value "org.eclipse.equinox.p2.description.url") for a String property containing a URL to the description of the installable unit.

See Also:
getProperty(String), Constant Field Values

PROP_DOC_URL

static final String PROP_DOC_URL
A property key (value "org.eclipse.equinox.p2.doc.url") for a String property containing a URL for documentation about the installable unit.

See Also:
getProperty(String), Constant Field Values

PROP_BUNDLE_LOCALIZATION

static final String PROP_BUNDLE_LOCALIZATION
A property key (value "org.eclipse.equinox.p2.bundle.localization") for a String property containing the bundle localization property file name

See Also:
Constant Field Values

PROP_NAME

static final String PROP_NAME
A property key (value "org.eclipse.equinox.p2.name") for a String property containing a human-readable name for the installable unit.

See Also:
getProperty(String), Constant Field Values

PROP_PROVIDER

static final String PROP_PROVIDER
A property key (value "org.eclipse.equinox.p2.provider") for a String property containing information about the vendor or provider of the installable unit.

See Also:
getProperty(String), Constant Field Values

PROP_ICON

static final String PROP_ICON
A property key (value "org.eclipse.equinox.p2.icon") for a String property containing a URI for an icon that should be shown when displaying this installable unit in a user interface.

See Also:
getProperty(String), Constant Field Values
Method Detail

getArtifacts

Collection<IArtifactKey> getArtifacts()
Returns the collection of artifacts associated with this installable unit. Installing this unit into a system will cause these artifacts to be fetched from a repository and applied to the installed system. Uninstalling this unit will cause these artifacts to be removed from the system.

Returns:
The artifacts associated with this installable unit

getFilter

IMatchExpression<IInstallableUnit> getFilter()
Returns the filter on this installable unit. The filter is matched against the properties of the environment the unit is installed into. An installable unit will not be installed if it has a filter condition that is not satisfied by the properties of the environment.

Returns:
The installation filter for this unit, or null
Restriction:
This method is not intended to be referenced by clients.

getFragments

Collection<IInstallableUnitFragment> getFragments()
Returns the fragments that have been bound to this installable unit, or null if this unit is not resolved.

Returns:
The fragments bound to this installable unit, or null
See Also:
isResolved()

getProperties

Map<String,String> getProperties()
Returns an unmodifiable copy of the properties associated with the installable unit.

Returns:
an unmodifiable copy of the properties of this installable unit.

getProperty

String getProperty(String key)
Returns the untranslated property of this installable unit associated with the given key. Returns null if no such property is defined.

If the property value has been externalized, this method will return a string containing the translation key rather than a human-readable string. For this reason, clients wishing to obtain the value for a property that is typically translated should use getProperty(String, String) instead.

Parameters:
key - The property key to retrieve a property value for
Returns:
the property that applies to this installable unit or null

getProperty

String getProperty(String key,
                   String locale)
Returns the property of this installable unit associated with the given key. Returns null if no such property is defined or no applicable translation is available.

Parameters:
key - The property key to retrieve a property value for
locale - The locale to translate the property for, or null to use the current locale.
Returns:
the property that applies to this installable unit or null

getProvidedCapabilities

Collection<IProvidedCapability> getProvidedCapabilities()
Returns the collection of capabilities provided by this installable unit.

Returns:
The collection of capabilities provided by this installable unit.

getRequirements

Collection<IRequirement> getRequirements()

getMetaRequirements

Collection<IRequirement> getMetaRequirements()

getTouchpointData

Collection<ITouchpointData> getTouchpointData()

getTouchpointType

ITouchpointType getTouchpointType()

isResolved

boolean isResolved()
Returns whether this installable unit has been resolved. A resolved installable unit represents the union of an installable unit and some fragments.

Returns:
true if this installable unit is resolved, and false otherwise.
See Also:
getFragments(), unresolved()

isSingleton

boolean isSingleton()
Returns whether this installable unit is a singleton. Only one singleton installable unit with a given id is allowed to exist in a given installed system. Attempting to install multiple versions of a singleton will fail.

Returns:
true if this unit is a singleton, and false otherwise
Restriction:
This method is not intended to be referenced by clients.

satisfies

boolean satisfies(IRequirement candidate)
Returns whether this unit has a provided capability that satisfies the given requirement.

Returns:
true if this unit satisfies the given requirement, and false otherwise.

unresolved

IInstallableUnit unresolved()
Returns the unresolved equivalent of this installable unit. If this unit is already unresolved, this method returns the receiver. Otherwise, this method returns an installable unit with the same id and version, but without any fragments attached.

Returns:
The unresolved equivalent of this unit
See Also:
getFragments(), isResolved()

getUpdateDescriptor

IUpdateDescriptor getUpdateDescriptor()
Returns information about what this installable unit is an update of.

Returns:
The lineage information about the installable unit

getLicenses

Collection<ILicense> getLicenses()
Returns the untranslated licenses that apply to this installable unit.

If the license text has been externalized, this method will return strings containing the translation keys rather than human-readable strings. For this reason, clients wishing to obtain a license for display to an end user should use getLicenses(String) instead.

Returns:
the licenses that apply to this installable unit

getLicenses

Collection<ILicense> getLicenses(String locale)
Returns the licenses that apply to this installable unit. Any translation of the licenses for the given locale will be applied. Returns an empty collection if this unit has no licenses, or if the available licenses are externalized and do not have translations available for the given locale.

Parameters:
locale - The locale to translate the license for, or null to use the current locale.
Returns:
the translated licenses that apply to this installable unit

getCopyright

ICopyright getCopyright()
Returns the untranslated copyright that applies to this installable unit.

If the copyright text has been externalized, this method will return strings containing the translation keys rather than human-readable strings. For this reason, clients wishing to obtain a copyright for display to an end user should use getCopyright(String) instead.

Returns:
the copyright that applies to this installable unit or null

getCopyright

ICopyright getCopyright(String locale)
Returns the copyright that applies to this installable unit. Any translation of the copyright for the given locale will be applied. Returns null if this unit has no copyright, or if the copyright is externalized and no translations are available for the given locale.

Parameters:
locale - The locale to translate the copyright for, or null to use the current locale.
Returns:
the copyright that applies to this installable unit or null

equals

boolean equals(Object obj)
Returns whether this InstallableUnit is equal to the given object. This method returns true if:

Overrides:
equals in class Object

Eclipse Platform
Release 3.6

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2010. All rights reserved.