SPI description

Problem

The things we make available as APIs are "cast in stone". We can't change them; we have to live with them for a long, long time. So it is a good idea to show as little as possible in APIs. However, sometimes we are faced with a situation when some pieces, while of no interest to majority of users, would be beneficial to a small group of consumers.

Moreover, often such special functionality would reveal too much of implementation details thus locking us into the current implementation. One solution is usage of "x-friends" attribute in OSGi manifest, but it requires explicit list of consumers.

So, how do we make some additional functionality available to those special customers without locking is into the current implementation?

Proposed Solution

Well, there is no magic wand. But there is a compromise: we provide those extra pieces, but we reserve the right to change them - sometimes.

Just like "Application Programming Interfaces" (API) we'll have "Service Provider Interfaces" (SPI). The difference would be that SPIs can be modified or removed when minor version of the bundle changes (for instance, 3.3 to 3.4). Such breaking changes should only be considered as a last resort but they are allowed.

Consumers of SPIs would be expected to specify smaller version range in the dependencies (for instance, [3.3, 3.4) as opposing to [3.3, 4.0) ). It would be a good idea for SPI consumers to "register" with SPI providers so that they can be contacted before changes in SPI take place. I think that list of e-mails of users can be added to Javadocs of the SPIs. (If there are too many users to list - consider making it an API.)

The SPI classes / interfaces / methods will have "@spi" tag added to Javadocs. The text of the "@spi" tag might specify a way to register with SPI provider.

SPI classes and interfaces need to be specified in OSGi manifests just like API classes and interfaces. Same rules for backward compatibility will apply with the exception that backward compatibility can be broken when minor version is incremented. SPI classes and interfaces can be placed in a package having ".spi" in the name to underscore the differences.

To recap this in a short form:

SPIs are like APIs but for a small subset of customers, probably exposing implementation details

Marked by "@spi" tag in Javadoc

Can be broken in a minor release

Consumers are advised to register with suppliers to be notified on upcoming changes