OSGi 8.1.0 · org.osgi.service.resolver.ResolveContext

Access	Constructor and Description
public	ResolveContext()

Method Summary

Modifier and Type	Method and Description
private static <T> Collection<T>	emptyCollection()
public abstract List<Capability>	Returns: A list of `Capability` objects that match the specified requirement. findProviders(Requirement The requirement that a resolver is attempting to satisfy. Must not be `null`. requirement) Find Capabilities that match the given Requirement.
public Collection<Resource>	Returns: A collection of the resources that the resolver should attempt to resolve for this resolve context. May be empty if there are no related resources. The returned collection may be unmodifiable. findRelatedResources(Resource The Resource that a resolver is attempting to find related resources for. Must not be `null`. resource) Find resources that are related to the given resource.
public Collection<Resource>	Returns: A collection of the resources that must be resolved for this resolve context. May be empty if there are no mandatory resources. The returned collection may be unmodifiable. getMandatoryResources() Return the resources that must be resolved for this resolve context.
public Collection<Resource>	Returns: A collection of the resources that the resolver should attempt to resolve for this resolve context. May be empty if there are no optional resources. The returned collection may be unmodifiable. getOptionalResources() Return the resources that the resolver should attempt to resolve for this resolve context.
public List<Wire>	Returns: A list containing a snapshot of the substitution `Wire`s for the `requirements` of the wiring, or an empty list if the wiring has no substitution wires. The list contains the wires in the order they are found in the `required` wires of the wiring. getSubstitutionWires(Wiring the wiring to get the substitution wires for. Must not be `null`. wiring) Returns the subset of `required` wires that provide wires to `capabilities` which substitute capabilities of the wiring.
public abstract Map<Resource, Wiring>	Returns: The wirings for existing resolved resources. The returned map is unmodifiable. getWirings() Returns the wirings for existing resolved resources.
public abstract int	Returns: The index in the list of the inserted HostedCapability. insertHostedCapability(List<Capability> The list returned from `findProviders(Requirement)`. Must not be `null`. capabilities, HostedCapability The HostedCapability to insert in the specified list. Must not be `null`. hostedCapability) Add a `HostedCapability` to the list of capabilities returned from `findProviders(Requirement)`.
public abstract boolean	Returns: `true` if the requirement should be considered as part of the resolve operation. isEffective(Requirement The Requirement to test. Must not be `null`. requirement) Test if a given requirement should be wired in the resolve operation.
public void	onCancel(Runnable the callback to execute in order to cancel the resolve operation. Must not be `null`. callback) Registers a callback with the resolve context that is associated with the currently running resolve operation.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

ResolveContext	back to summary
public ResolveContext()

Method Detail

emptyCollection	back to summary
private static <T> Collection<T> emptyCollection() Annotations @SuppressWarnings:unchecked

findProviders back to summary

findProviders	back to summary
public abstract List<Capability> findProviders(Requirement requirement) Find Capabilities that match the given Requirement. The returned list contains `Capability` objects where the Resource must be the declared Resource of the Capability. The Resolver can then add additional `HostedCapability` objects with the `insertHostedCapability(List, HostedCapability)` method when it, for example, attaches fragments. Those `HostedCapability` objects will then use the host's Resource which likely differs from the declared Resource of the corresponding Capability. The returned list is in priority order such that the Capabilities with a lower index have a preference over those with a higher index. The resolver must use the `insertHostedCapability(List, HostedCapability)` method to add additional Capabilities to maintain priority order. In general, this is necessary when the Resolver uses Capabilities declared in a Resource but that must originate from an attached host. Each returned Capability must match the given Requirement. This means that the filter in the Requirement must match as well as any namespace specific directives. For example, the mandatory attributes for the `osgi.wiring.package` namespace. Parameters requirement:Requirement The requirement that a resolver is attempting to satisfy. Must not be `null`. Returns:List<Capability> A list of `Capability` objects that match the specified requirement.

public abstract List<Capability> findProviders(Requirement requirement)

Find Capabilities that match the given Requirement.

The returned list contains Capability objects where the Resource must be the declared Resource of the Capability. The Resolver can then add additional HostedCapability objects with the insertHostedCapability(List, HostedCapability) method when it, for example, attaches fragments. Those HostedCapability objects will then use the host's Resource which likely differs from the declared Resource of the corresponding Capability.

The returned list is in priority order such that the Capabilities with a lower index have a preference over those with a higher index. The resolver must use the insertHostedCapability(List, HostedCapability) method to add additional Capabilities to maintain priority order. In general, this is necessary when the Resolver uses Capabilities declared in a Resource but that must originate from an attached host.

Each returned Capability must match the given Requirement. This means that the filter in the Requirement must match as well as any namespace specific directives. For example, the mandatory attributes for the osgi.wiring.package namespace.

Parameters

requirement:Requirement: The requirement that a resolver is attempting to satisfy. Must not be null.

Returns:List<Capability>

A list of Capability objects that match the specified requirement.

findRelatedResources back to summary

findRelatedResources	back to summary
public Collection<Resource> findRelatedResources(Resource resource) Find resources that are related to the given resource. The resolver attempts to resolve related resources during the current resolve operation. Failing to resolve one of the related resources will not result in a resolution exception unless the related resource is also a `mandatory` resource. The resolve context is asked to return related resources for each resource that is pulled into a resolve operation. This includes the `mandatory` and `optional` resources and each related resource returned by this method. For example, a fragment can be considered a related resource for a host bundle. When a host is being resolved the resolve context will be asked if any related resources should be added to the resolve operation. The resolve context may decide that the potential fragments of the host should be resolved along with the host. Parameters resource:Resource The Resource that a resolver is attempting to find related resources for. Must not be `null`. Returns:Collection<Resource> A collection of the resources that the resolver should attempt to resolve for this resolve context. May be empty if there are no related resources. The returned collection may be unmodifiable. Since 1.1

public Collection<Resource> findRelatedResources(Resource resource)

Find resources that are related to the given resource.

The resolver attempts to resolve related resources during the current resolve operation. Failing to resolve one of the related resources will not result in a resolution exception unless the related resource is also a mandatory resource.

The resolve context is asked to return related resources for each resource that is pulled into a resolve operation. This includes the mandatory and optional resources and each related resource returned by this method.

For example, a fragment can be considered a related resource for a host bundle. When a host is being resolved the resolve context will be asked if any related resources should be added to the resolve operation. The resolve context may decide that the potential fragments of the host should be resolved along with the host.

Parameters

resource:Resource: The Resource that a resolver is attempting to find related resources for. Must not be null.

Returns:Collection<Resource>

A collection of the resources that the resolver should attempt to resolve for this resolve context. May be empty if there are no related resources. The returned collection may be unmodifiable.

Since

1.1

getMandatoryResources	back to summary
public Collection<Resource> getMandatoryResources() Return the resources that must be resolved for this resolve context. The default implementation returns an empty collection. Returns:Collection<Resource> A collection of the resources that must be resolved for this resolve context. May be empty if there are no mandatory resources. The returned collection may be unmodifiable.

getMandatoryResources

back to summary

public Collection<Resource> getMandatoryResources()

Return the resources that must be resolved for this resolve context.

The default implementation returns an empty collection.

Returns:Collection<Resource>: A collection of the resources that must be resolved for this resolve context. May be empty if there are no mandatory resources. The returned collection may be unmodifiable.

getOptionalResources	back to summary
public Collection<Resource> getOptionalResources() Return the resources that the resolver should attempt to resolve for this resolve context. Inability to resolve one of the specified resources will not result in a resolution exception. The default implementation returns an empty collection. Returns:Collection<Resource> A collection of the resources that the resolver should attempt to resolve for this resolve context. May be empty if there are no optional resources. The returned collection may be unmodifiable.

