The Resolver service can find a complete and consistent set of transitive dependencies starting with an initial set of mandatory and optional resources. Such a set can be used to install resources in the environment from local or remote repositories. To use the Resolver service, the client must provide a ResolveContext object. This complex object represents the context of a resolution; it provides the initial resources (optional and mandatory), defines a number of namespaces specific policies, and provides the state of the environment.

A resolution can be based on an existing wiring in the environment, for example the current framework state. For the framework, the Resolve Context can find this existing state via the Bundle Wiring API Specification. The Resolver must then satisfy all the requirements of the mandatory resources. The Resolver must always ask the Resolve Context to find additional capabilities for the unsatisfied requirements. A capability is always associated with a resource, which is subsequently associated with additional requirements. The final resolution must contain a set of resources that include the initial set of mandatory resources, has no unsatisfied mandatory requirements, and is consistent with the implied constraints. Otherwise it fails.

The Requirement-Capability model is fully generic but provides special semantics through the use of namespaces. The Resolver must implement the standard OSGi namespaces as described in Bundle Wiring API Specification, which includes the uses constraints. Part of the semantics of the OSGi namespaces are delegated to the Resolve Context so that it can implement different policies. Singletons, ordering of capabilities, and matching are the responsibility of the Resolve Context; the Resolver never matches a requirement to a capability.

Requirements have an effective directive that indicates in what situations the requirement must be resolved. Also here, the Resolve Context decides if a particular requirement is effective or not. Only effective requirements are wired in the resolution.

Since capabilities are declared by resources that have additional requirements, the Resolver must create a set of resources where all transitive requirements are satisfied or fail with a Resolution Exception. This Resolution Exception can provide additional details why the resolution failed, if possible.

At the end of a successful resolve operation the Resolver returns a Map<Resource,List<Wire>>. These wires are a delta on the existing state, if any. The wires can then be used to provision missing resources or to provide diagnostic feedback.

The Resolve Context provides all the parameters for the resolve operation, the Resolver does not maintain any state between invocations. The Resolve Context must therefore provide the mandatory and optional resources, which are essentially the input parameters to the resolve operation. The resolver must find a solution that includes at least the initial mandatory resources and should include the optional resources.

The Resolve Context's findProviders(Requirement) method must be implemented in such a way that it returns an ordered list of capabilities. The Resolver will treat the order of the capabilities as preferences, the first element is more preferred than a later element. The Resolver cannot guarantee that the wiring obeys this preference since there can be other constraints. However, a Resolver must use this preference order for simple cases and try to use it in more constrained situations.

The Resolver does not make any assumptions, this means that the findProviders(Requirement) method must do all the matching. Even though the Resolver gets the mandatory and optional resources it will not search these for capabilities to satisfy requirements. If the findProviders(Requirement) method does not search these resources then their capabilities will not be used. The same is true for the existing wiring state used.

Since this section describes the Resolver with respect to a provisioning agent, the set of resources is not limited to the installed set. That is, normally when a framework is resolved the Resolver only has to include installed resources. However, for a provisioning agent it is possible to retrieve external resources. The [1] Repository Service Specification provides access to resource repositories but a management agent is free to find capabilities by any alternative means.

For resolving an OSGi framework the specifications outlines a number of heuristics that guide the order of wiring bundles and packages:

The Resolver can, and likely will, use the returned list to maintain its internal state during the resolve operation while trying out different potential solutions. It can add and remove capabilities at will. The returned list must therefore be mutable and not reused, after it is returned; it becomes owned by the Resolver. However, the Resolver can call back later with the insertHostedCapability(List,HostedCapability) method, giving back the returned list as the first parameter, see Insert Hosted Capabilities.

For example, assume that all possible resources in the previous example can be gotten with the getSortedResources method in the preferred resource order. This list contains all installed resources as well as any potentially installable resources. This list is sorted once on the given ordering criteria, this only has to be done once and not for each findProviders(Requirement) method invocation. The following code, which does not order by capability versions, could then be a simple skeleton for the findProviders(Requirement) method on the ResolveContextImpl inner class:

