I know that an API is not supposed to be broken, but.... in real life this happens.
In the context of the API tooling effort, we need to handle this case when checking for binary compatibility between two Eclipse drops.
An example would be that an API provider defines an interface that can be implemented by clients with a method that takes an internal type as a parameter. This API is not usable for the clients. The provider then changes the signature of the method to use an interface type instead of the internal type. Now the API is usable, but this change technically speaking a breaking API change.
This kind of changes should be documented in the porting guide, but I believe it should also be document at the source code level.
One way to do this would be to have a javadoc tag on the corresponding API that would state this is a known breakage. Something like:
@breakage-change The parameter type has been changed to use an API type instead of an internal type
The binary compatibility checker could then realize that this is a known breakage and don't report it anymore.
The next question is: "Since this is an API breakage, should the version of the corresponding bundle change its major version?".
I'd like to get your opinions on this topic.
Thank you.
Subscribe to:
Post Comments (Atom)
2 comments:
In cases like this, it depends on the situation. If existing clients had no other choice than to implement this method (and refer to internals), it is probably best to leave the interface as is and create a new one that does not refer to internals. It might also be that there was just no way at all for clients to implement the interface, for example if the internal type was private or package-visible. In this case, you can change the interface however you want, unless clients were allowed as callers. We will always have corner cases like this. With regards to Javadoc tags, I would suggest using something more generic (@ignore...) to be able to get rid of false positives that a tool would report.
you share very nice information with us. the information that you share with us is very useful for us.
Api provider in india
Post a Comment