getOptionalResources

back to summary

public Collection<Resource> getOptionalResources()

Return the resources that the resolver should attempt to resolve for this resolve context. Inability to resolve one of the specified resources will not result in a resolution exception.

The default implementation returns an empty collection.

Returns:Collection<Resource>: A collection of the resources that the resolver should attempt to resolve for this resolve context. May be empty if there are no optional resources. The returned collection may be unmodifiable.

getSubstitutionWires back to summary

getSubstitutionWires	back to summary
public List<Wire> getSubstitutionWires(Wiring wiring) Returns the subset of `required` wires that provide wires to `capabilities` which substitute capabilities of the wiring. For example, when a `package` name is both provided and required by the same resource. If the package requirement is resolved to a capability provided by a different wiring then the package capability is considered to be substituted. The resolver asks the resolve context to return substitution wires for each wiring that `provides` a `bundle` namespace capability that is used to resolve one or more bundle requirements. Note that this method searches all the `package` capabilities declared as `provided` by the resource associated with the wiring and fragment resources wired to the wiring with the `host` namespace. The provided package names are compared against the `required` package wires to determine which wires are substitution wires. Subclasses of `ResolveContext` should provide a more efficient implementation of this method. Parameters wiring:Wiring the wiring to get the substitution wires for. Must not be `null`. Returns:List<Wire> A list containing a snapshot of the substitution `Wire`s for the `requirements` of the wiring, or an empty list if the wiring has no substitution wires. The list contains the wires in the order they are found in the `required` wires of the wiring. Since 1.1

public List<Wire> getSubstitutionWires(Wiring wiring)

Returns the subset of required wires that provide wires to capabilities which substitute capabilities of the wiring. For example, when a package name is both provided and required by the same resource. If the package requirement is resolved to a capability provided by a different wiring then the package capability is considered to be substituted.

The resolver asks the resolve context to return substitution wires for each wiring that provides a bundle namespace capability that is used to resolve one or more bundle requirements.

Note that this method searches all the package capabilities declared as provided by the resource associated with the wiring and fragment resources wired to the wiring with the host namespace. The provided package names are compared against the required package wires to determine which wires are substitution wires. Subclasses of ResolveContext should provide a more efficient implementation of this method.

Parameters

wiring:Wiring: the wiring to get the substitution wires for. Must not be null.

Returns:List<Wire>

A list containing a snapshot of the substitution Wires for the requirements of the wiring, or an empty list if the wiring has no substitution wires. The list contains the wires in the order they are found in the required wires of the wiring.

Since

1.1

getWirings	back to summary
public abstract Map<Resource, Wiring> getWirings() Returns the wirings for existing resolved resources. For example, if this resolve context is for an OSGi framework, then the result would contain all the currently resolved bundles with each bundle's current wiring. Multiple calls to this method for this resolve context must return the same result. Returns:Map<Resource, Wiring> The wirings for existing resolved resources. The returned map is unmodifiable.

getWirings

back to summary

public abstract Map<Resource, Wiring> getWirings()

Returns the wirings for existing resolved resources.

For example, if this resolve context is for an OSGi framework, then the result would contain all the currently resolved bundles with each bundle's current wiring.

Multiple calls to this method for this resolve context must return the same result.

Returns:Map<Resource, Wiring>: The wirings for existing resolved resources. The returned map is unmodifiable.

insertHostedCapability back to summary

insertHostedCapability	back to summary
public abstract int insertHostedCapability(List<Capability> capabilities, HostedCapability hostedCapability) Add a `HostedCapability` to the list of capabilities returned from `findProviders(Requirement)`. This method is used by the `Resolver` to add Capabilities that are hosted by another Resource to the list of Capabilities returned from `findProviders(Requirement)`. This function is necessary to allow fragments to attach to hosts, thereby changing the origin of a Capability. This method must insert the specified HostedCapability in a place that makes the list maintain the preference order. It must return the index in the list of the inserted `HostedCapability`. Parameters capabilities:List<Capability> The list returned from `findProviders(Requirement)`. Must not be `null`. hostedCapability:HostedCapability The HostedCapability to insert in the specified list. Must not be `null`. Returns:int The index in the list of the inserted HostedCapability.

