<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Repository Roadmap for Logical Model Integration</title>
</head>
<body>
<table width="100%" cellpadding="2" cellspacing="5" border="0">
  <tbody>
    <tr> 
      <td bgcolor="#0080c0" valign="top" align="left"> <b><font
 face="Arial,Helvetica" color="#ffffff"> Eclipse 3.2 - Repository Roadmap for Logical Model Integration</font></b></td>
    </tr>
  </tbody>
</table>
<h1>Repository Roadmap for Logical Model Integration</h1>

<p>The <a
 href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-vcm-home/docs/online/team3.2/model-integration-proposals.html">Proposed 
  Support for Logical Model Integration</a> document outlines all the areas that
  are targeted to be addressed in 3.2 related to logical model integration support 
  in Eclipse. The purpose of this document is to describe the APIs repository providers
  can use to support logical models.
  </p>
  
<p>
To provide full support for logical models based on the Eclipse 3.2 API,
a repository provider can perform the following steps:
<ol>

	<li>Contribute the appropriate repository operations to elements
	that adapt to <a href="#ResourceMapping"><code>ResourceMapping</code></a>.</li>
	
	<li>Ensure that operations performed on resource mappings include
	all the appropriate model elements and resources by using an 
	<a href="#SyncScope"><code>ISynchronizationScope</code></a>
	and supporting API.</li>
	
	<li>Allow model providers to participate in headless merging through the 
	<a href="#AutoMerge"><code>IMergeContext</code></a>
	interface and supporting API.</li>
	
	<li>Allow model providers to participate in merge previews by using the 
	<a href="#TeamContent"><code>teamContentProviders</code></a> for the models involved in the merge.
	A <code>ModelSynchronizeParticipant</code> class is provided to help manage 
	the relationship between the model content, a merge context and the Compare
	framework.</li>
	
	<li>Provide access to the history of workspace files through the
	<a href="#FileHistory"><code>IFileHistoryProvider</code></a> API</li>
	
	<li>Provide access to remote configurations using the Eclipse
	File System API in the <em>org.eclipse.core.filesystem</em>
	plug-in and link this to workspace projects through the 
	<a href="#EFS"><code>ProjectSetCapability</code></a>
	
    <li>Support logical model element decoration by providing a workspace <code>Subscriber</code> 
    for use with the
	<a href="#Decoration"><code>SynchronizationStateTester</code></a> API.
	 
</ol>	

 <p>The following sections describe each of these points in more detail.
 A pointer to a simple <a
 href="#Example">Library example</a> is also provided.</p>


<h2><a name="ResourceMapping"></a>Contributing Actions to Resource Mappings</h2>

<h3>The Basic Resource Mapping API</h3>

<p>The resource mapping API consists of the following classes: </p>
<ul>
  <li><strong>ResourceMapping</strong>: The Class to which logical model elements 
    adapt to indicate that the model corresponds to a set of resources in the 
    workspace. The complete <code>ResourceMapping</code> class can be viewed <a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceMapping.java?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">here</a>. 
    The methods of interest are: 
    <ul>
      <li><code>Object getModelObject()</code>: The model object from which the 
        mapping was derived (or adapted).</li>
      <li><code>ResourceTraversal[] getTraversals(ResourceMappingContext, IProgressMonitor)</code>: 
        The resource traversal that cover the resources that constitute the model 
        object.</li>
    </ul>
  </li>
  <li><strong>ResourceTraversal</strong>: A <a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceTraversal.java?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup"><code>ResourceTraversal</code></a> 
    contains a set of resources and a depth flag that indicates the depth to which 
    the resources in the traversal are associated with the originating model object. 
    Resource traversals are provided to a client by a resource mapping in order 
    to describe the contents of a model in such a way that the client (e.g. a 
    repository provider) can perform its operations in as efficient a means as 
    possible. Methods of interest are: 
    <ul>
      <li><code>getResources()</code></li>
      <li><code>getDepth()</code></li>
    </ul>
  </li>
  <li><strong>ResourceMappingContext</strong>: a context that is provided to the 
    resource mapping by the client when obtaining traversals. This context allows 
    the logical model to determine what the remote state of the model is so that 
    the proper resources can be covered by the resource traversals returned by 
    the resource mapping. The use of the<code> <a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceMappingContext.java?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">ResourceMappingContext</a></code> 
    and<code> <a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/RemoteResourceMappingContext.java?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">RemoteResourceMappingContext</a></code> 
    is a bit more complicated and is described <a
 href="#ResourceMappingContext">later</a>.</li>
