This kind of reasoning is often caused by not seeing the extremely tight 
relation between the provider of an API and that API itself. There is virtually 
no backward compatibility for providers, if the API changes, you need a new 
provider. Separating the provider from its API therefore just creates a lot of 
work and potential error cases that provide no benefit whatsoever.

The best practice I learned over time is therefore is that a provider includes 
an exact copy of the API package that it is build against and both exports AND 
imports it. Since OSGi packages have a globally unique name + version this 
works, the framework will share one of the exported packages if possible. This 
model has a number of advantages:

1) The resolver can automatically drag in implementations based on the API
2) You have significantly fewer bundles to worry about
3) You always have the right version at hand
4) bnd supports this model very well with its package include from class path 
function and calculation of importing exports.

Every time I run into bundles that do not include their API I get this 
desperate sinking feeling :-(

The idea that it works better with multiple providers of the same API is 
nonsense since they both MUST use the identical versions of the overlapping 
packages. That is, there is no backward compatibility to speak of for 
providers. So substitutable imports work fine for this use case.

The only argument for separating API and implementation in two bundles is that 
you do not have to refresh the client if you update an implementation. True, 
but due to transitive dependencies it takes real hard work to actually achieve 
this unless you have a small trivial system. And an OSGi system that can handle 
the going down of any bundle is likely not very valuable since it will likely 
fail. So realistically, this argument sounds nice in theory but has very little 
value in practice.

Interestingly, this discussion was held early on and several times thereafter. 
Initially, I was not sure, the separate API bundle did not sound so bad. Now, 
15 years later I am quite convinced that the provider including the API is the 
best solution in most cases.

Kind regards,

        Peter Kriens

> On 20 mei 2015, at 17:37, Milen Dyankov <> wrote:
> Well I agree in general. My only point is that IMHO the one defining the
> API should also be the one providing it at runtime. Since OSGi alliance is
> defining a spec which describes a service API it should be the one
> providing the API bundle. Vendors are still free to provide their own
> implementations and extensions anyway they wish. But this way a random
> consumer does not have to investigate if given vendor has included the API
> in the implementation and if not then worry about which bundles need to be
> installed at runtime to satisfy imports. I personally (as probably most
> people on this list) can deal with it. And from that perspective it's easy
> (and partly true) to say it's not rally a problem. However it doesn't look
> nice and it does not help to fight the "too complex" and "too messy"
> stereotypes.
> Just my 2 cents!
> Best,
> Milen
> On Wed, May 20, 2015 at 3:55 PM, Richard S. Hall <>
> wrote:
>> On 5/20/15 05:15 , Milen Dyankov wrote:
>>> Thanks for your answer Richard!
>>> I am aware if the FAQ however what it basically tells you is "it depends"
>>> ;)
>> Unfortunately, it does depend on your circumstances. There are very few
>> cases in software engineering where you can say, "always do it like
>> this"...that's the way the cookie crumbles.
>> Thus I was hoping for some more insides so I can better understand the
>>> intentions and the situation with service APIs from OSGi specs as of
>>> today.
>>> So, if I understand your answer correctly the conclusions are:
>>> - Never use compendium bundle at runtime because it is not a proper bundle
>>> (whatever that means).
>> Bundles (i.e., modules) are supposed to be cohesive and loosely coupled.
>> The compendium is just a bunch of APIs thrown into a JAR file, so that
>> hardly is cohesive and certainly wouldn't lead to low coupling. Understand?
>>   I agree with you that this should be in FAQ at
>>> least. It would be even better if there is some more official statement
>>> (may be there is and I just couldn't find it) that also explains why!
>>> - There are no proper/official separate API bundles for the service APIs
>>> defined in the specs. Vendors are free to choose if they (1) package the
>>> API in the implementation bundle, (2) provide the implementation only or
>>> (3) provide separate bundles for API and implementation. Felix has chosen
>>> the first approach to avoid maintaining too many bundles.
>> No choice has been made at Apache Felix, but generally people have
>> gravitated to that approach. Subprojects are free to do it any way they
>> want, because use cases vary.
>>   IMHO
>>> and according to the FAQ it seems the third approach makes more sense:
>>> "*This
>>> situation would be different if the service API were package in a separate
>>> bundle. In this situation, all consumer bundles would be wired to the API
>>> bundle, not to the provider bundle. Thus, if the provider were updated or
>>> uninstalled and then refreshed, the consumer bundles would only be
>>> minimally impacted (i.e., they would either switch to the new version of
>>> the provider or to a different provider).*"  but I respect your decisions.
>> It does make a lot of sense in many cases. If you are unsure of your
>> needs, I'd recommend this as the default approach.
>>> - There is no issue with split packages
>>> <>  because regardless of the
>>> provider and the way APIs they are packaged/exported the API package(s)
>>> *should* always be both complete and limited to what what OSGi alliance
>>> has
>>> specified. IMHO this should be a bit more strict than just expecting
>>> vendors to "do it right". Then perhaps consumers can feel a bit more safe
>>> from such issues when choosing an implementation (without the need to
>>> examine it's internals). But I'm not going to argue about it.
>> There is not much that can be done about this. What do you want the OSGi
>> Alliance to do? We could require that ever developer give a signed list of
>> every class that should be in every package and store that in some central
>> repository. Then any time a bundle says they export a particular class, the
>> framework could go out to that authority get the list of classes for that
>> package and scan the bundle to make sure it contains the proper classes. Of
>> course, this wouldn't even guarantee anything, since the bundle could
>> include bogus implementation classes. Nor could you make it better by
>> including class signatures in this central repository, because that would
>> eliminate substitutability of different provider implementations.
>> At some point, you just have to trust the bundle developers and if they
>> end up lying, the you put that bundle developer on your blacklist and you
>> exclude them in your future choices.
>> As with everything, you're not going to get something (worthwhile) for
>> free.
>> -> richard
>>> Once again thanks for your answers. Please correct me if
>>> I misunderstood something.
>>> Regards,
>>> Milen
>>> On Sun, May 17, 2015 at 8:01 PM, Richard S. Hall<>
>>> wrote:
>>> On 5/17/15 12:57 , Milen Dyankov wrote:
>>>> Hi,
>>>>> I recently stumbled upon something that makes me wonder about OSGI specs
>>>>> APIs. As Metatype was the one API that made me start thinking about the
>>>>> issue, I'll use it as an example but the question is about APIs in
>>>>> general.
>>>>> So while attempting to replace Felix's Metatype with Equinox one,  I
>>>>> realized Felix implementation jar provides also the API while Equinox
>>>>> does
>>>>> not. So my first thought was that there should be another jar with the
>>>>> API
>>>>> alone but I couldn't find one. Second thought was to install
>>>>> osgi.cmpn.jar
>>>>> (it's  a bundle after all) but I was told I should never do that and
>>>>> that
>>>>> those jars are provided to be only used as compile time dependencies.
>>>>> So here comes the question - who should provide the APIs at runtime for
>>>>> a
>>>>> OSGI specs?
>>>>> See the FAQ:
>>>>  I would actually split the question into a few:
>>>>> - is it really forbidden/nor recommended to use osgi.cmpn.jar at
>>>>> runtime?
>>>>> If so can someone please elaborate?
>>>>> This should probably be in the FAQ too. The compendium only happens to
>>>> be
>>>> packaged as a bundle because that is how it is built, not because it
>>>> actually is a proper bundle. It is not cohesive, since it is just a
>>>> collection of API, and pulls in unnecessary dependencies. The OSGi
>>>> Alliance
>>>> should probably quit publishing it as a bundle. Over the years, we seen
>>>> lots of users run into difficulties when using it as a bundle.
>>>>  - shouldn't there be independent  (perhaps released by OSGI alliance)
>>>> API
>>>>> bundles? If there should be but they are missing at the moment then why
>>>>> Felix does not provide APIs in a separate bundles instead of packaging
>>>>> them
>>>>> with the implementation?
>>>>> It's not really the purpose of the OSGi Alliance, but I suppose they
>>>> could. At Apache Felix, we have enough bundles to maintain, without
>>>> creating more.
>>>>  - finally if the expectation is that each implementation provides also
>>>> the
>>>>> API isn't this leading to split package condition? I'm aware for most
>>>>> specs
>>>>> it probably makes no sense to have 2 different implementations at the
>>>>> same
>>>>> time but still ...
>>>>> No. How would they be split? Packages are self contained in OSGi
>>>> bundles
>>>> unless you explicitly make them split. If done properly, there is little
>>>> harm in having multiple providers of a package. However, having a single
>>>> provider does provide some benefits too. As the FAQ says, it just depends
>>>> on your situation.
>>>> If you really are dealing with composing a system out of third-party
>>>> bundles, though, you cannot really always have it your way so you have to
>>>> deal with the realities on the ground.
>>>> -> richard
>>>> I would appreciate if someone can throw more light on the subject.
>>>>> Regards,
>>>>> Milen
>>>>> ---------------------------------------------------------------------
>>>> To unsubscribe,
>>>> For additional commands,
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail:
>> For additional commands, e-mail:
> -- 

To unsubscribe, e-mail:
For additional commands, e-mail:

Reply via email to