platform-team/team3.0/team_api.html

<title>Team API</title>
<table border="0" cellspacing="5" cellpadding="2" width="100%">
  
    <tr> 
      
    <td align="left" valign="top" bgcolor="#0080c0"> <b><font color="#ffffff" face="Arial,Helvetica"> 
      Eclipse 3.0 - Team API Plan Item</font></b> </td>
    </tr>
</table>
<h1>Team API</h1>
<p>This document outlines the state of the Eclipse Platform <strong>Improve Team 
  API </strong> 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 <a
 href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=37705">bug report</a> for 
  this plan item. </p>
<p class=MsoNormal>This is the plan item:</p>
<blockquote> 
  <p>"<em>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]</em>"</p>
  <p>Last Modified: October 2nd, 2003</p>
</blockquote>
<h2>Motivation</h2>
<p>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. </p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h2>Our plan</h2>
<p>Our proposed improvements to the Team provider integration include the following 
  high-level work items in the Eclipse 3.0 timeframe:</p>
<ol>
  <li>Harmonize<a href="team_provider.htl"></a> versioning and non-versioning 
    repository integration points. This mainly affects the Target Management plugins.<br>
    <em>Timeline: Breaking changes will be identified for M5, and work will be 
    prototyped in a branch.<br>
    </em></li>
  <li>Promote the support of a Team API by repository vendors.<br>
    <em>Timeline: WVCM plugin will be available with hooks for integration. Plus 
    a reference implementation started in a branch for M5. This will help provide 
    feedback to the JSR process.<br>
    </em></li>
  <li>Improved <a href="synchronizing_solution.html">Synchronize view</a> with 
    simplified integration API.<br>
    <em>Timeline: very functional in M4 with final documentation and API to be 
    complete for M5.<br>
    </em></li>
  <li>Support <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=36957">concurrent 
    execution</a> of operations.<br>
    <em>Timeline: support available in M4. See the referenced document.</em></li>
</ol>
<p>The rest of this document focuses on points 1 and 2.</p>
<h2>Investigating a Team API</h2>
<p>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 <em><strong>the</strong></em> 
  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 <em><strong>another</strong></em> option.</p>
<h3>JSR 147</h3>
<p>The <a href="http://www.jcp.org/en/jsr/detail?id=147">JSR-147</a> 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.</p>
<p>To make WVCM integration into Eclipse a success, we must do the following:</p>
<ol>
  <li>Integrate the WVCM API into Eclipse so it can be used by repository vendors.</li>
  <li>Provide one or more reference implementations for WVCM in order to prove 
    the API.</li>
  <li>Encourage repository vendors to implement the API by providing generic UI 
    on top of the WVCM API (repository/site explorer, version history browser) 
    that vendors can easily integrate with by implementing the API.</li>
</ol>
<h2>WVCM API</h2>
<p>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.</p>
<p>The WVCM plugin will be available to providers through the <em>org.eclipse.team.wvcm</em> 
  plugin.This plugin will provide access to both the WVCM API and the Team API 
  for obtaining a WVCM providers from a repository provider.</p>
<p>The Eclipse specific components of the Team API will include a means of converting 
  a RepositoryProvider into a WVCM Provider and vica versa.</p>
<blockquote> 
  <pre>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
	}

}</pre>
</blockquote>
<p>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, <em>null</em> will 
  be returned.</p>
<p>A repository vender associates a VCM provider with a repository provider by 
  contributing to the <em>org.eclispe.team.wvcm.provider</em> extension point.</p>
<blockquote>
  <pre>&lt;extension point=&quot;org.eclipse.team.wvcm.provider&quot;&gt;
  	&lt;provider
		id=&quot;org.eclipse.team.cvs.core.cvsRepositoryProvider&quot;
		class=&quot;org.eclipse.team.internal.ccvs.core.CVSWVCMProvider&quot;&gt;
	&lt;/provider&gt;
&lt;/extension&gt;</pre>
</blockquote>
<p>The <em>id</em> 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 <em>org.eclipse.team.core.repository</em> extension 
  point).</p>
<p>For a description of the WVCM API itself, see <a href="http://www.jcp.org/en/jsr/detail?id=147">JSR-147</a>. 
  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.</p>
<h2>WVCM Based UI</h2>
<p>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.</p>
<p>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:</p>
<ul>
  <li>Synchronize view</li>
  <li>Repository Explorer</li>
  <li>Resource History View</li>
</ul>
<p>We have already built a <a href="synchronizing_solution.html">Sychronize view</a> 
  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.</p>
<p>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.</p>
</BODY>
</html>