</ul>
<p>There are two types of plugins that should be interested in resource mappings. 
  Those who provide a model that consists of, or is persisted in, resources in 
  the workspace and those that want to perform operations on resources. 
  The former case will be covered in a document targetted at model providers and
  the later case is covered in the next section.</p>
  
<h3>Resource Mappings and Object Contributions</h3>

<p>Plug-ins that contribute extensions to adaptable extension points will have 
  to make two changes to support the new <code>ResourceMapping</code> APIs:</p>
<ol>
  <li>Update any <em>objectContributions</em> in their plugin.xml file to target
   <code>ResourceMapping</code> instead of <code>IResource</code> (for those for which this is 
    appropriate).</li>
  <li>Update their actions to work on <code>ResourceMapping</code> instead of 
    <code>IResource</code> and respect the depth constraints provided in the traversals.</li>
</ol>
<p>Plug-ins that add object contributions to <code>IResource</code> 
  can now add them to <code>ResourceMapping</code> instead, 
  if the action can apply to multiple resources. Here is an XML snippet that contributes 
  a menu action to objects that adapt to resource mappings:</p>

<pre style="background-color: rgb(204, 204, 255);">   &lt;extension<br>       point="org.eclipse.ui.popupMenus"&gt;<br>      &lt;objectContribution<br>            id="org.eclipse.team.ccvs.ui.ResourceMapperContributions"&gt;<br>         &lt;enablement&gt;<br>           &lt;adapt type="org.eclipse.core.resources.mapping.ResourceMapping"&gt;<br>              &lt;test <br>                 property="org.eclipse.core.resources.projectPersistentProperty" <br>                 args="org.eclipse.team.core.repository,org.eclipse.team.cvs.core.cvsnature" /&gt;<br>           &lt;/adapt&gt;<br>         &lt;/enablement&gt;<br>         &lt;action<br>               label="%UpdateAction.label"<br>               definitionId="org.eclipse.team.cvs.ui.update"<br>               class="org.eclipse.team.internal.ccvs.ui.actions.UpdateAction"<br>               tooltip="%UpdateAction.tooltip"<br>               menubarPath="team.main/group2"<br>               id="org.eclipse.team.cvs.ui.update"&gt;<br>         &lt;/action&gt;<br>         ...<br>      	&lt;/objectContribution&gt;<br>   &lt;/extension&gt;</pre>

<p>Contributions to <code>ResourceMapping</code> will automatically apply to objects 
  that adapt to <code>IResource</code>. This transitive association is handled 
  by the Workbench. Filtering of the contributions to resource mappings can be done using enablement
  expressions. An expression for filtering by project persistent property 
  has been added to allow repository providers to have their menus appear on projects 
  that are mapped to their repositories.</p>
  
<p>Actions that have been contributed to the <code>ResourceMapping</code> class 
  will be given a selection that contains one or more <code>ResourceMappings</code>. 
  It is the actions responsibility to translate the resource mapping into a set 
  of resources to be operated on. This can be done by calling <code>getTraversals</code> 
  to get the traversals of the mapping. Traversals are used to allow the clients 
  of the traversal to optimize their operations based on the depth of the resources 
  being traversed. A client may traverse the resource manually or may use the 
  resource and the depth as input into an operation that the action delegates 
  to do the work. As an example, if the user performs a CVS update on a java package 
  and the java package resource mapping maps to a folder of depth one, CVS would 
  issue an appropriate command ("cvs update -l" for those who are curious) which 
  would perform a shallow update on the folder the package represents.</p>
  
<p>Although it is possible to obtain a set of traversals directly from the selected
resource mappings, their are model relationships (or repository reltionships) that may
require the inclusion of additional resources or model elements in an operation. The next
section describes how to ensure that all required resources are included in an operation</p>

<h2><a name="SyncScope"></a>Operation Scope</h2>

<p>For team operations, the selected mappings need to be translated into the set 
  of mappings to be operated on. This process involves consulting all model providers 
  to ensure that they get included in operations on resources that match their 
  enablement rules. The term we use to describe the complete set of resource mappings 
  to be operated on is the operation <em>scope</em>. The following API has been 
  provided for this:</p>
