A bundle that needs to hide service references from other bundles, or wants to be informed about the service events another bundle sees, can register a Find and Event Listener hook by registering a Find Hook service and an Event Listener Hook service with the framework. If a service event is generated, it will pass this event to the hook. The Event Listener Hook method can then inspect the arguments and optionally remove bundles from the event delivery list.

When a bundle uses the Bundle Context getServiceReference or getServiceReferences method, the Find Hook is notified with the list of discovered services. The hook can then remove any service references it wants to hide for the target bundle.

A bundle that wants to be aware of the services bundles are waiting for to be registered can register a Listener Hook. The framework will notify such hooks of all existing listeners as well as any changes in this list. The interceptor can use the filter information registered with the listener to detect the services that are being listened for.

In an OSGi system, all communication is normally tunneled through services. This makes it a very interesting place for a handler to intercept the service communications. These handlers can provide facilities like proxying, extra security, authentication, and other functions completely transparent to the parties that interact through services.

Proxying an existing service for a specific bundle requires the following steps:

Registering a proxy service X' is trivial with the OSGi API, there are no special requirements on the service. As long as it implements the listed interfaces and provides the same attributes then it can pose as service X.

Hiding service X can be implemented with a combination of the Event Listener Hook and the Find Hook. The Event Listener Hook can be used to hide any service events from the target bundle and the Find Hook can be used to remove X from the delivered results of the getServiceReference(s) methods.

In the following figure the difference between a normal service interaction and a proxied interaction is depicted. In the normal case, Bundle A directly uses Service X, in the proxying case, the Proxy Bundle hides the original and provides an alternative.

Figure 55.3 Normal and proxied service interaction

However, there is one complication with the service hiding: what is the observing state of the target bundle when proxying begins? The Event Listener Hook must be registered to act as a filter on the service events. Just after this registration it can not determine what events have been seen by the target bundle. If it has already checked out X, the hook has no possibility to make the target bundle unget the service. A solution is to transiently stop the target bundle before the hook is registered and then transiently started it again, if the bundle is active. It is usually not advised to start/stop other bundles but this seems to be the only reliable solution. The problem can be alleviated when the start level is used to start the proxying handler bundle before the target bundles, in that case the target bundle is not started when the proxy is created. Though this optimizes the normal case, stopping the target bundle remains necessary because any of the bundles can be updated or stopped at any moment in time.

The following example shows how to hide a specific Service Reference from a specific bundle.

public class Hide implementsEventListenerHook, FindHook {
    final Bundle           bundle;
    final ServiceReference reference;
    final BundleContext    context;
    ServiceRegistration    reg;

    Hide(BundleContext context, 
        ServiceReference reference, 
        Bundle bundle) {
        this.context = context;
        this.bundle = bundle;
        this.reference = reference;
    }

    void open() {
        boolean active = 
            bundle.getBundleState() == Bundle.ACTIVE;
        if ( active )
            bundle.stop(Bundle.STOP_TRANSIENTLY);
        reg = context.registerService(
            new String[] {
                FindHook.class.getName(),
                EventListenerHook.class.getName() }, this, null);
        if ( active )
            bundle.start(Bundle.START_TRANSIENTLY);
    }

    public void close() { reg.unregister();}

The Hide class registers a Event Listener Hook and Find Hook service in the open method. Once registered, these services will receive their event callbacks. In the find hook, the target Service Reference is removed from the results if the bundle that called the getServiceReference(s) method is the target bundle.

    public void find(BundleContext ctx, 
        String name, String filter,
        boolean allServices, Collection refs) {
        if (ctx.getBundle() == bundle) {
            refs.remove(reference);
        }
    }

The event method is the opposite of the find method. In this method, the target bundle is removed from the event destinations if the related Service Reference is the target Service Reference.

    public void event(ServiceEvent event, 
        Collection bundles) {
        if (event.getServiceReference().equals(
            reference)) 
            bundles.remove(bundle);
    }
}

Once the Hide class is working, a proxy can be registered. For example:

void startProxy(ServiceReference ref,Bundlefor,
        Object proxy ) {
    Hide hide = new Hide(ctx, ref, for);
    hide.open();
    ServiceRegistration reg = ctx.registerService(
        (String[]) ref.getProperty("objectClass"),
        proxy,
        makeProperties(ref)  // copy the properties
    );
}
...

The Listener Hook provides information about services that bundles are listening for. This makes it possible to look outside the OSGi framework to see if a listened for service could be provided in another way. For example, this service could come from Jini, SLP, or through some other means.

A Listener Hook receives events every time a bundle adds or removes a Service Listener. The Listener Hook is called with an added and removed method that take a collection of ListenerInfo objects. These objects provide the identity of the bundle that added a Service Listener and the optional filter string. The Listener Hook can use this filter string to look for specific properties, for example the objectClass property to determine the type that is being sought. Extracting the property from this filter string is non-trivial though regular expressions can in general be used to extract the needed information.

The following class uses an unexplained Track object to do the low level details. The example only shows how the Listener Hook can interact with these track objects.

public class OnDemand implements ListenerHook{
    final BundleContext context;
    final Map           tracked = HashMap();
    ServiceRegistration reg;

The constructor saves the Bundle Context. The registration is done in an open method.

    public OnDemand(BundleContext context) {
        this.context = context; }
    public void open() {
        reg = context.registerService(
            ListenerHook.class.getName(), this, null); }

The Listener Hook has added and removed methods that take collections. It is easier to handle the concurrency per object.