public abstract int insertHostedCapability(List<Capability> capabilities, HostedCapability hostedCapability)

Add a HostedCapability to the list of capabilities returned from findProviders(Requirement).

This method is used by the Resolver to add Capabilities that are hosted by another Resource to the list of Capabilities returned from findProviders(Requirement). This function is necessary to allow fragments to attach to hosts, thereby changing the origin of a Capability. This method must insert the specified HostedCapability in a place that makes the list maintain the preference order. It must return the index in the list of the inserted HostedCapability.

Parameters

capabilities:List<Capability>: The list returned from findProviders(Requirement). Must not be null.
hostedCapability:HostedCapability: The HostedCapability to insert in the specified list. Must not be null.

Returns:int

The index in the list of the inserted HostedCapability.

isEffective back to summary

isEffective	back to summary
public abstract boolean isEffective(Requirement requirement) Test if a given requirement should be wired in the resolve operation. If this method returns `false`, then the resolver should ignore this requirement during the resolve operation. The primary use case for this is to test the `effective` directive on the requirement, though implementations are free to use any effective test. Parameters requirement:Requirement The Requirement to test. Must not be `null`. Returns:boolean `true` if the requirement should be considered as part of the resolve operation.

public abstract boolean isEffective(Requirement requirement)

Test if a given requirement should be wired in the resolve operation. If this method returns false, then the resolver should ignore this requirement during the resolve operation.

The primary use case for this is to test the effective directive on the requirement, though implementations are free to use any effective test.

Parameters

requirement:Requirement: The Requirement to test. Must not be null.

Returns:boolean

true if the requirement should be considered as part of the resolve operation.

onCancel back to summary

onCancel	back to summary
public void onCancel(Runnable callback) Registers a callback with the resolve context that is associated with the currently running resolve operation. The callback can be executed in order to cancel the currently running resolve operation. When a resolve operation begins, the resolver must call this method once and only once for the duration of the resolve operation and that call must happen before calling any other method on this resolve context. If the specified callback is executed then the resolver must cancel the currently running resolve operation and throw a `ResolutionException` with a cause of type `CancellationException`. The callback allows a resolve context to cancel a long running resolve operation that appears to be running endlessly or at risk of running out of resources. The resolve context may then decide to give up on resolve operation or attempt to try another resolve operation with a smaller set of resources which may allow the resolve operation to complete normally. Parameters callback:Runnable the callback to execute in order to cancel the resolve operation. Must not be `null`. Exceptions IllegalStateException: if the resolver attempts to register more than one callback for a resolve operation Since 1.1

public void onCancel(Runnable callback)

Registers a callback with the resolve context that is associated with the currently running resolve operation. The callback can be executed in order to cancel the currently running resolve operation.

When a resolve operation begins, the resolver must call this method once and only once for the duration of the resolve operation and that call must happen before calling any other method on this resolve context. If the specified callback is executed then the resolver must cancel the currently running resolve operation and throw a ResolutionException with a cause of type CancellationException.

The callback allows a resolve context to cancel a long running resolve operation that appears to be running endlessly or at risk of running out of resources. The resolve context may then decide to give up on resolve operation or attempt to try another resolve operation with a smaller set of resources which may allow the resolve operation to complete normally.

Parameters

callback:Runnable: the callback to execute in order to cancel the resolve operation. Must not be null.

Exceptions

IllegalStateException:: if the resolver attempts to register more than one callback for a resolve operation

Since

1.1

public abstract Class ResolveContext

Constructor Summary

Method Summary

Constructor Detail

Method Detail