For tracing purposes, a bundle can weave a trace entry and exit message around each method. This can be done with byte code weaving by inserting a call to a service at the beginning and end of a method. In this example, a service is created that has two methods:

The strategy chosen here is simple. The weaver registers a Weaving Hook service so it receives all class loads. Any such class load is checked against a set of bundles that needs tracing, any class from a traced bundle is then woven with the trace information. If a bundle is to be traced, the set is updated and the bundle is refreshed to ensure all classes are loaded anew so the tracing code can be woven in.

public class TracingWeaver implements WeavingHook {
    final Set<Bundle> bundles = new HashSet<Bundle>();
    final List<String> imports = Arrays.asList(
        "com.acme.trace;version=\"[1,2)\""); 
    BundleContext context;

The weave method is the service method of the Weaving Hook service. It receives a WovenClass object that provides the information about the class to be woven. In this case, the bundles field contains the bundles to be woven, so this is checked first. If the to-be-loaded class is in one of the traced bundles, the byte codes are changed to provide trace information. Otherwise the no change is made.

In general, weaving code will require new imports for the to-be-woven bundle. These imports can be added by adding Dynamic Import Package clauses to the list received from the getDynamicImports() method. This is a list of String objects, the syntax of each string is equal to a clause in the DynamicImport-Package header. See Dynamic Import Package for the proper syntax.

    public void weave(WovenClass classInfo) {
        BundleWiring bw = classInfo.getBundleWiring(); 
        Bundle b = bw.getBundle(); 
        if (bundles.contains(b)) {
            byte [] woven = weaveTracing(classInfo.getBytes());
            if (!classInfo.getDynamicImports().containsAll(imports))
                classInfo.getDynamicImports().addAll(imports);
            classInfo.setBytes(woven);
        }
    }

The following trace method is called when a bundle must be traced. It ignores the request if the bundle is already traced. Otherwise, it will add the bundle to the set of traced bundles and refresh the bundle.

    public void trace(Bundle b) {
        if (bundles.add(b))
            refresh(b);
    }

The untrace method is the reverse:

    public void untrace(Bundle b) {
        if (bundles.remove(b))
            refresh(b);
    }

The refresh method uses the Bundle Wiring API to refresh a bundle. Refreshing a bundle will throw away its class loader so that all used classes are reloaded when needed.

    private void refresh(Bundle b) {
        Bundle fwb = context.getBundle(0);
        FrameworkWiring fw = fwb.adapt(FrameworkWiring.class);
        fw.refreshBundles(Arrays.asList(b));
    }

The trace method that does the final weaving is left as an exercise to the reader:

    byte[] weaveTracing(byte[] bytes) {
        ..
    }       
}

The Resolver Hook Service Specification allows bundles to be separated into various regions isolated by sharing policies. The dynamic imports added in the tracing example will need to be taken into account by the sharing policies of regions containing bundles whose classes were woven in order for the bundles to resolve. This can be accomplished using a Woven Class Listener. Using a Weaving Hook would not be appropriate since there is no guarantee that a Weaving Hook observes the final list of dynamic imports.

The region registers a Woven Class Listener service so it receives notifications of Woven Class state transitions. The sharing policy of the region containing the bundle whose class was woven is updated with the dynamic imports, if any. This action occurs while the Woven Class is in the TRANSFORMED state to ensure the region is prepared to accept the imports before the bundle wiring is updated upon entering the DEFINED state. The region is initialized with the set of bundles composing it and a static sharing policy consisting of namespaces mapped to sets of filters indicating the allowed capabilities.

public class Region implements WovenClassListener, ResolverHook {
    final Set<Bundle> bundles;
    final Map<String, Set<Filter>> policy;

The modified method is the service method of the Woven Class Listener service. It receives a Woven Class object that provides the information about the woven class that underwent a state transition. If the current state is TRANSFORMED, and the associated bundle is part of the region, the sharing policy is updated with the additional dynamic imports, if any.

    public void modified(WovenClass wovenClass) {
        if ((wovenClass.getState() & WovenClass.TRANSFORMED) == 0)
            return;
        Bundle bundle = wovenClass.getBundleWiring().getBundle();
        if (!bundles.contains(bundle))
           return;
        Set<Filter> filters = policy.get(PackageNamespace.PACKAGE_NAMESPACE);
        for (String dynamicImport : wovenClass.getDynamicImports())
            filters.add(toFilter(dynamicImport));
    }

The region also implements ResolverHook. When the filterMatches method is called, the requirement is inspected to see if its matching capabilities are allowed into the region. If not, the list of candidates is cleared.

    public void filterMatches(BundleRequirement requirement, 
            Collection<BundleCapability> candidates) {
        Bundle bundle = requirement.getRevision().getBundle();
        if (!bundles.contains(bundle))
            return;
        String namespace = requirement.getNamespace();
        if (!policy.containsKey(namespace))
            return;
        Map<String, String> directives = requirement.getDirectives();
        String filter = directives.get(
            PackageNamespace.REQUIREMENT_FILTER_DIRECTIVE);
        Set<Filter> filters = policy.get(namespace);
        if (!filters.contains(toFilter(filter)))
            candidates.clear();
    }

The toFilter method responsible for converting the requirement filters and dynamic import package clauses into a Filter is left as an exercise to the reader.

    private Filter toFilter(String s) {
        ...
    }
}

Class loads can occur at any time and Weaving Hook services must be able to handle concurrent as well as re-entrant calls to the weave method. The framework should not hold any locks when calling the Weaving Hook services, and Weaving Hook service implementations must be thread-safe. Furthermore Weaving Hook services may be re-entrant, and should be careful to avoid cycles when weaving.

For example when a class is being woven, the Weaving Hook may implicitly load a class by having a reference to it or the Weaving Hook can explicitly load a class. This new class load will also pass through the Weaving Hook service, so care must be taken to avoid infinite looping.

Weaving hooks are very low level and care must be taken by the Weaving Hook services to not disrupt normal class loading. In the case that a weaving hook throws an unexpected exception the framework must do the following:

Class loads can occur at any time, and Woven Class Listeners must be able to handle concurrent calls to the modified method. The framework should not hold any locks when calling Woven Class Listeners, and Woven Class Listener implementations must be thread-safe. Woven Class Listeners must be synchronously called by the framework when a Woven Class completes a state transition. The woven class processing will not proceed until all Woven Class Listeners are done.

Woven Class Listeners must not cause the weaving process to fail. If a Woven Class Listener throws an exception, the framework should log the exception but otherwise ignore it.

All hooks described in this specification are highly complex facilities that require great care in their implementation to maintain the Framework invariants. It is therefore important that in a secure system the permission to register these hooks is only given to privileged bundles.

In this case, the user of the hook services is the framework. Therefore, there is never a need to provide:

Implementers of these hooks must have:

In addition, a Weaving Hook must have Admin Permission with the WEAVE action to be able to use the methods on the WovenClass object that mutate the state like setBytes(byte[]), getBytes(), and the mutating methods on the list returned by getDynamicImports(). Moreover, a Weaving Hook must have Package Permission with the IMPORT action in order to add or replace dynamic imports.

The Framework must grant implied PackagePermission[somePkg, IMPORT] permissions to bundles whose classes are being woven with additional dynamic imports, assuming the weaver has a matching package import permission. The permission check for the weaver must occur during any call to the list that results in the addition or setting of a dynamic import. If the check fails, a SecurityException must be thrown. If it succeeds, the implied permission must be granted to the woven bundle immediately before defining the class.

Implementers of these listeners must have: