I hate provisional API

Eclipse, Software Engineering

Eclipse puts provisional API into internal packages. I think this is really distracting. Why? Well, provisional API should encourage early adopters to support upcoming features. Great. But what do they get from adopting an API that will be moved to some other package in a later point of time? Right, their adoption breaks and the users of their plug-ins are stuck to an older Eclipse release.

This now happened to me with the Borland StarTeam integration. The developers adopted to the ResourceMapping support introduced in Eclipse 3.1. Actually this should bring the plug-in some benefits in handling model objects that are backed by multiple resources. That’s a great idea but now I’m stuck to Eclipse 3.1 and can’t use 3.2 M5 anymore because the package name of the Resource mapping support changed and the plug-ins can’t be started anymore due to a java.lang.NoClassDefFoundError: org...internal...mapping.ResourceMapping. This reduces the intendence of the adoption to absurdity. Even a match="greaterOrEqual" won’t help in this case.

Unfortunately, the StarTeam integration is closed source. Thus, I can’t go an fix this stupid error myself. I probably have to wait till long after Eclipse 3.2 has been released to get an updated. 🙁

And at the end? Nobody will get any benifits. Users are stuck to an older technology or need to drop the Team integration completely. The adopters appologize and may consider not adopting next time. And the developer will get no feedback about his API because there won’t be any volunteers anymore. 🙁

Update 2006-08-17:

I’ve written a plug-in for Polarion’s SVNImporter. It allows you the migrate from StarTeam to Subversion. The code is available here.

16 thoughts on “I hate provisional API”

  1. The issue with the ResourceMapping support is that we had no customers step up during the 3.1 development cycle and we just didn’t have enough confidence in the API to make it real. I believe that the same thing applies to the data binding support added in 3.2 (i.e. it is a provisional API in internal packages). Certainly, the developers of the API would have prefered not to do this but it was the prudent thing to do based on the state of the API at the API freeze deadline.

    Really, the problem is that, in some cases, there is not enough time for an API to be introduced, completed and used by a reasonable number of clients within a single development cycle. In these cases, we need some way to get the work started and make clients aware of what is happening while reserving the right to make the necessary corrections if the API doesn’t meet the clients needs.

    From a client standpoint, you need to view anything in internal packages as internal, whether it is flagged as provisional API or not. This means that clients should not release products that make use of this internal code. They are free to release tech-previews that allow clients to see what is possible when the API is made real and they also have a good opportunity to influence the API by providing feedback to the API developers. However, as you have found out, if they make use of the provisional API in a product, their product is pretty much guaranteed not to be compatible with future releases of Eclipse.

    A guide to provisional APIs was published recently by the Eclipse Platform development team. It can be found at http://wiki.eclipse.org/index.php/Provisional_API_Guidelines.

  2. It is unfortunate that the StarTeam integration does not work for you any more. However, I think the behaviour you experienced shows why it was a good decision to put the (at that time) unstable API into an internal package. From the error message you got, it was very easy to see what happened and why it happened.

    Since the API was not stable at the API freeze deadline for 3.1, it was not an option to just publish it, pretending it was real. To see why this would be a bad idea, let’s consider what would have happened if the API had been released into a public package, with big warning signs that it was provisional and subject to change. Chances are that changes would have been made, only this time the changes would not necessarily be noticeable right away, and it would be much harder to diagnose the problem.

    With APIs, you don’t have a second chance. Whenever API appears in a release, we promise to maintain it in an upwards compatible way for all following point releases. To make this possible, it is important to have clear boundaries between API and internal code.

    What could Borland have done to avoid this situation? Clearly, the simplest solution is not to use internal code at all. However, there are other options I can think of: If the internal code you are using is helpful for you, but not essential, you can separate the code that relies on internals into its own plug-in or only access it through reflection to ensure graceful degradation. Another option might be to negotiate a private contract with the team that implemented the internal code. The key here is that if you know who is using your internal code and how they are using it, it is usually possible to come up with an upgrade path that does not break those known clients. Of course, this requires that both parties involved have an interest in making this work since it means additional effort on both sides.

    Oh, by the way, there is a tutorial at EclipseCon about API design 😉 http://www.eclipsecon.org/2006/Sub.do?id=151.

  3. Gunnar,

    Did you ever get comment from Borland as to when/if they’re going to fix the plugin for 3.2?

  4. Sorry, your comment was in the moderation queue, and I didn’t get notified. However, the only thing they promised was to put me onto an early-bird list so that I would get preview releases. But no response so far. Meanwhile I started an initiative in our company to migrate away from StarTeam and it looks promising. I’m already working on a migration strategy. As part of this I extended the Polarion SVN Imported to import files from StarTeam. 🙂

  5. Hi
    My team is also looking for migration from starteam to svn. I have done migration from vss to cvs earlier using a available tool.But i do not know how to accomplish this starteam to svn migration. Can you plz tell me how u did it…wat tool did u use and where do i find it?

  7. could you plz share it with me…I am not able to access it over the link you gave.

  8. You might want to try Starclipse (www.starclipse.com). It is compatible with Eclipse 3.2

  10. To migrate source code from StarTeam 2005 to SVN do we also need to install StarTeam 2005 (on machine where we will install SVNImporter) or can we just work with dump from StarTeam (without need to install StarTeam).

  14. Gunnar,

    I am trying to migrate projects from Starteam to SVN. If I try to capture the trunk only, it works. Attempting to get tags/branches, it errors out. I found a suggestion by Quinn Bailey on how to fix the “EXCEPTION CAUGHT: org.polarion.svnimporter.svnprovider.SvnException: Unknown branch” exception at this URL http://www.openmakesoftware.com/insights/svn-importer-converting-from-borland-starteam/ but am unable – even with a Polarion account – to grab the source code from Polarion even after obtaining a log-in account from them.

    Here I quote from his suggestion: OK, so the fix needs to be made on line 139 of STTransform.java:

    svnModel.addFileCopyToTag(revision.getAbsolutePath(), tagName, revision.getBranch().getName(), revision.getAbsolutePath(), oldRevno);

    Instead that line should read:

    svnModel.addFileCopyToTag(revision.getAbsolutePath(), tagName, revision.getBranch().getBranchName(), revision.getAbsolutePath(), oldRevno);

    Do you have an idea on how to obtain the source or the fixed build? Recht schoenen Dank

  16. Sergei,

    Please reach out to the Polarion folks for accessing the source code. I have no longer access. However, it’s open source so there should be a guest account for checking out the code from their SVN repository.

    Thanks!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.