A handler bundle that needs to manage the wiring between bundles must register a Resolver Hook Factory service. For each resolve operation the Resolver needs to perform, the framework asks each Resolver Hook Factory service for a new Resolver Hook specific for the operation. During the resolve operation, the Resolver will allow the Resolver Hooks to remove candidate solutions and assist in selecting singletons.

The Resolver is triggered by activity in the OSGi framework. Calling certain methods on a bundle when a bundle is in the INSTALLED state will cause the framework to begin a resolve operation in order to resolve the bundle. Other API can also trigger a resolver. Frameworks can resolve on a per bundle basis or they can resolve a number of bundles atomically in one operation. The bundles that trigger a resolve operation are called the trigger bundles. The trigger bundles can be defined by the following cases:

Various types of resolve operations can be initiated:

The resolve operation is not limited to the trigger bundles only, they just provide the root bundles that must be resolved. The Resolver is free to consider any present bundle to provide the required capabilities. If such bundles are in the INSTALLED state then they can also become a candidate to be resolved. The resolver is also free to use bundles that are actually not installed in the framework, for example for what-if scenarios.

Once the resolver is triggered, it must prepare the Handlers to participate in the resolve operation. A Handler is an active bundle that needs to participate in the resolve operation, there can be multiple Handlers in a framework. A Handler must register a Resolver Hook Factory service. This service is the interface between a Handler bundle, a bundle that will handle some aspects of the resolve operation, and the Resolver.

To prepare the Handlers, the Resolver must request a new Resolver Hook from each of the registered Resolver Hook Factory services with the begin(Collection) method. The parameter is the set of trigger bundles. The Handler is expected to create a new ResolverHook object for each call. If null is returned then the Handler abstains from participation. A Resolver Hook Factory must be thread-safe and allow the creation of independent Resolver Hook objects that can be active on multiple threads.

A Resolver Hook is created for a single atomic resolve operation and does not have to be thread safe. The Resolver must ensure that access to the Resolver Hook is serialized, that is, the can only be active from a single thread. The ResolverHook object is called multiple times during a resolve operation to influence the outcome of a resolve operation. The following operations are provided:

A Resolver Hook can influence the outcome of a resolve operation by removing entries from shrinkable collections. A shrinkable collection is a collection that can only shrink. The Handler can remove entries from the collection but it cannot add an entry to it. Any attempt to add to the collection must result in throwing an Unsupported Operation Exception. All collections in the Resolver Hook API are shrinkable collections.

The Resolver Hook Factory services begin(Collection) method is called in the ranking order, see Service Ranking Order. This is the same order used for calling the resulting Resolver Hooks. The Resolver Hook end() method notifies the Handler that the resolve operation has finished. The framework must not hold on to this Resolver Hook instance after the end() method has been called.

There are use cases where a bundle that is being installed should not be allowed to resolve until some activity has taken place. Sometimes certain bundles should never resolve. For example, there are byte code weaving scenarios where a bundle is used as the source but a synthetic bundle with the woven code provides the actual classes. The source bundle should then not resolve. The filterResolvable(Collection) method can be used to ensure that certain bundles are never resolved. All the given Bundle Revisions are unresolved. The Handler can look at the given collection and remove any bundles it wants to prevent being resolved in this resolve operation.

The set of bundles passed will contain the trigger bundles. If a Handler removes one of the trigger bundles the resolve of the removed bundle will not succeed and fail the call to the method that triggered the resolve operation.

The framework can pass an empty collection of resolvable bundle revisions, this could for example happen while resolving a dynamic import. An empty collection indicates that the framework will not cause any bundles to transition from INSTALLED to RESOLVED during a dynamic import package resolving.

For example, a Handler wants to ensure certain bundles are not resolved, then it can do:

public class UnresolveHandler implements ResolverHook{
    Set<BundleRevision> neverResolve = ... ;

    public void filterResolvable(
        Collection<BundleRevision> toBeResolved ) {
        toBeResolved.removeAll( neverResolve );
    }

   ... other methods
}

The filterMatches(BundleRequirement,Collection) method is used to remove capabilities for consideration for a specific requirer. The Handler receives the Bundle Requirement and the set of candidates that already match the requirement. The Handler can now remove any candidates that are not suitable. Removing the capability will prevent the requirement from getting wired to the capability. If the Bundle Requirement is declared in a fragment then the host is not knowable.

For example, a Handler wants to ensure that a set of bundles in a group are only wired to a limited set of infra-structure bundles and each other. This could be implemented as follows:

public class GroupHandler implements ResolverHook{
    Map<Bundle,Set<Bundle>> groups = ...;
    Set<Bundle> system = ... ;

