org.osgi.service.resolver
Interface Resolver

All Known Subinterfaces:

FelixResolver

All Known Implementing Classes:

ResolverImpl

public interface Resolver

A resolver is a service interface that can be used to find resolutions for specified resources based on a supplied Environment.

Version:

$Id: 5735a30be6494040afe5a05cadf353cf0ce943a0 $

Method Summary

java.util.Map<Resource,java.util.List<Wire>>

resolve(Environment environment, java.util.Collection<? extends Resource> mandatoryResources, java.util.Collection<? extends Resource> optionalResources) Attempt to resolve the resources based on the specified environment and return any new resources and wires to the caller.

Method Detail

resolve

java.util.Map<Resource,java.util.List<Wire>> resolve(Environment environment,
                                                     java.util.Collection<? extends Resource> mandatoryResources,
                                                     java.util.Collection<? extends Resource> optionalResources)
                                                     throws ResolutionException

Attempt to resolve the resources based on the specified environment and return any new resources and wires to the caller.

The resolver considers two groups of resources:

• Mandatory - any resource in the mandatory group must be resolved, a failure to satisfy any mandatory requirement for these resources will result in a ResolutionException
• Optional - any resource in the optional group may be resolved, a failure to satisfy a mandatory requirement for a resource in this group will not fail the overall resolution but no resources or wires will be returned for this resource.

Delta

The resolve method returns the delta between the start state defined by Environment#getWiring() and the end resolved state, i.e. only new resources and wires are included. To get the complete resolution the caller can merge the start state and the delta using something like the following:

 Map<Resource, List<Wire>> delta = resolver.resolve(env, resources, null);
 Map<Resource, List<Wire>> wiring = env.getWiring();

 for (Map.Entry<Resource, List<Wire>> e : delta.entrySet()) {
   Resource res = e.getKey();
   List<Wire> newWires = e.getValue();

   List<Wire> currentWires = wiring.get(res);
   if (currentWires != null) {
     newWires.addAll(currentWires);
   }

   wiring.put(res, newWires);
 }
 

Consistency

For a given resolve operation the parameters to the resolve method should be considered immutable. This means that resources should have constant capabilities and requirements and an environment should return a consistent set of capabilities, wires and effective requirements.

The behavior of the resolver is not defined if resources or the environment supply inconsistent information.

Parameters:

environment - the environment into which to resolve the requirements

mandatoryResources - The resources that must be resolved during this resolution step or null if no resources must be resolved

optionalResources - Any resources which the resolver should attempt to resolve but that will not cause an exception if resolution is impossible or null if no resources are optional.

Returns:

the new resources and wires required to satisfy the requirements

Throws:

ResolutionException - if the resolution cannot be satisfied for any reason

java.lang.NullPointerException - if environment is null