on Sep 16th, 2008Eclipse API Tools Article
API is a pain in the ass… either crafting API or just maintaining it. Just ask any Eclipse committer who has:
- broken API by introducing a subtle change to a class
- forgotten to rev version numbers when adding new API
- accidentally revved version numbers when not adding new API
- maintained IWorkbenchPart3, ITextViewerExtension7, IContext2… etc…
- tried to argue that API isn’t binding in the state of Texas
To help with this problem, PDE introduced API Tooling as part of the Ganymede release. Not too many people outside the Eclipse Platform team know about these tools so I have written an article that introduces the wonderful PDE API Tooling to everyone! Hopefully this will kick-start your adventure in using API Tools and making it easier to maintain API and versioning information.
Also, if the wonderful (and handsome!) Eclipse Summit Europe program committee decides to accept my talk on API Tooling, you can hear about it in person at one of my favorite European Eclipse conferences!
The versioning support looks very cool, guess I will take a closer look …
@Heiko, yap… that’s one of the best features of API Tools as keep tracking of when you should rev versions is difficult… especially when you want your versions to mean something in regards to API compatibility
Ooopps…
API Tooling
@Simon, thanks… don’t you love it when “tooling” tries to be so smart
Great article Chris, thanks !
One remark is that if I’m not wrong Eclipse SDK is required to use API Tools. You should mention it in the article as the SDK is not installed by default in 3.4
2 stupid questions though:
1- What exactly means “internal.provisional” packages ?
2- What’s the point of using @noextend annotation for a class instead of declaring it “final” ? To give the API developer some room to still extend it in the future, but not the consumer ?
Neat!
@Frederic,
What do you mean that the SDK is not installed by default? If you download ‘Eclipse Classic’ it is. All of the projects part of the Eclipse Classic (SDK) distribution are using API Tools.
In response to your questions:
1) internal.provisional basically means that the classes in these packages are still internal but most likely will end up as API in a future release. It’s a way of committers getting more feedback before things are made into a permanent API.
2) Yap, that’s one of the reasons. Also, if you mark something final, you don’t leave consumers ANY room to do something. Consumers can still break the rules if they want to, but they are at least warned.