public List<Capability> findProviders(Requirement requirement ) {
  List<Capability> result = new ArrayList<Capability>();

  for ( Resource r : getSortedResources() )
    for ( Capability c : r.getCapabilities( null ) )
      if ( match( requirement, c ) )
          result.add( c );

  return result;
}

The findProviders(Requirement) method is responsible for only returning the capabilities that the management agent wants to be considered by the Resolver. Since the Resolver must never match any requirements to capabilities it allows the management agent to fully control the matching. However, in an OSGi environment the following matching behavior is expected:

The following example shows a skeleton match method that provides OSGi semantics:

boolean match(Requirement r, Capability c){
  if ( !r.getNamespace().equals( c.getNamespace() ) )
    return false;

  String effective = c.getDirectives().get("effective");
  if ( !(effective == null || effective.equals( "resolve") ) ) 
    return false;

  String f = r.getDirectives().get( "filter" );
  if ( f  != null ) {
    Filter filter = context.createFilter( f );
    if ( !filter.matches( c.getAttributes() ) )
      return false;
  }

  if ( !c.getNamespace().startsWith( "osgi.wiring." ) )
    return true;

  String mandatory = c.getDirectives().get("mandatory");
  if ( mandatory == null)
    return true;

  List<String> attrs = 
    Arrays.asList( mandatory.toLowerCase().split( "\\s*,\\s*") );

  Matcher m = FILTER_ASSERT_PATTERN.matcher( f == null ? "": f );
  while( m.find() )
    attrs.remove(m.group(1)); // the attribute name

  return mandatory.isEmpty();
}

Resolving to provision a framework is different than a framework resolving itself. During provisioning remote repositories can be consulted to find external resources while the framework only resolves a limited set (the installed bundles). These repositories generally contain magnitudes more bundles than what is installed in a framework.

Repositories do not implement any namespace specific semantics and therefore do not understand any directives. Repositories only verify the requirement's filter (if any) against the capability's attributes. The Resolver expects the Resolve Context to do the namespace specific matching. The [1] Repository Service Specification provides the details for a service that abstracts a Requirement-Capability aware repository.

With such a repository service the findProviders(Requirement) method can be implemented as follows:

List<Repository> repositories = new CopyOnWriteArrayList<Repository>();

void addRepository(  Repository repository) { repositories.add(repository);}
void removeRepository(Repository repository){ repositories.remove(repository);}

public List<Capability> findProviders( Requirement requirement) {
  List<Capability> result = new ArrayList<Capability>();

  // previous findProviders that searches the initial resources

  for ( Repository repository : repositories ) {
     Collection<Capability> capabilities = repository.findProviders(
            Collections.singleton( requirement ) ).get( requirement);
     for ( Capability c : capabilities )
       if ( match( requirement, c ) )
           result.add( c );
  }
  return result;
}

The Resolver service always creates a list of wires that should be added to an existing state. To get the existing state, the ResolveContext interface specifies the getWirings() method. This method must return the existing state as a Map<Resource,Wiring>. A Wiring is an object that reflects the wired state of a resource in the environment. From this object, all declared and hosted capabilities and requirements can be found, including their wires if any. The Resolver needs this existing state to create a consistent resolution. For example, uses constraints require access to the existing state.

The Resolver service API is based on the generic Requirement-Capability model. This API is implemented by the OSGi framework to reflect its internal wiring, see Bundle Wiring API Specification. When the Resolver service is used for an OSGi framework then the Resolve Context can provide the existing wiring state based on the Framework Wiring API. The interfaces used in the org.osgi.framework.wiring package all extend their counterpart in the org.osgi.resource package (the generic model). For example, the BundleCapability interface extends the Capability interface.

The framework wiring API models all the power and complexities of the OSGi framework. One of those aspects is removal pending. Each installed bundle is represented by one or more bundle revisions. Each bundle revision is a Resource object but only one is the current bundle revision. During a resolve operation a framework can actually wire to the current bundle revision but is not forbidden to also select the pending removal bundle revisions. The Resolve Context must therefore decide if it provides only the current bundle revisions or all. The best policy solution in this case is to always refresh after a (batch) of install operations and only resolve when there are no pending-removal bundle revisions. However, certain management agents attempt to manage a system that is in this half-way state and will then be required to include the pending-removal revisions.