<ul>
  <li><code><a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/mapping/ISynchronizationScope.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">ISynchronizationScope</a></code>: 
    Interface that defines the API for accessing the scope of the operation. It 
    provides access to all the resource mappings being operated on and the traversals 
    for those mappings as they were calculated during the scope building process.</li>
  <li><code><a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/mapping/ISynchronizationScopeManager.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">ISynchronizationScopeManager</a></code>: 
    Interface that defines the API for creating and managing a scope.</li>
  <li><code><a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/mapping/provider/SynchronizationScopeManager.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">SynchronizationScopeManager</a></code>: 
    Extendable class that provides a default implementation of the <code>ISynchronizationScopeManager</code> API.</li>
   <li><code><a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelOperation.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">ModelOperation</a></code>: 
    Extendable operation class that generates a scope using a provided scope manager and prompts if additional resources or mappings
    have been included in the operation due to model provider relationships.</li>
</ul>
<p>
The <em>initialize(IProgressMonitor)</em> method of the <code>SynchronizationScopeManager</code> class handles the entire process of converting
an input set of resource mappings into the complete set of mappings that need to be operated on as well
as the complete set of traversals that cover these mappings. A repository provider can tailor the process
by:
<ol>
<li>Providing a <code>RemoteResourceMappingContext</code> for use when obtaining resource traversals 
from resource mappings.</li>
<li>Overriding <code>SynchronizationScopeManager</code> to tailor the scope management
process as required.</li>
</ol>
<p>The next two sections describe these points in more detail.</p>

<h3><a name="ResourceMappingContext"></a>Remote Resource Mapping Context</h3>

<p>In order to guarantee that all necessary resources get included in a team operation,
the model provider may need the ability to glimpse at the state of one or more resources
in the repository. For some models, this may not be required. For instance, a java package 
  is a container visited to a depth of one, regardless of the remote state of 
  the model. Given this, a repository provider can easily determine that outgoing 
  deletions should be included when committing or that incoming additions should 
  be included when updating. However, the resources that constitute some logical 
  models may change over time. For instance, the resources that constitute a model 
  element may depend of the contents of a manifest file (or some other similar 
  mechanism). In order for the resource mapping to return the proper traversal, 
  it must access the remote contents of the manifest file (if it differs from 
  the local contents) in order to see if there are additional resources that need 
  to be included. These additional resources may not exist in the workspace but 
  the repository provider would know how to make sure they did when the selected 
  action was performed.</p>
<p>In order to support these more complex models, a <code>RemoteResourceMappingContext</code> 
  can be passed to the <code>ResourceMapping#getTraversals</code> method. When 
  a context is provided, the mapping can use it to ensure that all the necessary 
  resources are included in the traversal. If a context is not provided, the mapping 
  can assume that only the local state is of interest. </p>

<p>The remote resource mapping
  context provides three basic queries:</p>
<ul>
  <li>What type of comparison is being performed: two-way or three-way 
    <ul>
      <li>for two-way, does the local contents differ from the remote contents</li>
      <li>for three-way, are there local changes and are there remote changes</li>
    </ul>
  </li>
  <li>What are the contents of the remote (and base for three-way) counterparts 
    of the file</li>
  <li>What are the remote members of a folder</li>
</ul>
<p>The answer to the first question above depends on the type of operation that 
  is being performed. Typically, updates and merges are three-way while comparisons 
  and replace operations (at least for CVS) are two-way.</p>
<p>The Eclipse Team API includes a <code>Subscriber</code> class that defines 
  an API for providing the synchronization state between the local workspace and 
  a remote server. A <code><a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/SubscriberResourceMappingContext.java?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">SubscriberResourceMappingContext</a></code> 
  has been created that uses a <code>Subscriber</code> to access the necessary 
  remote state. Clients that have a <code>Subscriber</code> do not need to do 
  any additional work to get a resource mapping context.</p>

<h3>Subclassing SynchronizationScopeManager</h3>

<p>The <code>SynchronizationScopeManager</code> class can be subclassed to tailor the scope
generation and management process. The two main reasons for subclassing the scope manager are:
<ol>
<li>The repository provider needs to include additional resources due to some repository
level relationship (e.g. change set). This can be accomplished by overriding the 
<em>adjustInputTraversals(ResourceTraversal[])</em> method.</li>
<li>The synchronization has a longer lifecycle (e.g. Synchronize view vs. dialog) and needs the potential to react to scope
changes. The <code><a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/mapping/ISynchronizationScopeParticipant.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">ISynchronizationScopeParticipant</a></code> 
    interface defines the API that model providers can use to participate in the scope management process.
    The <code><a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/SubscriberScopeManager.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">SubscriberScopeManager</a></code>
 class is a <code>Subscriber</code> based subclass of <code>SynchronizationScopeManager</code> that involves participants in the scope management process.
 An example of why this type of process is needed is working sets. If a working set is one of the resource mappings in a scope, the set of traversals
 covered by the scope would increase if resources were added to the working set.
</ol>

<h2><a name="AutoMerge"></a>Model-based Merging</h2>

<p>The main repository operation type that requires model participation is merging. In many
cases, models only need to participate at the file level. For this, the <code>IStorageMerger</code>
API was introduced to allow model providers to contribute mergers that should be used to merge
files of a particular extension or content type. However, in some cases, models may need
additional context to participate properly in a merge. For this purpose, we introduced the
<code>IResourceMappingMerger</code> and <code>IMergeContext</code> APIs.</p>

<p>Merge operations are still triggered by actions associated with a repository
provider. However, once a merge type operation is requested by the user, the
repository provider needs to involve the model providers in the merge process to
ensure that the merge does not corrupt the model in some way.</p>

<p>There are two main pieces of repository provider API related to the model-based merging support.
<ol>
<li>API to describe the synchronization state of the resources involved in the merge.</li>
<li>API to allow model providers to merge model elements.</li>
</ol>
The following sections describe these two pieces.

<h3>API for Synchronization State Description</h3>

<p>An important aspect of model-based merging is the API used to communicate the 
  synchronization state of the resources involved to the model provider. The following 
  interfaces are used to describe the synchronization state:</p>
<ul>
  <li><a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/mapping/ISynchronizationContext.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">ISynchronzationContext</a>: 
    provides access to the synchronization state of all resources within the scope 
    of the operation. The following API pieces are used to describe the synchronization 
    state of resources. 
    <ul>
      <li><a
      href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/diff/IDiff.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">IDiff</a>:
      A generic path-based diff that consist of a diff kind (NO_CHANGE, ADD, REMOVE, CHANGE).</li>
      <li><a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/diff/ITwoWayDiff.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">ITwoWayDiff</a>:
      A diff that provides more details about a change between two states of an element (CONTENT, MOVE_TO, MOVE_FROM, COPY_FROM, REPLACE).
     <li><a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/diff/IThreeWayDiff.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">IThreeWayDiff</a>: 
      A diff that consists of either a local or remote two-way diff or both and provides a direction description for the change (INCOMING, OUTGOING, CONFLICTING) based on the presense of either or both the local and remote change.</li>
        <li><a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/mapping/IResourceDiff.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">IResourceDiff</a>:
      A two-way diff that applies to resources and provides access to the before state and after state of files through the 
      <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/history/IFileRevision.java?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">IFileRevision</a> 
        API.</li>
      <li><a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/diff/IDiffTree.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">IDiffTree</a>:
 A generic path-based data strucuture for accessing a tree of diffs.</li>
      <li><a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/mapping/IResourceDiffTree.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">IResourceDiffTree</a>: 
A resource-based data structure that contains the synchronization state for all resources 
        in the operation scope that are out-of-sync.</li>
    </ul>
  </li>
</ul>

<p>
Abstract classes are provided for all these interfaces with the convention that the class names match the 
interface names with the "I" prefix removed. The only class that repository providers must override is 
the <code>ResourceDiff</code> class so that appropriate before and after file revisions can be provided.
</p>

<h3>API for Model Merging</h3>

  <p>The <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/mapping/IMergeContext.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">IMergeContext</a>
  interface extends synchronization context with additional methods that support merging. Callback methods exist for:
    <ul>
    <li>Merging one or more diffs.</li>
    <li>Rejecting the remote changes in one or more diffs</li>
    <li>Indicating that one or more conflicts have been merged by the model</li>
    <li>Performing a group of operations while holding an appropriate scheduling rule.</li>
    </ul>
<p>An abstract 
<a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/mapping/provider/MergeContext.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">MergeContext</a>
class is provided that contains default implementations for much of the
merging behavior and also uses the 
<a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/mapping/IStorageMerger.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">IStorageMerger</a>
to perform three-way merges. 
A
<a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/SubscriberMergeContext.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">SubscriberMergeContext</a>
class is also provided which handles the population and maintenance
of the synchronization state description associated with the merge context.</p>

<p>An operation class, 
<a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelMergeOperation.java?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">ModelMergeOperation</a> 
 is provided which uses the <code>IResourceMappingMerger</code> API to perform a model-based merge operation. Subclasses need
 to overriding the <code>initializeContext(IProgressMonitor)</code> method to return a merge context.
 The operation uses this content to attempt a headless model-based merge. If conflicts exist,
 the preview of the merge is left to the subclass. As we'll see in the next section, there is a 
 <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelParticipantMergeOperation.java?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">ModelParticipantMergeOperation</a> 
 that provides preview capabilities using a
 <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelSynchronizeParticipant.java?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">ModelSynchronizeParticipant</a>.</p>


<h2><a name="TeamContent"></a>Model Content in Team Viewers</h2>

<p>Support for the display of logical models in a team operation is provided using the Common
Navigator framework which was introduced in Eclipse 3.2. Logical models can associate a 
content extension with a model provider using the <em>org.eclipse.team.ui.teamContentProvider</em>
extension point. Team providers access these content providers through the
<code>ITeamContentProviderManager</code>.</p>

<p>There are several places where a team provider may wish to display logical models:
<ul>
<li>When the scope of an operation has been expanded due to model provider relationships.
The <code>ModelOperation</code> class provides a prompt that uses the registered team content providers
to inform the user of a scope expansion.</li>
<li>When a merge preview is required. The 
<a
 href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.ui/src/org/eclipse/team/ui/synchronize/ModelSynchronizeParticipant.java?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">ModelSynchronizeParticipant</a>
 class makes use of
the team content providers and a merge context to display a merge preview. Team providers can extend this class
in several ways to tailor the preview.</li>
</ul>
<p>The <code>ModelSynchronizeParticipant</code> provides integration into the Synchronize view or any container that can display 
<code>iSynchronizePages</code>. The participant makes use of both the pre-existing synchronization participant capabilities and the 
Common Navigator capabilities to allow for team providers and models to tailor the toolbar, context menu and other aspects of the
merge preview. The <code>ModelSynchronizeParticipant</code> provides the following:
<ul>
<li>A synchronize page that defines thet link between a scope manager, merge context and team content providers.</li>
<li>Toolbar actions for displaying direction modes (Incoming, Outgoing, Both and Conflicting modes).</li>
<li>Toolbar action for cycling through models involves (i.e. Show All, Show Resources, Show Java, etc).</li>
<li>Refresh and scheduled refresh actions.</li>
<li>Action to open elements in a compare editor.</li>
<li>Change Navigation actions.</li>
<li>Standard Merge actions (Merge, Overwrite and MarkasMerged) for which models can register handlers and team providers
can provide appropriate labels (e.g. Update for CVS).</li>
</ul>

<p><img src="syncPart.png"></p>

<p>Here's a checklist of steps for tailoring a model synchronize participant for a particular Team provider:

<ul>
  <li>Define the participant using the <em>org.eclipse.team.ui.synchronizeParticipants</em> extension point.
  This will require team providers to create a sublcass of <code>ModelSynchronizeParticipant</code></li>
  <li>Define a viewer for the participant using he <em>org.eclipse.ui.navigator.viewer</em> extension point.
  The viewer definition is used to specify what menu groups appear in the context menu.</li>
  <li>Override the <em>initializeConfiguration</em> method of the participant in order to set the 
  <code>ISynchronizePageConfiguration.P_VIEWER_ID</code> to the id of the viewer specified in the previous step.</li>
  <li>Override the <em>createMergeActionGroup</em> to provide a custom subclass of <code>MergeActionGroup</code> 
  in order to tailor the appearance of the merge related actions.</li>
  <li>If the participant is persistable, override the <em>createScopeManager</em> and <em>restoreContext</em> methods to recreate
  the scope manager and merge context for the participant when it is restored on startup. </li>
  <li>Implement a subclass of <code>ModelParticipantMergeOperation</code> for handling the transition from a model-based
  merge to a preview in a dialog or Synchronize view.</li>
</ul>
<p>
An example of these types of overrides appear in the
<a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.cvs.ui/src/org/eclipse/team/internal/ccvs/ui/mappings/WorkspaceModelParticipant.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">WorkspaceModelParticipant</a>
class. The following XML snipets illustrate how this participant class is registered and how it's viewer is defined.
</p>
<pre style="background-color: rgb(204, 204, 255);">
   &lt;extension point="org.eclipse.team.ui.synchronizeParticipants"&gt;
      &lt;participant
            name="CVS"
            icon="$nl$/icons/full/eview16/cvs_persp.gif"
            class="org.eclipse.team.internal.ccvs.ui.mappings.WorkspaceModelParticipant"
            id="org.eclipse.team.cvs.ui.workspace-participant"&gt;
      &lt;/participant&gt;
   &lt;/extension&gt;
   
   &lt;extension point="org.eclipse.ui.navigator.viewer"&gt;
       &lt;viewer viewerId="org.eclipse.team.cvs.ui.workspaceSynchronization"&gt;
           &lt;popupMenu
                allowsPlatformContributions="false"
                id="org.eclipse.team.cvs.ui.workspaceSynchronizationMenu"&gt; 
             &lt;insertionPoint name="file"/&gt;
             &lt;insertionPoint name="edit" separator="true"/&gt;       
             &lt;insertionPoint name="synchronize"/&gt;
             &lt;insertionPoint name="navigate" separator="true"/&gt;
             &lt;insertionPoint name="update" separator="true"/&gt;
             &lt;insertionPoint name="commit" separator="false"/&gt;
             &lt;insertionPoint name="overrideActions" separator="true"/&gt;
             &lt;insertionPoint name="otherActions1" separator="true"/&gt;
             &lt;insertionPoint name="otherActions2" separator="true"/&gt;
             &lt;insertionPoint name="sort" separator="true"/&gt;
             &lt;insertionPoint name="additions" separator="true"/&gt;             
             &lt;insertionPoint name="properties" separator="true"/&gt;
          &lt;/popupMenu&gt;
       &lt;/viewer&gt;
   &lt;/extension&gt;
</pre>

<h2><a name="FileHistory"></a>File History</h2>
<p>A file history API has been added to allow models to access the history of files. The file history API consists of the following interfaces:</p>
<ul>
  <li><a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/filehistory/IFileHistoryProvider.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">IFileHistoryProvider</a>: 
    Obtained from a RepositoryProvider, the file history provider allows clients 
    to obtain the file history of a particular file.</li>
  <li><a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/filehistory/IFileHistory.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">IFileHistory</a>: 
    A data structure that allows access to the history of a file</li>
  <li><a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/filehistory/IFileRevision.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">IFileRevision</a>: 
    The description of a single revision or state of a file at a particular point in time in its history.</li>
</ul>
<p>Along with this API, a generic file History view has been added. This will allow Team providers to display their file/resource 
history in a shared view and also allows models to display model element history for elements tat do not map
directly to files. The History view is a page-based view which onbtains a page for the selected element in the
following way:
</p>
<ul>
<li>A history page for workspace resources is obtained by adapting the <code>RepositoryProvider</code> associated
with the project that contains thge resource to an 
<a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.ui/src/org/eclipse/team/ui/history/IHistoryPageSource.java?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">IHistoryPageSource</a>.
<li>A history page for other objects is obtained by adapting the object itself to an <code>IHistoryPageSource</code></li>
</ul>


<h2><a name="EFS"></a>Project Set Capability</h2>

<p>Methods have been added to <code>ProjectSetCapability</code> to support the translation between a reference string 
used to identify a mapping between a project and remote content and
URIs that identify a filesytem scheme regsitered with the <em>org.eclipse.core.filesystem.filesystems</em> extension point.
Team providers can optionaly provide support for this in order to allow logical models to performing 
remote browsing and project loading.</p>

<h2><a name="Decoration"></a>Decorating Model Elements</h2>

<p>Team providers can decorate model elements by converting their lightweight decorators to work for resource mappings
in the same way object contributions are converted to work for resource mappings. However, there is one aspect of
logical model element decoration that is problematic. If a model element does not have a one-to-one mapping to a 
resource, the model element may not recieve a label update when the underlying resources change.</p>

<p>To address this issue, a <code>SynchronizationStateTester</code> class was added. This class is used by model
views to determine when the labels of logical model elements need to be updated. This API relies on the <code>Subscriber</code>
interface to determine when the team state of resource has changed. To work properly, repository providers
must override the <code>RepositoryProviderType#getSubscriber()</code> method in order to return a subscriber
that provides clients access to the team state of workspace resources.

<h2><a name="Example"></a>EMF Library Example</h2>
<p>This example, available <a
 href="libraryExample.html">here</a>, is built on a model that consists of libraries, 
  books and writers.</p>
  
<h2>Change History</h2>
<p>Changes in version 3.2 M5</p>
<ul>
  <li>Document created
  </li>
</ul>
</body>
</html>