The basic framework provides complete visibility for any bundle to any other bundle. In certain use cases it can be important to provide the impression to application bundles that they are part of a limited group of bundles. Bundle Hook services allow Handlers to hide bundles from other bundles by filtering the Bundle Events and return values of methods that return bundles.

Though Bundle Hooks can effectively control bundle visibility of other bundles by filtering some of the key Bundle Context methods as well as event delivery, it does not provide proper isolation. Bundles that use other API will be able to see bundles even if they are hidden by the Bundle Hooks.

The Bundle hooks provide a basic mechanism to hide bundles from each other as well as control bundle collisions. The Bundle Event Hook allows a Handler to hide Bundle Events from bundles, the Bundle Find Hook allows a Handler to alter the result of framework methods that return bundles. The Collision Hook is used for providing a policy when bundles collide. A collision takes place when there is an attempt to install or update a bundle and the situation arises that there are two bundles with the same bundle symbolic name and version.

A Find Hook or an Event Hook can influence the outcome of a number of operations that retrieve a bundle or show a bundle related event by removing entries from shrinkable collections. A shrinkable collection is a collection that can only remove entries, not add to it. Any attempt to add to the collection must result in throwing an Unsupported Operation Exception. All collections in the Find Hook and Event Hook API are shrinkable collections.

The framework must call the hooks in a privileged block, see Privileged Callbacks. Hooks are always called in service ranking order, Service Ranking Order.

Handlers must ensure that Client bundles continue to see a consistent set of Bundle Events that strictly follow the transitions defined by the OSGi specifications because Bundle events can be used in a state machine that depends on these transitions. Such state machines can get confused if some Bundle Events are missed.

For example, if a Bundle Tracker sees a STARTED event but the corresponding STOPPED event is removed for that Client then the tracker will still assume the associated bundle is active.

A simple solution is to stop the Client bundle when the Handler decides to start filtering the Bundle Events. The Client bundle should then be started after the filter is in place. This model ensures that the Handler can assume the Client has no knowledge of any hidden bundles.

However, when the bundle that implements the bundle event hook is stopped, it will of course no longer be able to filter events and the target bundle might see bundle events for bundles it was not aware of.

As a best practice a Handler should not hide a Bundle from itself. That is, its own events should always be received and if it gets the bundles from the framework its own Bundle object should be included.

A Handler must register a bundle Event Hook service to intercept and filter events before they are delivered to bundles. The framework must call the event(BundleEvent,Collection) method on all registered hooks in service ranking order to filter the events before they are delivered to any of the registered bundle listeners. The Handler can remove any BundleContext objects from the given shrinkable collection it wants shield from the event's Bundle.

The event method must be called once for each Bundle Event, this includes Bundle Events that are generated when there are no Bundle Listeners registered.

The event(BundleEvent,Collection) method must be called on the same thread that is performing the action which generated the specified event. The shrinkable collection includes BundleContext objects with all Bundle Listeners registered with them.

A Bundle Event Hook must receive all Bundle Events:

The purpose of the Bundle Find Hook, is to limit the visibility of bundles to selected Client bundles. The Find Hook service is called with the find(BundleContext,Collection) method on all Handler Hook services in service ranking order when a Client bundle tries to get bundles from the framework. A registered Find Hook service gets a chance to inspect the candidate set of bundles and can remove any bundle that must be hidden from the receiver.

The Bundle Find Hook can filter the result of the following methods:

The Find Hook is not called for:

The Bundle Find Hook is also used during an install operation when the to be installed bundle is already installed at a given location. Normally, the install the returns the Bundle object of the existing bundle but this can cause confusion for the installer when this bundle is hidden by the Find Hook. Therefore, the REJECTED_BY_HOOK Bundle Exception is thrown when the find(BundleContext,Collection) method determines that the Bundle Context has no visibility of the conflicting bundle.

Two bundles collide when they have the same bundle symbolic name and version, although there location must always be different. The org.osgi.framework.bsnversion launching property (see Launching Properties ) defines the policy when a collision is about to take place during install or update operations. The launching property can have the following values:

There are two types of operation that can create a new bundle revision: Install and Update. During this creation the framework has to consider its bsnversion policy as defined by the launching property. For each creation, there are a number of candidates to collide with. In single mode, any candidate that exists will fail the creation. In multiple mode, any number of candidates are allowed. In managed mode, no candidates are allowed, like the single mode, but the Collision Hook services can prune the list of candidates before the framework makes the decision. If the Collision Hook services have emptied the list of candidates then the installation will succeed, if any bundle remains in this list then the operation fails. In managed mode, creations are treated as in single mode but bundles must assume as if the system operates in multiple mode.

The purpose of the Collision Hook is to delegate the decision of bundle collisions to a management agent. For example, using this and other hooks a management agent can create regions of bundles that have limited visibility of each other. Since these bundles do not have visibility of all other bundles a global collision does not necessarily translate into a collision inside a region. Using the Collision Hook the management agent can allow these collisions globally but restrict their impact locally.

In managed mode the framework must call all registered Collision Hook services for each bundle install and update operation. The calling order of the hooks is defined by ranking order, see Service Ranking Order. The Collision Hook service is only called in managed mode and there exists one or more candidates during the creation phase of an install/update operation.

The CollisionHook interface has a single method:

The filterCollisions(int,Bundle,Collection) method takes a type of operation value that must be one of the following two values that indicate the operation that caused the Collision Hook to be called:

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: