Package 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.

    Instances of this class are handle objects and do not necessarily reflect entities that exist in any particular profile or repository. These handle objects can be created using MetadataFactory.

    Since:
    2.0
    See Also:
    MetadataFactory.createInstallableUnit(org.eclipse.equinox.p2.metadata.MetadataFactory.InstallableUnitDescription)
    Restriction:
    This interface is not intended to be implemented by clients.
    Restriction:
    This interface is not intended to be extended by clients.

    • 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_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.

      • 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:
        • Both this object and the given object are of type IInstallableUnit
        • The result of getId() on both objects are equal
        • The result of getVersion() on both objects are equal
        Overrides:
        equals in class Object