The following example code shows a possible implementation of the getWirings() method. It only uses the current wiring and ignores removal pending bundle revisions:

public Map<Resource,Wiring> getWirings(){
    Map<Resource,Wiring> wirings = new HashMap<Resource,Wiring>();

   for ( Bundle b : context.getBundles() ) {
     BundleRevision revision = b.adapt( BundleRevision.class);
     if ( revision != null ) {
       Wiring wiring = revision.getWiring();
       if ( wiring != null )
           wirings.put( revision, wiring );
     }
   }
   return wirings;
}

A wiring for a resource may also have a subset of required wires which substitute capabilities provided by the resource or one of its attached fragment resources. The getSubstitutionWires(Wiring) method is called by the resolver in order to find the wires that substitute capabilities of the wiring. For example, when a wiring provides a osgi.wiring.bundle capability that is used to resolve one or more osgi.wiring.bundle requirements. In this case the resolver needs to discover which capabilities have been substituted in order to ensure a consistent class space (see Requiring Bundles). In order to get the capabilities which have been substituted, the resolver asks the resolve context to return the substitution wires for the wiring.

Note that the default implementation of this method searches all the osgi.wiring.package capabilities which are declared as provided by the resource associated with the wiring and fragment resources wired to the wiring with the osgi.wiring.host namespace. The provided capabilities 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.

The Resolver service is designed to work with OSGi frameworks but the scope is broader; its design allows many alternative usages. The effective directive on the capabilities and requirements is meant to allow requirements and capabilities to be effective in different phases. The default is resolve, the value for an OSGi framework resolving process. Bundles and other OSGi defined artifacts must declare their capabilities and requirements in the resolve effective time to be considered by an OSGi resolver.

However, Resolvers can use the effective directive to run the Resolver at other times than the standard OSGi framework resolve. For example, it could be possible to define an active time to resolve the service dependencies.

For this reason, the Resolver is designed to be agnostic for this directive, it will always ask the ResolveContext if a requirement is effective. It does this with the isEffective(Requirement) method. Since the Resolver service never matches requirements to capabilities it is also up to the Resolve Context to decide how to treat the effective directive. For an OSGi resolve operation, capabilities should also have an effective time value of resolve (or not set since resolve is the default).

To make requirements effective during the resolving of bundles it will be necessary to implement the isEffective(Requirement) method similar to:

public boolean isEffective( Requirement requirement) {
  String e = requirement.getDirectives().get( "effective");
  return e==null || "resolve".equals( e );
}

One of the complex aspects of resolving for an OSGi framework is handling fragments. For fragments, the declared capabilities are going to be hosted by their hosts. The Requirement and Capability objects have a getResource method that returns the associated resource. For hosted capabilities and requirements this must be the hosting resource and for others the declaring resource.

The HostedCapability interface defines the interface for allowing the hosting resource to be returned instead of the declaring resource. Since the Resolver service creates these Hosted Capabilities the Resolver needs a way to add them to the lists of capabilities returned from findProviders(Requirement). The Resolver service cannot add them itself since this list has a preference order, the Resolver service must therefore ask the Resolve Context to insert this new capability to allow the Resolve Context to maintain the desired order.

The Resolve Context must therefore implement an insertHostedCapability(List,HostedCapability) method. The given list must have been returned earlier from a findProviders(Requirement) method invocation. The Resolve Context must find the appropriate position to insert the HostedCapability object, insert it, and return the index of the inserted object.

It is the responsibility of the Resolve Context to find the proper position. In Finding Capabilities it was discussed how the findProviders(Requirement) method must return an ordered list. The insertHostedCapability(List,HostedCapability) has that same responsibility.

The following example shows how the Hosted Capability is inserted based on the index of the hosted resource's index in the sorted list of resources the management agent maintained. The example iterates through the capabilities and compares the index of sorted resources to indicate preference. If it finds a capability from a resource that was later in the list of sorted resources then it inserts it at that position. A real implementation should also take the version of the capability into account.