    public void filterMatches( BundleRequirement r,
        Collection<BundleCapability> candidates ) {
        Set<Bundle> group = groups.get(r.getRevision().getBundle());
        if ( group == null )
            return; // not in a group

        for ( Iterator<BundleCapability> i = candidates.iterator();
            i.hasNext(); ) {
            BundleCapability candidate = i.next();
            Bundle other = candidate.getRevision().getBundle();

            if ( group.contains(other) || 
                system.contains(other) )
                continue;

            i.remove(); // not system, not in the same group
        }
    }

   ... other methods
}

Certain namespaces provide a singleton directive. For example, the osgi.wiring.bundle namespace defines that a bundle can be singleton, meaning that only one such bundle with a given symbolic name can be resolved. The purpose is to ensure that a bundle that needs exclusiveness gets this.

In certain scenarios it is necessary to limit the singleton constraint to a group of bundles instead of the whole framework. One of the primary use cases of the Resolver Hooks is to allow scoping of bundles. Some Handlers can interpret the singleton constraints as to apply to the group, not the whole framework. For this purpose, the Resolver Hook API allows the Handler to influence which bundle revision is selected for the singleton with the filterSingletonCollisions(BundleCapability,Collection) method.

The first parameter is the capability that is under consideration by the resolver, called the viewpoint capability. The resolver needs to find out what other capabilities can collide with the viewpoint. A collision takes place when multiple bundles with the same symbolic name and singleton directive set to true can potentially be resolved at the same time. For example, a Handler implements a grouping model. A singleton is therefore only valid for the bundles in this group. A Handler must therefore be able to indicate which bundles can collide. This model is asymmetric. If a group has for example outer and inner bundles, then inner bundles can collide with outer bundles but not vice versa.

The second parameters of the filterSingletonCollisions(BundleCapability,Collection) method is a set of capabilities called the candidates. The Handler can shrink this collection by removing capabilities. Removing a capability from the list of collision candidates will effectively hide the collision candidate from the target singleton bundle. This will allow the target singleton bundle to resolve regardless of the resolving state of the collision candidate.

If S is the group of infrastructure bundles (acting as an outer bundles) and a non-infrastructure group is A, then the following cases exist:

S S     collide, leave in set
A A     collide, leave in set
A !A    remove from set, not visible
A S     collide, leave in set
S A     do not collide, remove from set

The following example implements this strategy:

public class GroupHandler implements ResolverHook{
    Map<Bundle,Set<Bundle>> groups = ...;

    public void filterSingletonCollisions( BundleCapability c,
        Collection<BundleCapability> candidates ) {
        Set<Bundle> group = groups.get(c.getRevision().getBundle());

        for ( Iterator<BundleCapability> i = candidates.iterator();
            i.hasNext(); ) {
            BundleCapability candidate = i.next();
            Bundle other = candidate.getRevision().getBundle();
            Set<Bundle> otherGroup = groups.get(other);

            if ( group == otherGroup || otherGroup == null ) // Samegroup
                continue;

            i.remove(); // not system, not in the same group
        }
    }

   ... other methods
}

The framework can call this method multiple times for the same singleton capability. For example, as a first pass a framework may want to determine if a singleton bundle is resolvable first based on the presence of other already resolved singleton capabilities. Later the framework may call this method again to determine which singleton capabilities from unresolved bundles to allow to resolve.

Resolver hooks are system level components. Handlers must be careful not to create an unresolvable state which is very hard for a developer or a provisioner to diagnose. Resolver Hooks also must not be allowed to start another resolve operation, for example by starting a bundle or resolving bundles. The framework must detect this and throw an Illegal State Exception.

In cases where a Bundle Exception can be thrown, such as the Bundle start method, the Illegal State Exception must be the cause of the Bundle Exception and the Bundle Exception must be of type RESOLVE_ERROR. In cases where an exception cannot be propagated to a caller, for example during dynamic import resolving, a Framework Event of type ERROR must be published.

All hooks are treated as ordinary services, they can be used by the system bundle or other bundles.

If during the resolving anything goes wrong then the Resolver must abort the resolve operation, clean up and report an error.

If the begin(Collection) method successfully returns a ResolverHook, then the end() method must be called on that hook if it is still valid (its ResolverHookFactory is still registered) at the end of the Resolve. A ResolverHook can therefore safely allocate resources in the begin(Collection) method because it is guaranteed that it can deallocate them in the end() method.

The following are potential failures:

If the Resolver fails, it must throw a Bundle Exception to the caller if possible. Otherwise it must publish a Framework Event of type ERROR.