[platform-vcm-dev] RepositoryProviders: notes on converting natures

["Kevin McGuire" <Kevin_McGuire@xxxxxxx>]

This document describes the changes in Team core which repository providers
should be aware of for 2.0, wrt our use of persistent properties vs.
natures.

Team Core

- There's a new extension point where you can register your provider.  This
extension point is very similar to the Core nature extension point you are
using at present.

Old way using natures:

<extension point="org.eclipse.core.resources.natures"
      id="YoYoRepoNature" name="My Repo Nature">
      <runtime>
            <run class="com.yoyodyne.Provider"/>
      </runtime>
      <one-of-nature id="org.eclipse.team.repository-provider"/>
</extension>

*New way using Team Core, you would add the following.  You may want to
change the ID to not use the word 'nature', but keeping it the same is the
simplest/most direct conversion (also, if you keep them the same you can
use RepositoryProvider.convertNatureToProperty()):

<extension point="org.eclipse.team.resources.repository">
      <repository
            id="com.yoyodyne.yoyoRepoNature"
            class="com.yoyodyne.Provider">
      </repository>
</extension>

The ID for your provider can be the same as your nature ID if you want to
cheat.  You can keep the nature extension in without harm -- nobody else
will attempt to associate it with the project as a nature.  Actually, its
the provider who always associated it with the project in their "Share"
wizard page, which you will change to use the new API.

Changes in your plugin.xml

In addition to the above extension point, you will need to change the
filtering rules for your object contributions (menus), property page, etc.
The change is trivial. Anywhere where you filtered:
         <filter
               name="projectNature"
               value="com.yoyodyne.yoyoRepoNature">
         </filter>

you will change to filter as follows:
         <filter
               name="projectPersistentProperty"
               value=
"org.eclipse.team.core.repository=com.yoyodyne.yoyoRepoNature">
         </filter>

FYI, the left side "org.eclipse.team.core.repository" matches against the
key we use for the persistent property, the right side value"
com.yoyodyne.yoyoRepoNature" matches against the value of the persistent
property, in our case your provider ID used in the argument to
IRepositoryProvider.map(IProject project, String providerID), described
below.

class RepositoryProvider methods

public abstract class RepositoryProvider implements IProjectNature
   - class signature remains the same.  This ensures you can be still be a
   nature, or not a nature, as you decide.
   - we will maintain a persistent property
   (IResource.setPersistentProperty()) on the project to track the provider
   ID. This is equivalent to core remembering the nature ID on the project.
   - the provider ID is a string, just like the nature ID, and could/should
   be the same string
   - we will maintain a session property (IResource.setSessionProperty())
   on the project to remember the RepositoryProvider instance.  This is
   equivalent to core instantiating the nature and remembering it during a
   workspace session.

public static String[] getAllProviderTypeIds()
   - will return a list combining those ID's registered via our new
   extension point, and those registered via core nature (old code)

public static RepositoryProvider getProvider(IProject project)
   - will first look for a provider by persistent property/session
   property, instantiating the provider if required
   - if it can't find one that way, will fall back to old code which looks
   for a team nature

public static RepositoryProvider getProvider(IProject project, String id)
   - will first look for a provider by that id via persistent
   property/session property, instantiating the provider if required
   - if it can't find provider that way, will fall back to old code which
   looks for a nature with that id


*New* class RepositoryProvider methods

public static void map(IProject project, String id)
   - this is the new "in" way to associate your provider instance with a
   project
   - where you used to call Team.addNatureToProject() (e.g your "Share"
   wizard page) you should call this
   - It will instantiate your provider (via the extension point), set your
   ID in our persistent property, and set your provider instance in the
   session property
   - Will touch() the project to generate deltas on the IProjectDescription
   to notify that the project is being mapped.

public static void unmap(IProject project)
   - this is the new "in" way to disassociate your provider instance from a
   project
   - where you used to call Team.removeNatureFromProject() you should call
   this
   - we will clear the persistent and session properties
   - Will touch() the project to generate deltas on the IProjectDescription
   to notify that the project is being unmapped.

public static void convertNatureToProperty(IProject project, boolean
removeNature)
   - convenience method that checks if the project has a team nature, and
   if it does creates a corresponding persistent property by the same ID as
   the nature ID
   - if 'removeNature == true', also removes the nature from the project,
   indirectly updating the .project

class Team methods

public static void addNatureToProject(IProject proj, String natureId,
IProgressMonitor monitor)
   - will remain "as is" so existing callers will continue working until
   they are converted over
   - will continue to put the nature in the .project

public static void removeNatureFromProject(IProject proj, String natureID,
IProgressMonitor monitor)
   - will remain "as is" so existing callers will continue working until
   they are converted over


Things to Watch For
==============================

You should look for the following when converting:

1. References to IProjectDescription.  For example, senders of hasNature(),
getNature(), setNatureIds(), etc.

2. Senders of IProject.getDescription(), IProject.SetDescription().

3. References to any kind of MyProvider.getId() method that returns your
provider ID (you probably have one of these for convenience.  This should
correspond to #1 above.

4. Nature lifecycle:  We believe we've reproduce it with the new
RepositoryProvider API.  For example, we call configureProject() and
deconfigure() in the same cases.

5. Listening for deltas on ProjectDescriptions:   You may be listening to
these as a way of being notified when the project is shared/disconnected
(if you support the latter).  We generate them now in map()/unmap() by
touching the project.


Convenience - Conversion Menu
==============================

The following will get you a project menu to convert natures to persistent
properties.  The underlying menu, RepositoryProvider.
convertNatureToProperty(), assumes you're using the same ID for both our
new provider extension and the nature.

The action is in team.ui so you can use it just by adding this to your
plugin.xml, modulo the id's of course (this is from our cvs.ui plugin):

      <objectContribution
            objectClass="org.eclipse.core.resources.IProject"
            adaptable="true"
            id="org.eclipse.team.ccvs.ui.IProjectContributions">
         <filter
               name="projectNature"
               value="org.eclipse.team.cvs.core.cvsnature">
         </filter>
         <action
               label="%ConvertNature.label"
               tooltip="%ConvertNature.tooltip"
               class="org.eclipse.team.internal.ui.NatureToPropertyAction"
               menubarPath="team.main/projectGroup"
               id="org.eclipse.team.ccvs.ui.convertNature">
         </action>
      </objectContribution>


The action code itself is trivial, so reuse or not as you need.