public int insertHostedCapability( 
    List<Capability> caps, HostedCapability hc ) {

    List<Resource> resources = getSortedResources();
    int index = resources.indexOf( hc.getResource() );

    for ( int i =0; i < caps.size(); i++ ) {
        Capability c = caps.get( i );
        int otherIndex = resources.indexOf( c.getResource() );
        if ( otherIndex > index ) {
            caps.add( i, hc );
            return i;
        }
    }
    caps.add( hc );
    return caps.size()-1;
}

Fragments are resources that have an osgi.wiring.host requirement that must match a capability from one or more host bundles. However, for example an Export-Package in a fragment must be merged with its attached hosts. These capabilities and requirements from namespaces that appear as if they come from the host bundle are called hosted.

When resolving a set of resources it must be possible to pull in any available fragments which may attach to the resource. Since fragments are not required by the host bundle, there will be no resource requiring the fragment bundles. However, fragments will require their hosts. A Resolver should attach any fragments available in a resolution to suitable hosts.

In order to discover additional fragments which may be attached to the resources in a resolution the findRelatedResources(Resource) method is called by the resolver . The resolver attempts to also resolve the related resources during the current resolve operation. Failing to resolve one of the related resources must not result in a resolution exception unless the related resource is also considered a mandatory resource.

A resolve context may consider a fragment to be a related resource for the hosts it can attach to. In order for the resolver to pull the fragments into the resolve operation the resolve context is asked to return the related resources of each host bundle which is to be resolved. The resolve context may decide if the fragments of the host needs to be resolved along with the host. Note that fragments are used as an example of a related resource. The resolve context is free to use any type of resource as a related resource.

Fragments can of course also be found by the normal finding of capabilities.

A resource can be marked as a singleton. A singleton resource has the singleton directive set to true on the osgi.identity capability. A singleton resource conflicts with another singleton resource if:

This constraint is not enforced by the Resolver service to give more flexibility to management agents. The Resolve Context must ensure that it does not return capabilities from conflicting singleton resources from the findProviders(Requirement) method. When the Resolver is used with a limited set of resources then it is possible to enumerate all singletons ahead of time and use permutations. However, when repositories are used an incremental method works better because the scope is so much larger.

When the findProviders(Requirement) method is called for a requirement that selects a capability declared in a singleton then it is likely that repositories will return multiple versions of this singleton including the resource with the highest available version for conflicting resources. It is therefore possible to maintain a white list of singletons incrementally.

Once the findProviders(Requirement) method has created a result list, it is possible to prune this list of conflicting singletons. This can be an incremental process, the first time a singleton is encountered in such a list of capabilities the highest version can be selected as the singleton. Other singletons that are in that list or come in other invocations of findProviders(Requirement) can then no longer provide capabilities. For example:

    Map<String,Resource> whitelist = new HashMap<String,Resource>();
    
    void prune( List<Capability> list ) {
        Map<String,Resource> singletons = new HashMap<String,Resource>();

        for ( Capability c : list) {
            Resource r = c.getResource();
            Version now = getVersion( r );
            String identity = getIdentity( r );

            if ( isSingleton( r ) && !whitelist.containsKey(identity ) ) {
                Resource selected = singletons.get( identity );
                if ( selected == null )
                    singletons.put( identity, r );
                else {
                    Version old = getVersion( selected );
                    if ( now.compareTo( old )> 0 )
                        singletons.put( identity, r );
                }
            }
      }

      this.whitelist.putAll( singletons );
        
        for ( Iterator<Capability> i=list.iterator(); i.hasNext();) {
            Capability c = i.next();
            Resource r = c.getResource();
            String identity = getIdentity( r );
            Resource selected = this.whitelist.get( identity );
            if ( selected != null && !selected.equals( r ))
                i.remove();
        }
  }

