| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html lang="en"> |
| <head> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <meta content="text/html; charset=ISO-8859-1" |
| http-equiv="Content-Type"> |
| <meta content="text/css" http-equiv="Content-Style-Type"> |
| <link type="text/css" charset="ISO-8859-1" href="../book.css" |
| rel="STYLESHEET"> |
| <title>Repository resource management</title> |
| <link href="../book.css" type="text/css" rel="stylesheet"> |
| </head> |
| <body style="background-color: rgb(255, 255, 255);"> |
| <h2>Repository resource management</h2> |
| <p>Once you have created a <b><a |
| href="../reference/api/org/eclipse/team/core/RepositoryProvider.html">RepositoryProvider</a></b>, |
| there are other resource management mechanism that should be understood:<br> |
| </p> |
| <ul> |
| <li>In order to allow other plug-ins to indicate special handling for |
| their projects |
| and files the team plug-in defines extension points that other |
| providers and other plug-ins can use to register <a href="#filetypes">file |
| types</a> and to |
| declare files that should be <a href="#ignored">ignored </a>by a |
| repository provider.</li> |
| <li>Team providers can also register a class that can be used to |
| persist |
| a <a href="#projectsets">set a projects</a> so that references to the |
| project can be shared across |
| a team, with the actual contents coming from the repository.</li> |
| <li>Repository providers should consider how they will handle <a |
| href="#linked">linked resources</a>.<br> |
| </li> |
| <li>Finally, team providers can mark resources that should be hidden |
| from the user as <a href="#teamprivate">team private</a>.<br> |
| </li> |
| </ul> |
| <h3><a name="ignored"></a>Ignored files</h3> |
| <p>In several cases, it may be unnecessary to keep certain files under |
| repository control. For example, resources that are derived from |
| existing |
| resources can often be omitted from the repository. For example, |
| compiled |
| source files, (such as Java ".class" files), can be omitted since |
| their corresponding source (".java") file is in the repository. |
| It also may be inappropriate to version control metadata files that are |
| generated by repository providers. The <a |
| href="../reference/extension-points/org_eclipse_team_core_ignore.html"><b>org.eclipse.team.core.ignore</b></a> |
| extension point allows providers to declare file types that should be |
| ignored |
| for repository provider operations. For example, the CVS client |
| declares |
| the following:</p> |
| <pre><extension point="org.eclipse.team.core.ignore"><br> <ignore pattern = ".#*" selected = "true"/><br></extension></pre> |
| <p>The markup simply declares a file name <b>pattern</b> that should |
| be ignored |
| and a <b>selected</b> attribute which declares the default selection |
| value of |
| the file type in the preferences dialog. It is ultimately up to |
| the user |
| to decide which files should be ignored. The user may select, |
| deselect, |
| add or delete file types from the default list of ignored files.</p> |
| <p><img src="images/ignore.png" alt="" border="0"></p> |
| <h3><a name="filetypes"></a>File Types<br> |
| </h3> |
| <p>Some repositories implement different handling for text vs. binary |
| files. The <a |
| href="../reference/extension-points/org_eclipse_team_core_fileTypes.html"><b>org.eclipse.team.core.fileTypes</b></a> |
| extension allows plug-ins to declare file types as text or binary |
| files. |
| For example, the Java tooling declares the following: |
| </p> |
| <pre><extension point="org.eclipse.team.core.fileTypes"><br> <fileTypes extension="java" type="text"/><br><br> <fileTypes extension="classpath" type="text"/><br> <fileTypes extension="properties" type="text"/><br> <fileTypes extension="class" type="binary"/><br><br> <fileTypes extension="jar" type="binary"/><br> <fileTypes extension="zip" type="binary"/><br></extension></pre> |
| <p>The markup lets plug-ins define a file type by <b>extension</b> and |
| assign a <b>type</b> |
| of text or binary. As with ignored files, it is ultimately up to |
| the user |
| to manage the list of text and binary file types. |
| </p> |
| <p><img src="images/filetypes.png" alt="" border="0"> |
| </p> |
| <h3><a name="linked"></a>Team and linked resources</h3> |
| <p>A project may contain resources that are not located within the |
| project's directory in the local file system. These resources are |
| referred to as <a href="resInt_linked.htm">linked resources</a>. </p> |
| <h4>Consequences for Repository Providers</h4> |
| <p>Linked resources can pose particular challenges for repository |
| providers which operate directly against the file system. This is a |
| consequence of the fact that linked resources by design do not exist in |
| the immediate project directory tree in the file system. </p> |
| <p>Providers which exhibit the following characteristics may be |
| affected by linked resources:</p> |
| <ol> |
| <li>Those which call out to an external program that then operates |
| directly against the file system.</li> |
| <li>Those which are implemented in terms of IResource but assume that |
| all the files/folders in a project exist as direct descendents of that |
| single rooted directory tree.</li> |
| </ol> |
| <p>In the first case, lets assume the user picks a linked resource and |
| tries to perform a provider operation on it. Since the provider calls a |
| command line client, we can assume that the provider does something |
| equivalent to first calling <a |
| href="../reference/api/org/eclipse/core/resources/IResource.html"><b>IResource</b></a>.getLocation().toOSString(), |
| feeding the resulting file system location as an argument to the |
| command line program. If the resource in question is a linked resource, |
| this will yield a file/folder outside of the project directory tree. |
| Not all command line clients may expect and be able to handle this |
| case. In short, if your provider ever gets the file system location of |
| a resource, it will likely require extra work to handle linked |
| resources. </p> |
| <p>The second case is quite similar in that there is an implicit |
| assumption that the structure of the project resources is 1:1 with that |
| of the file system files/folders. In general, a provider could be in |
| trouble if they mix IResource and java.io.File operations. For example, |
| for links, the parent of <a |
| href="../reference/api/org/eclipse/core/resources/IFile.html"><b>IFile</b></a> |
| is not the same as the java.io.File's parent and code which assumes |
| these to be the same will fail. |
| </p> |
| <h4>Backwards Compatibility</h4> |
| <p>It was important that the introduction of linked resources did not inadvertently |
| break existing providers. Specifically, the concern was for providers that reasonably |
| assumed that the local file system structure mirrored the project structure. |
| Consequently, by default linked resources can not be added to projects that |
| are mapped to such a provider. Additionally, projects that contain linked resources |
| can not by default be shared with that provider.</p> |
| <h4>Strategies for Handling Linked Resources</h4> |
| <p>In order to be "link friendly", a provider should allow projects |
| with linked resources to be version controlled, but can disallow the |
| version controlling of linked resources themselves. </p> |
| <p>A considerably more complex solution would be to allow the |
| versioning of the actual linked resources, but this should be |
| discouraged since it brings with it complex scenarios (e.g. the file |
| may already be version controlled under a different project tree by |
| another provider). Our recommendation therefore is to support version |
| controlled projects which contain non-version controlled linked |
| resources.</p> |
| <h4>Technical Details for Being "Link Friendly"</h4> |
| <p>Repository provider implementations can be upgraded to support |
| linked resources by overriding the <b><a |
| href="../reference/api/org/eclipse/team/core/RepositoryProvider.html">RepositoryProvider</a>.canHandleLinkedResources()</b> |
| method to return <strong>true</strong>. Once this is done, linked |
| resources will be allowed to exist in projects shared with that |
| repository provider. However, the repository provider must take steps |
| to ensure that linked resources are handled properly. As mentioned |
| above, it is strongly suggested that repository providers ignore all |
| linked resources. This means that linked resources (and their children) |
| should be excluded from the actions supported by the repository |
| provider. Furthermore, the repository provider should use the default |
| move and delete behavior for linked resources if the repository |
| provider implementation overrides the default <a |
| href="../reference/api/org/eclipse/core/resources/team/IMoveDeleteHook.html"><b>IMoveDeleteHook</b></a>.</p> |
| <p>Team providers can use <a |
| href="../reference/api/org/eclipse/core/resources/IResource.html"><b>IResource</b></a>.<b>isLinked() |
| </b>to determine if a resource is a link. However, this method only |
| returns true for the root of a link. The following code segment can be |
| used to determine if a resource is the child of a link.</p> |
| <pre>String linkedParentName = resource.getProjectRelativePath().segment(0);<br>IFolder linkedParent = resource.getProject().getFolder(linkedParentName);<br>boolean isLinked = linkedParent.isLinked();</pre> |
| <p>Repository providers should ignore any resource for which the above |
| code evaluates to <strong>true</strong>.</p> |
| <h3><a name="teamprivate"></a>Team private resources</h3> |
| <p>It is common for repository implementations to use extra files and |
| folders to |
| store information specific about the repository implementation. |
| Although |
| these files may be needed in the workspace, they are of no interest to |
| other |
| plug-ins or to the end user.</p> |
| <p>Team providers may use <a |
| href="../reference/api/org/eclipse/core/resources/IResource.html"><b>IResource</b></a>.<b>setTeamPrivateMember(boolean) |
| </b>to indicate that a resource is private to the implementation of a |
| team |
| provider. Newly created resources are not private members by default, |
| so this |
| method must be used to explicitly mark the resource as team |
| private. A |
| common use is to mark a subfolder of the project as team private when |
| the |
| project is configured for team and the subfolder is created.</p> |
| <p>Other resource API that enumerates resources (such as resource delta |
| trees) |
| will exclude team private members unless explicitly requested to |
| include |
| them. This means that most clients will not "see" the team |
| private resources and they will not be shown to the user. The |
| resource |
| navigator does not show team private members by default, but users can |
| indicate |
| via Preferences that they would like to see team private resources.</p> |
| <p>Attempts to mark projects or the workspace root as team private will |
| be |
| ignored.</p> |
| <h3><a name="projectsets"></a>Project sets</h3> |
| <p>Since the resources inside a project under version control are kept |
| in the |
| repository, it is possible to share projects with team members by |
| sharing a |
| reference to the repository specific information needed to reconstruct |
| a project |
| in the workspace. This is done using a special type of file |
| export for <b>team |
| project sets</b>. </p> |
| <p><img border="0" alt="" |
| src="images/projectset.png"></p> |
| <p> </p> |
| <p>In 3.0, API was added to <a |
| href="../reference/api/org/eclipse/team/core/ProjectSetCapability.html">ProjectSetCapability</a> |
| to allow repository providers to declare a class that implements |
| project saving for projects under their control. When the user |
| chooses to export project sets, only the projects configured with |
| repositories that define project sets are shown as candidates for |
| export. This API replaces the old project set serialization API (see |
| below). </p> |
| <p>The project set capability class for a repository provider is obtained from |
| the <a |
| href="../reference/api/org/eclipse/team/core/RepositoryProviderType.html">RepositoryProviderType</a> |
| class which is registered in the same extension as the repository provider. |
| For example:</p> |
| <pre><extension point="org.eclipse.team.core.repository"><br> <repository<br> typeClass="org.eclipse.team.internal.ccvs.core.CVSTeamProviderType"<br><br> class="org.eclipse.team.internal.ccvs.core.CVSTeamProvider"<br> id="org.eclipse.team.cvs.core.cvsnature"><br> </repository><br></extension></pre> |
| <p>Prior to 3.0, The <a |
| href="../reference/extension-points/org_eclipse_team_core_projectSets.html"><b>org.eclipse.team.core.projectSets</b></a> |
| extension point allowed repository providers to declare a class that |
| implements project saving for projects under their control. When |
| the user chooses to export project sets, only the projects configured |
| with repositories that define project sets are shown as candidates for |
| export.</p> |
| <p>For example, the CVS client declares the following:</p> |
| <pre><extension point="org.eclipse.team.core.projectSets"><br> <projectSets id="org.eclipse.team.cvs.core.cvsnature" class="org.eclipse.team.internal.ccvs.ui.CVSProjectSetSerializer"/><br></extension></pre> |
| <p>The specified class must implement <a |
| href="../reference/api/org/eclipse/team/core/IProjectSetSerializer.html"><b>IProjectSetSerializer</b></a>. |
| Use of this interface is still supported in 3.0 but has been deprecated.</p> |
| |
| </body> |
| </html> |