    public void added(Collection listeners) {
        for (Iterator i=listeners.iterator(); i.hasNext();) {
            add((ListenerHook.ListenerInfo) i.next());
    } }
    public void removed(Collection listeners) {
        for (Iterator i=listeners.iterator(); i.hasNext();) {
            remove((ListenerHook.ListenerInfo) i.next());
    } }

In the add hook, a ListenerInfo object provides the information about the Service Listener. In this example, a Track object is created for each active listener and associated with the given info object. This requires proper synchronization and should handle the rare case that the events are delivered out of order. The ListenerInfo object contains an isRemoved method that provides this information. If it is true, the corresponding removed event has already been called or will be called very soon. In that case, it is safe to discard the added event. For proper cleanup, the reg field is tested to see if it is set, if not, this call is during closing and should be ignored.

    synchronized void add(ListenerHook.ListenerInfoinfo) {
        if ( reg == null || info.isRemoved() )
            return;

        Track t = new Track(info);
        tracked.put(info, t);
        t.open();
    }

To remove a Track object it is necessary to consult the tracked map. If the track object is in the map, it must be closed. If not, there is an out of order delivery and this event can be ignored, the add method will ignore the corresponding ListenerInfo object because the isRemoved flag will be set. For proper closing, the reg field is tested for null.

    synchronized void remove(ListenerHook.ListenerInfoinfo){
        if ( reg == null )
            return;
        Track t = tracked.remove(info);
        if ( t != null ) 
            t.close();
    }

The close method is straightforward. The hook services are unregistered and all the remaining Track objects are closed. The reg field is used to make sure the event methods are ignoring any outstanding calls by setting it to null. After the synchronized block, any incoming event is ignored.

    public void close() {
        reg.unregister();
        synchronized(this) { reg = null; }
        for ( Track t : tracked.values() ) { t.close(); }
        tracked.clear();    }  }

Service Listeners may be registered with the system bundle's BundleContext. If at least one Service Listener is registered with the system bundle's BundleContext then the system bundle's BundleContext must be contained in the keys of the shrinkable map passed to the event(ServiceEvent,Map) method. Just like other BundleContext keys contained in the shrinkable map, the system bundle's BundleContext may be removed. If the system bundle's BundleContext is removed by a service Event Listener Hook then the BundleContext will not be contained in the map for the remaining service Event Listener Hooks called. Unlike other BundleContext objects, if the system bundle's BundleContext is removed from the shrinkable map then the service event is still delivered to the Service Listeners added to the system bundle's BundleContext.

When one of the getServiceReference or getServiceReferences methods is called using the system bundle's BundleContext then the service Find Hooks are called in the same way the hooks are called when a normal BundleContext is used. The system bundle's BundleContext along with the shrinkable candidate service references collection is passed to the find(BundleContext,String,String,boolean,Collection) method. Service Find Hooks may remove service references from the shrinkable collection. If a service reference is removed by a service Find Hook then the service reference will not be contained in the collection for the remaining service find hooks called. Unlike other BundleContext objects, if the system bundle's BundleContext is used to find services then the Framework ignores the service reference removals performed by the service Find Hooks and allows the service references removed to remain visible in the find results.

A key concept in the Listener Hook is the filter. When a bundle is interested in a specific set of services, it registers a service listener with a filter. This filter is an indication of what services are interesting to the target bundle. The objectclass property holds the names of the interfaces and classes. However, just searching for this property with a regular expression is not guaranteed to return a usable value. The form of the sub-expressions can make the property part of an and or even negate. For example, looking for the objectclass in the following expression gives a result that is the opposite of what is searched.

(!(objectclass=org.osgi.service.cm.ConfigurationAdmin))

However, understanding a full filter expression is quite difficult. An acceptable strategy is to look for the object classes in the filter string with a regular expression but evaluate the filter against any conclusions that are being drawn. That is, testing a Configuration Admin service against the filter in the previous example will not match.

Realistically, many scenarios that are enabled by the Listener Hook will require the filters to have a simple structure.

The Event Listener Hook and Find Hook both allow the interceptor to remove elements from a collection and not add elements. The reason is that adding almost inevitably violates framework invariants that can trip the receivers. These invariants are very important to keep the programming model for the bundle developers simple.

All service hooks are treated as ordinary services. If the framework uses them, their Service References will show that the system bundle is using them, and if a hook is a Service Factory, then the actual instance will be properly created.

The only special treatment of the service hooks is that the framework must not use them for the hooks themselves. That is, the Event and Find Hooks can not be used to hide the services from the framework.

The hooks are very sensitive to ordering because they modify the basic behavior of the OSGi Framework. Before a hook is registered, a client bundle interacts with the framework directly. However, ordering in an OSGi Framework can never be relied upon from an programmer's perspective. It is bad practice to rely on start level ordering in a program because updates and other disturbances will inevitably break this ordering. Start level ordering is a tool for deployers to smoothen initialization problems, not to handle ordering dependencies.

Implementers of the hooks must therefore be intricately aware that they can be started before or after their target bundles are started.

Many scenarios for the hooks specified here could be simplified by being able to intercept the getService call of the target bundle. This design was investigated and rejected because it created a dependency graph (registering bundle, proxying bundle, and target bundle) that could not be properly managed in a dynamic OSGi system. For example, if a proxying bundle provides an alternative implementation for a service, how does the receiving bundle know that it should stop using this service? It has no knowledge that the proxying bundle even exists. Instead of creating a much more complex service registry, it was decided to keep the model simple and reuse the existing primitives. This puts the complexity at implementing the hooks, but leaves the overall service model simple.

All hooks in this specification must be thread safe because the hooks can be called any time. All hook methods must be re-entrant, the framework can enter them at any time, and in rare cases in the wrong order. Most methods will be called synchronously with framework activities. It is fully allowed to call the framework from any of the hook methods. However, even more than usual, it is highly recommended to not hold any locks while calling the framework.