The Resolver service throws a ResolutionException when the resolve operation cannot find a solution. This Exception provides the standard human readable message. However, there is also the getUnresolvedRequirements() method. With this method it is possible to find what requirements could not be matched. Though this is very useful in many cases it must be realized that resolving is a complicated process. It is not possible to establish the exact set of missing requirements because any unresolved resolution can have many, different, sets of unresolved requirements. This is an intrinsic part of the resolution problem. There is also no guarantee that providing capabilities that satisfy these requirements will give a successful resolution. There could still be other constraints that cannot be satisfied. In general, the Resolve Context can already detect any unresolved mandatory requirements when it cannot find a matching capability in the findProviders(Requirement) method.

That said, the getUnresolvedRequirements() can often point to a potential solution.

Some resolution operations can be long running, and therefore a resolve context may want to cancel the currently running resolve operation. The resolver must register a single runnable callback with the resolve context that is associated with the currently running resolve operation. The onCancel(Runnable) method must be invoked by the resolver implementation before any other method on the resolve context is invoked. The resolve context invokes the callback to cancel the currently running resolve operation that appears to be running endlessly or at risk of running out of resources. The resolve context may give up on the resolve operation or attempt to try another resolve operation with a smaller set of resources which may allow the resolve operation to complete normally.

Implementing a Resolve Context is a non-trivial task that requires extensive knowledge of the OSGi framework, especially the module layer. Though this section contains numerous code examples, they are not sufficient to implement a real Resolve Context since this would require too much code for a specification.

The resolve(ResolveContext) method uses a Resolve Context to provide the context and parameters of the resolution. During the resolution process the Resolver service can callback the Resolve Context to retrieve the following information:

The Resolver service returns the following:

The resolve(ResolveContext) method returns a resolution D that is a delta on the existing Wiring state X. It is up to the Resolve Context to ensure that the delta D is installed. In for example the OSGi framework the framework hooks can be used to guide the framework's resolving process.

The goal of the Resolver is to provide a set of wires between a set of resolved resources. A resource is resolved when all its mandatory and effective requirements are satisfied by capabilities from resolved resources. A Resolver must not return wires between resources that have unsatisfied mandatory requirements.

A mandatory requirement has a resolution directive that is not set or that is set to mandatory. The effectiveness of a requirement is defined by the Resolve Context, a Resolver service must call the isEffective(Requirement) method to establish if a requirement is effective for a given resolve operation. A Resolver must never create a wire from a requirement that is not effective.

To find a resolution, the Resolver must use the Resolve Context to find candidate capabilities for the requirements declared in the resources that it needs to resolve. A candidate capability is a capability that satisfies the requirement. From the perspective of the Resolver service, a requirement is satisfied by a capability when that capability is returned from the findProviders(Requirement) method. A Resolver has no alternative way to find out if a requirement is satisfied by a capability and must therefore not make any assumptions about matching. Any matching rules like for example the osgi.wiring.* mandatory directive must be implemented by the Resolve Context. A Resolve Context must always return the same capabilities during a resolving operation when given the same requirement.

Since the resolver cannot match requirements and capabilities the Resolve Context must return capabilities for all possible resources, this must include:

It can include additional resources that were indirectly returned through the findProviders(Requirement) method.

The existing wiring X and its substitution wires S provides an existing set of constraints that the Resolver service must abide by. It can get this state with the getWirings() and getSubstitutionWires(Wiring) methods. The purpose of the existing state is to ensure that any wires are compatible with existing wiring. For an OSGi framework it is crucial that the uses constraints are maintained for the resolution, see Module Layer.

The Resolver service can wire new requirements to existing capabilities but it can never create wires for an existing requirement from the existing wiring unless the resolve process is for a dynamic resolve, see Dynamic Resolving.

If the Resolver service attaches a hosted resource like a fragment, and thereby needs to add new HostedCapability objects to a previously returned list from findProviders(Requirement) then it must call the Resolve Context's insertHostedCapability(List,HostedCapability) method.

Fragments can be attached to resolved resources or to resources that declare the capabilities returned from findProviders(Requirement), that is, C_env. Additional resources are also pulled into the resolve operation by invoking the findRelatedResources(Resource) method on the resolve context. As part of the related resources the resolve context can include fragments to be considered as part of the resolve operation. This allows the available fragments to be resolved when the host is being resolved.

