OSGi Services are great. They can solve many problems very elegantly. Take for instance SPI patterns. SPI patterns are used to make implementations pluggable. This type of pattern outside OSGi often comes with a bunch of external configuration (e.g. in META-INF/services) that makes it hard to manage and gives you a once-off chance to choose your implementation that you're stuck with for the rest of the VM lifecycle. OSGi Services provide a much more elegant way to solve this.
In many cases clients simply want to use some functionality and don't particularly care how that functionality was created. When using OSGi Services the functionality is looked up in the OSGi Service Registry which is a directory of these. Services can be looked up by implemented interface (like a phone book) or by provided attribute (like the yellow pages). How the service got there is not interesting to the client and he's not involved in that. What if the service gets replaced while the client is active? No problem, the OSGi Service Programming model is actually built around this dynamicity. You don't need to stop service consumers when you are replacing or updating the service, they are automatically rebound.The Service Registry also provides us with an attribute based selection mechanism which is very nice if there are multiple implementations to choose from. As an example, take a system where every available printer is represented in the Service Registry as a Service that implements the org.acme.Printer interface. Each printer will have additional properties registered that help with the selection:
When looking for a Printer OSGi allows you to use an LDAP-style filter to select the printer you want. So if you want a printer that can do A3 you would use this LDAP filter:
(&(objectClass=org.acme.Printer)(paper-size=A3))
or if you want a printer in a location that starts with 'b' you do this:
(&(objectClass=org.acme.Printer)(location=b*))
This is all great and you can build your system on this using either plain OSGi code or component frameworks such as OSGi Blueprint or OSGi Declarative Services. However sometimes you may want to tweak the properties at a later date without having to rewrite your system. Assume that in your organisation all of a sudden the office numbering has changed, which would really mean that you'd have to update the 'location' attribute of all the printers. Or maybe you want to add some additional metadata to existing printers that influence the selection process, like their energy rating.
Service Registry Hooks provide the building blocks that make this possible. I wrote a little bundle called ServiceJockey that uses these to manipulate service registrations and how they are looked up. BTW you can find details at the end of this posting about getting ServiceJockey, which is open source and available freely under the Apache License.
Service Registry Hooks: what are they?
Altering Service Registrations
Altering Client Side Lookups
Is it overkill?
Service Jockey - ride your service interactions
Service Registry Hooks: what are they?
One of the driving factors for Service Registry Hooks (an OSGi standard introduced in the 4.2 Core specification) was the Remote Services (Distributed OSGi) work done in the OSGi Alliance. One of the things that implementations of the Remote Service spec need to know is what kind of services consumers are looking for so that they can go out to a discovery system to see if it might be available remotely. Eagerly registering all available remote services is clearly not scalable so we need a smarter mechanism to allow for transparent on demand discovery of remote services. This is what the ListenerHook and FindHook provide us. Together they allow us to find out what service consumers are requesting making us to only look in a remote Discovery system for those that are relevant to the current framework.
Another problem was frequently brought up. What if you have an existing bundle that doesn't know anything about Remote Services? What is the default behaviour? Should all service lookups all of a sudden always include remote services? The Remote Services spec does include a special property that you can add to your filter to influence this (service.imported) but you clearly don't want to break up all your existing service consumers to add this extra property to their lookup filters.
It turned out that there wasn't really a valid answer to that question applicable to all cases. If you're working on a system only using Remote Services for a select set of services it may make sense to default all other services consumers to not use Remote Services. On the other hand, maybe if you're building a Cloud-based infrastructure where services can move freely from one container to another the default behaviour could be that you do allow remote services for just about anything.
Since there isn't really a one-size fits-all here the Service Registry Hooks make it possible to provide a policy for this problem in a separate bundle. You can create EventHooks and FindHooks to influence what services consumers can see. This effectively allows you to add extra conditions to the lookup of service consumers without the need to modify those consumers.
Finally, EventHooks and FindHooks, together with the a ServiceListener, allow you to proxy Service Registrations, where you provide a second registration of the same object with modified properties, hiding the original.
The ability to provide an alternate registration on the fly and the possibility to impose extra conditions on existing service consumer lookups is what I built ServiceJockey around.
ServiceJockey doesn't replace the Service Object, it only effectively replaces the registration in the Service Registry plus it can put additional constraints on client lookups. But you could go further. If you wanted to actually replace or shadow the real service object and do some work when somebody uses it (maybe log it or something) you could put an additional object between the consumer and the original service object.
Because the Service Registry Hooks effectively modify some basic behaviour of the framework (the visibility of Services) they should really be started early in the Framework lifecycle. You can achieve that by giving them a low start level.
The Service Registry Hooks are available in Felix 1.8.0 and Equinox 3.5 and newer versions of these.
Altering Service Registrations
Let's start with a bundle that consumes (uses) a Printer. It isn't interested in which printer, as long as it can print A4:
BundleContext context = ... // from Activator.start()
Filter filter = context.createFilter(
"(&(objectClass=org.acme.Printer)(paper-size=A4))");
st = new ServiceTracker(context, filter, null) {
public Object addingService(ServiceReference ref) {
// print out some information on the printer
// or use the printer
return super.addingService(ref);
}
};
st.open();
When I run this it's reporting both printers that I have in my system:
Printer:
objectClass: [org.acme.Printer]
service.id: 27
name: p1
location: b283
capabilities: [Double-sided]
paper-size: [A3, A4]
Printer:
objectClass: [org.acme.Printer]
service.id: 28
name: p7
location: a12
capabilities: [Colour, Staple]
paper-size: [A4, Letter]
So the client has arbitrary access to both of them. Now lets see if you can modify the client behaviour so that it only uses a printer with an Energy Rating < 50.
But hold on, we don't even know about energy ratings yet! We need to add this information to the Printer registration without changing the bundle(s) that register the Printers. Let's user Service Jockey to do this.
Service Jockey uses the OSGi Extender Model. This means that it is driven from a data file in a bundle.
So I've got a bundle (called PrinterJockey) that contains META-INF/sj.xml:
<service-jockey xmlns="http://www.coderthoughts.org/schemas/sj/v1.0.0">
<proxy-registration>
<rule>
<service-filter>(&(objectClass=org.acme.Printer)(name=p1))</service-filter>
<add-property key="energy-rating">75</add-property>
</rule>
<rule>
<service-filter>(&(objectClass=org.acme.Printer)(name=p7))</service-filter>
<add-property key="energy-rating">50</add-property>
</rule>
</proxy-registration>
</service-jockey>
I will have to tell the Service-Jockey that my bundle contains configuration for it, for that I'm adding a header to the Manifest:
Service-Jockey: META-INF/sj.xml
Lets run the Printer Consumer bundle together with Service Jockey and my 'Printer Jockey' configuration bundle that contains the sj.xml file:
id State Level Bundle
0 ACTIVE 0 org.eclipse.osgi_3.5.1.R35x_v20090827
1 ACTIVE 1 org.coderthoughts.servicejockey_0.0.1
2 ACTIVE 1 PrinterJockey_1.0.0
3 ACTIVE 10 Printers_1.0.0
In my case the Printers bundle both registers and consumes the Printers, but that's because its a little test bundle. It's not really relevant. Note that the Printers bundle has a higher start level than the Jockey ones and therefore starts later.
When I run my system again I can see that it's doing some work. Now my client reports these services:
Printer:
objectClass: [org.acme.Printer]
service.id: 30
name: p1
location: b283
capabilities: [Double-sided]
paper-size: [A3, A4]
energy-rating: 75
.ServiceJockey: Proxied
Printer:
objectClass: [org.acme.Printer]
service.id: 32
name: p7
location: a12
capabilities: [Colour, Staple]
paper-size: [A4, Letter]
energy-rating: 50
.ServiceJockey: Proxied
Aha! I've got my energy rating in there! That's good. Remember that these are alternative registrations. The original ones haven't changed, they're just hidden.
Altering Client Side Lookups
Now I want my client to only use the one that is rated <= 50.
That's done by adding another rule to the Service Jockey configuration. A rule that adds an extra filter to any matching lookup in a consumer.
<service-jockey xmlns="http://www.coderthoughts.org/schemas/sj/v1.0.0">
<restrict-visibility>
<rule>
<bsn>.*</bsn>
<service-filter>(objectClass=org.acme.Printer)</service-filter>
<add-filter>(energy-rating<=50)</add-filter>
</rule>
</restrict-visibility>
<proxy-registration>
...
</proxy-registration>
</service-jockey>
You can specify a regular expression to say what the Bundle Symbolic Name of the consumer bundle(s) is that the rule applies to. In my case .* matches anything. So it applies to any bundle that has OSGi Service consumers. By the way, there's also a
You specify to what services the additional filter applies with the tag and you specify the additional filter in
Note that the Service Filter applies to any service returned to a service consumer, regardless of the filter used by the client itself looks like.
Let's run the client again:
Printer:
objectClass: [org.acme.Printer]
service.id: 32
name: p7
capabilities: [Colour, Staple]
location: a12
paper-size: [A4, Letter]
energy-rating: 50
.ServiceJockey: Proxied
Bingo - it only selects the service I wanted it to select. Based on additional properties and criteria listed in my Service Jockey configuration file. I did not have to modify the Printer Service registration bundle or the Consumer bundle...
Is it overkill?
Seems like a lot of work for just adding a service property, is there not a lighter way to at least add values to Service Registrations? Well at least that was my initial impression. However looking at the ServiceJockey bundle, it's only 14kb. Besides that there is currently no other way to achieve this...
Service Jockey - ride your service interactions
I didn't show any of the code to actually use the EventHook and the FindHook. Have a look at the HidingEventHook and HidingFindHook source code for that.
You can check out the source (Apache License) as an Eclipse Project from SVN here. If you fancy modifying the code, I would recommend you also get the tests project and add new ones. The test bundle depend on the Mockito bundle for its mock objects...
You can check out the source (Apache License) as an Eclipse Project from SVN here. If you fancy modifying the code, I would recommend you also get the tests project and add new ones. The test bundle depend on the Mockito bundle for its mock objects...
I'm sure the Service Jockey isn't perfect, because I only wrote it during an airplane flight so feel free to send patches :)
I also put a binary download of ServiceJockey here.
Also in the source tree, Eclipse projects for the Printers and PrinterJockey example bundles.
1 comment:
As google code has stopped providing source code repositories, the code for this blog article can now be found here: https://github.com/bosschaert/service-jockey
Post a Comment