search

eclipse-archived / smarthome

Eclipse SmartHome™ project
https://www.eclipse.org/smarthome/
Eclipse Public License 2.0
861 stars 784 forks source link

Distinguish @ProviderType and @ConsumerType interfaces #4736

Open sjsf opened 6 years ago

sjsf commented 6 years ago

We had several discussions lately about how to compatibly evolve our APIs. Especially with Interfaces it makes a huge difference whether they are implemented by the users of the framework or by the framework itself when it comes to deciding what a "breaking" change is and where we allow/accept null as arguments or return types. [EDIT: rather not the null argument distinction - that's a different story; see my comment below]

OSGi R6 therefore introduced nice little @ProviderType and @ConsumerType annotations for exactly this purpose. Tooling like bnd makes use of them, but even without that it IMHO would make sense to at least use them for documentary purposes. They come as a standalone JAR and neither have nor introduce any dependencies to OSGi R6 (apart from them being defined there themselves). The annotations have a "CLASS" retention policy, i.e. they will be available at runtime but the JVM is perfectly fine if it cannot resolve them - similarly as the DS annotations.

I therefore suggest to make use of them here.

Signed-off-by: Simon Kaufmann simon.kfm@googlemail.com

maggu2810 commented 6 years ago

Especially with Interfaces it makes a huge difference whether they are implemented by the users of the framework or by the framework itself

So, are there interfaces that must only be implemented by the framework? Aren't the most interfaces that are implemented by the framework allowed to be implement by products, too? Or are the annotations to be interpret as "for pure bindings" allowed?

sjsf commented 6 years ago

Or are the annotations to be interpret as "for pure bindings" allowed?

No, they are not. From this point of view it doesn't make any difference if it is a binding or a solution which implement it. It might though make a difference in the decision whether it is "acceptable" to do a breaking change at all.

Thing, SafeCaller and ItemRegistry would be good examples for @ProviderType interfaces, I reckon. ThingHander and ItemProvider both are @ConsumerType interfaces.

sjsf commented 6 years ago

As I just had a lunch-discussion with @kaikreuzer about this topic I'd like to add to the previous comment: The @ProviderType and @ConsumerType annotations are only meant to denote what kind of changes are considered to be "breaking" and what are "compatible".

The question about which rules apply regarding to accepting/returning null and/or empty lists turned out to be rather orthogonal. It differs also which area of API is involved, e.g. frequently implemented interfaces like bindings vs. provider implementations with in fact are rather close to the core framework. In contrast to my initial comment it doesn't make sense to overload the semantical meaning of these two annotations with it.