| Eclipse 3.0 - Team API Plan Item |
This document outlines the state of the Eclipse Platform Improve Team API plan item. Interested parties should review this document and verify that their use cases are reflected in the requirements then later that the solution provided satisfies their needs. Feedback is strongly encouraged and may be provided on the platform-vcm-dev mailing list or in the bug report for this plan item.
This is the plan item:
"Improve team API. Since Eclipse 2.0, each team repository provider adds its own specialized commands to the Eclipse UI. There are no common APIs for a plug-in tool to programmatically interact with different team providers. JSR- 147 is in the process of developing common API for creating and manipulating sets of version-controlled files and web resources, based on the DeltaV extension to WebDAV. Eclipse should support this experimental API. [Platform Team]"
Last Modified: October 2nd, 2003
There is a long history of Team APIs in Eclipse :) In the early days of Eclipse we thought that an API was the foundation on which the Eclipse Team support should be built and spent quite a while trying to realize this. That was Eclipse 1.0.
As a result of the 1.0 API, several repositories, including CVS, were forced to bend and contort to implement the API. And what ended up happening was that each repository wasn't able to fully expose their functionality within Eclipse. We had an API, but the repository integration within Eclipse was weak.
As part of the 2.0 release we shifted our priority from an API and concentrated instead on providing repositories the mechanisms for rich integration into the workbench (file system hooks, decoration, menu contributions, project association). Our goal was to ensure that any repository provider could integrate and easily show-off their cool features within the workbench. Based on the number of providers that have integrated with Eclipse in such a short period and the small number of questions we feel that we have succeeded.
In Eclipse 3.0 we want to improve and fix the problems with the existing integration mechanisms. Furthermore we would like to deliver on our promise to have an API for the Synchronize View and kick start work on support for a generic abstraction layer for Team providers.
Our proposed improvements to the Team provider integration include the following high-level work items in the Eclipse 3.0 timeframe:
The rest of this document focuses on points 1 and 2.
Since Eclipse 1.0, our position on a general Team API has been that we don't want to be the ones inventing or imposing an API because we know from experience that we shouldn't be in that business. On the other hand, we acknowledge that it would be a great benefit to some 3rd party tools to have generic access to repository provider functionality. Hence, unlike in 1.0, the motivation for providing a Team API is no longer based entirely on our desire to build the generic Team UI but instead to complement the current Team support (very rich integration story for providers) with an API story that can support these 3rd party tools. We have learned our lesson and know that an API should never be the only option for providers to integrate into Eclipse, but that doesn't mean that it can't become another option.
The JSR-147 is a repository vendor approved API that is close to what we we need for providing generic access to repository functionality. This JSR, titled Workspace Versioning and Configuration Management (WVCM), has been crafted by several vendors but does not yet have a reference implementation. This represents a great opportunity to advance the state of repository provider/tool integration.
To make WVCM integration into Eclipse a success, we must do the following:
The WVCM API work will be done in a separate plugin. The reason for this is two-fold. For one, we do not want to require repository providers to implement this API and making it a separate feature will allow those providers to deliver a product without the WVCM feature. Second, and more importantly, we do not want to tie the release cycle of the WVCM API to that of the Eclipse Platform SDK. This will allow any modifications required by repository providers to be released on a schedule that is appropriate for the provider.
The WVCM plugin will be available to providers through the org.eclipse.team.wvcm plugin.This plugin will provide access to both the WVCM API and the Team API for obtaining a WVCM providers from a repository provider.
The Eclipse specific components of the Team API will include a means of converting a RepositoryProvider into a WVCM Provider and vica versa.
public class WVCM {
public static javax.wvcm.Provider getProvider(RepositoryProvider provider) throws WvcmException {
// return associated WVCM provider if registered
}
public static RepositoryProvider getProvider(javax.wvcm.Provider provider) throws TeamException {
// return Eclipse Team provider for a specified WVCM provider
}
}
In either of the above cases, it is possible that the corresponding provider does not exist. For instance, it is not a requirement that a repository provider implement a corresponding WVCM provider. In these cases, null will be returned.
A repository vender associates a VCM provider with a repository provider by contributing to the org.eclispe.team.wvcm.provider extension point.
<extension point="org.eclipse.team.wvcm.provider"> <provider id="org.eclipse.team.cvs.core.cvsRepositoryProvider" class="org.eclipse.team.internal.ccvs.core.CVSWVCMProvider"> </provider> </extension>
The id of a WVCM provider is the same as the identifier for the corresponding repository provider (as defined in the extension for registering the subclass of RepositoryProvider with the org.eclipse.team.core.repository extension point).
For a description of the WVCM API itself, see JSR-147. At the current time, this specification is rather vague. This is partially because it is attempting to define a general API on top of heterogeneous repository systems but also because it currently lacks a reference implementation to add concrete examples. As part of the integration of WVCM into Eclipse, we are proposing to implement a WVCM provider for CVS (and possibly also for WebDAV and FTP, time permitting) to prove (and if necessary improve) the WVCM API.
The wide spread adaptation of a standard Team API is hindered due to a catch-22 situation between the repository vendors and 3rd party tool implementers. Without 3rd party tools that add benefit for the repository vendors there is little motivation to implement a general API. But without specific implementations of a standard API, there is no possibility (let alone motivation) to implement 3rd party tools that make use of the standard API.
To circumvent this situation, we are proposing to implement several UI pieces in Eclipse on top of the WVCM API. These tools will include one or more of the following:
We have already built a Sychronize view that repository providers re-use by implementing a small set of classes. One possibility is to provide an implementation of these class on top of WVCM so that any providers who implement WVCM can plug into the sync view for free. We also are considering providing a Repository Explorer and Resource History view similar to those provided by the Eclipse CVS plugin that uses the WVCM API.
One things we learned during the development of Eclipse 1.0 is that general views such as those proposed often hide the distinguishing features of a particular repository. However, what we are proposing is to provide these views for those providers that want fast and easy integration into Eclipse. We will still provide the the means for repository providers to obtain more rich integration. It may even be possible to support the surfacing distinguishing features within the generic views. This is something we will be aiming for whenever possible.