@ConsumerType public abstract class ResolveContext extends java.lang.Object
capabilitiesthat the Resolver can use to satisfy
getWirings()method. A wiring consists of a map of existing
A resolver may call the methods on the resolve context any number of times during a resolve operation using any thread. Implementors should ensure that this class is properly thread safe.
insertHostedCapability(List, HostedCapability) and
onCancel(Runnable), the resolve context methods must be
idempotent. This means that resources must have constant capabilities
and requirements and the resolve context must return a consistent set of
capabilities, wires and effective requirements.
|Constructor and Description|
|Modifier and Type||Method and Description|
Find Capabilities that match the given Requirement.
Find resources that are related to the given resource.
Return the resources that must be resolved for this resolve context.
Return the resources that the resolver should attempt to resolve for this resolve context.
Returns the wirings for existing resolved resources.
Test if a given requirement should be wired in the resolve operation.
Registers a callback with the resolve context that is associated with the currently running resolve operation.
public java.util.Collection<Resource> getMandatoryResources()
The default implementation returns an empty collection.
public java.util.Collection<Resource> getOptionalResources()
The default implementation returns an empty collection.
public abstract java.util.List<Capability> findProviders(Requirement requirement)
The returned list contains
Capability objects where the Resource
must be the declared Resource of the Capability. The Resolver can then
HostedCapability objects with the
insertHostedCapability(List, HostedCapability) method when it,
for example, attaches fragments. Those
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
requirement- The requirement that a resolver is attempting to satisfy. Must not be
Capabilityobjects that match the specified requirement.
public abstract int insertHostedCapability(java.util.List<Capability> capabilities, HostedCapability hostedCapability)
HostedCapabilityto the list of capabilities returned from
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
capabilities- The list returned from
findProviders(Requirement). Must not be
hostedCapability- The HostedCapability to insert in the specified list. Must not be
public abstract boolean isEffective(Requirement requirement)
false, then the resolver should ignore this requirement during the resolve operation.
The primary use case for this is to test the
on the requirement, though implementations are free to use any effective
requirement- The Requirement to test. Must not be
trueif the requirement should be considered as part of the resolve operation.
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.
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
The resolve context is asked to return related resources for each
resource that is pulled into a resolve operation. This includes the
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.
resource- The Resource that a resolver is attempting to find related resources for. Must not be
public void onCancel(java.lang.Runnable callback)
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
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.
callback- the callback to execute in order to cancel the resolve operation. Must not be
java.lang.IllegalStateException- if the resolver attempts to register more than one callback for a resolve operation
requiredwires that provide wires to
capabilitieswhich substitute capabilities of the wiring. For example, when a
packagename 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.
Note that this method searches all the
capabilities declared as
provided by the resource associated with the wiring and fragment
resources wired to the wiring with the
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.
wiring- the wiring to get the substitution wires for. Must not be
Wires for the
requirementsof 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
requiredwires of the wiring.
Copyright © OSGi Alliance (2000, 2018). All Rights Reserved. Licensed under the OSGi Specification License, Version 2.0