This specification does not define the detailed rules and constraints associated with resolving; these rules are defined in their namespaces. An OSGi Resolver service must support at least all namespaces defined in Framework Namespaces Specification except for the following directives:

A Resolver service must support the uses constraints and any applicable rule defined in the Module Layer for the osgi.wiring.* namespaces.

The Resolver must return a delta wiring to the existing state (potentially empty) or throw an Exception. The resolution:

The resolveDynamic(ResolveContext,Wiring,Requirement) method is used to resolve a dynamic requirement for an existing host wiring. For example, this method can be used to resolve dynamic package imports as specified by the DynamicImport-Package manifest header. This method may resolve additional resources in order to resolve the dynamic requirement. Dynamic resolving must return a resolution D that is a delta on the existing Wiring state X or throw a ResolutionException if the dynamic requirement cannot be resolved.

The delta must contain the host resource of the host wiring as a key. The list of wires for the host resource entry will contain a single wire that resolves the dynamic requirement to a valid capability. The delta wiring may also contain additional resources that are necessary to resolve the dynamic requirement.

To find a dynamic resolution D, the Resolver must use the Resolve Context in the same way as normal resolving except the Resolve Context is not asked for mandatory or optional resources as provided by getMandatoryResources() and getOptionalResources(). The Resolve Context is asked to find providers for the dynamic requirement as provided by findProviders(Requirement).

The Resolver assumes the following about the host wiring and the dynamic requirement:

The Resolver is not required to validate these assumptions. If these assumptions are not true then the result of the dynamic resolution is not specified.

The Resolver uses the dynamic requirement to call findProviders(Requirement) in order to find valid matching capabilities. In order for a matching capability to be considered as valid it must satisfy the following rules:

The Resolver assumes the matching capabilities are valid. If invalid capabilities are returned by the Resolve Context then the result of the dynamic resolution is not specified.

At this point the dynamic resolution continues on as a normal resolution where the host wiring resource is considered a mandatory resource and the dynamic requirement is considered a mandatory requirement. The resources providing the matching capabilities to the dynamic requirement are then resolved as in a normal resolution operation.

If the Resolver cannot find a solution or it runs into problems then it must throw a Resolution Exception, which is a Runtime Exception.

The ResolutionException provides the getUnresolvedRequirements() method. If the resolution failed then it is possible that this was caused because it failed to find matches for certain requirements. The information in this method can be very helpful to find a solution that will work, however, there are a number of caveats.

Resolving is an NP-complete problem. For these problems there exists no algorithm that can infer a solution from the desired outcome. Therefore, the Resolver tries a potential solution and if that solution does not match the constraints it will backtrack and attempt another solution. An unavoidable aspect of such solutions is that it is impossible to pin-point a single failure point if the algorithm fails to find a solution, in general the algorithm gives up after having exhausted its search space. However, during its search it might have been very close to a solution, for example it only missed a single requirement, but its final failure missed many requirements.

The implication is that the reported missing requirements neither give a guarantee for a resolution when satisfied nor indicate that this is the smallest set of missing requirements.

Therefore, getUnresolvedRequirements() is intended for human consumption and not for automated solutions.

The Resolver service is a pure function that has no state. The Resolve Context maintains the state and is therefore the actor that requires most permissions. In general, it will require access to the Wiring API and Repositories.

Since the Resolver requires no external access it does not have to be a trusted service. Resolve Contexts that support security must ensure that the callbacks are executed in a privileged block.

PackagePermission[org.osgi.service.resolver,IMPORT]
ServicePermission[...Resolver, REGISTER ]

PackagePermission[org.osgi.service.repository,IMPORT]
PackagePermission[org.osgi.service.resolver,IMPORT]
PackagePermission[org.osgi.resource,IMPORT]
PackagePermission[org.osgi.framework.wiring,IMPORT]
PackagePermission[org.osgi.framework.namespaces,IMPORT]
ServicePermission[...Resolver, GET ]
... likely needs AdaptPermissions and ServicePermission[...Repository,GET]