Ressources liées

Dans les explications antérieures sur les ressources et le système de fichiers (Mappage de ressources vers des emplacements de disque), toutes les ressources d'un projet devaient se trouver au même endroit dans le système. Ce cas de figure se vérifie généralement. Cependant, le concept de ressources liées dans le plan de travail permet que les fichiers et dossiers d'un projet soient stockés dans le système de fichiers, mais à un autre endroit que le projet. 

Les ressources liées doivent posséder un projet comme ressource parent. Elles peuvent se trouver n'importe où dans le système de fichiers. Leur emplacement peut être différent de celui du projet, voire correspondre à un autre projet. Seules quelques restrictions s'appliquent aux emplacements de ressources liées. La méthode IWorkspace.validateLinkLocation peut être employée afin de vérifier qu'un emplacement est valide pour créer une ressource liée.

Des ressources liées sont créées à l'aide de la méthode IFolder.createLink ou IFile.createLink. Pour savoir via un programme si une ressource donnée est liée, recourez à la méthode IResource.isLinked. Vous remarquez que cette méthode renvoie uniquement la valeur true pour les ressources liées, et non pour leurs enfants.

A part ces méthodes particulières pour créer des ressources liées et savoir si une ressource est liée, vous pouvez employer des API standard de l'espace de travail. Le plus souvent, les ressources liées fonctionnent exactement comme toute autre ressource dans l'espace de travail. Cependant, certaines restrictions s'appliquent lorsque vous les déplacer, copier ou supprimer. Reportez-vous à IResource et ses sous-classes pour en savoir plus sur chaque opération et ses limites.

Variables de chemin

La variables de chemin peuvent être utilisées pour indiquer l'emplacement de ressources liées. Une variable de chemin correspond à un mappage simple (String -> IPath) définissant un raccourci pour un endroit du système de fichiers. Les variables peuvent faciliter la gestion des ressources liées en réduisant le nombre d'endroits où des chemins absolus et figés dans le code sont utilisés.  

Les variables de chemin rationalisent la gestion des ressources liées de diverses manières :

Le dernier point de cette liste mérite plus d'explications. Lorsqu'un utilisateur crée une ressource liée dans un projet, une description de celle-ci est ajoutée au fichier de description du projet (".project"), à l'emplacement de ce dernier. Grâce aux variables de chemin, les utilisateurs peuvent partager un projet (en copiant son contenu ou à l'aide d'un référentiel) et redéfinir la variable afin de l'adapter à chaque poste de travail. Par exemple, un utilisateur peut stocker des ressources externes sous c:\temp sur un système, alors qu'un autre sous Unix stockera ces mêmes ressources dans /home/username/tmp. La définition d'une variable de chemin dans chaque espace de travail (TEMP=c:\temp et TEMP=/home/userb/tmp) permet aux utilisateurs de dépasser cette différence et de partager des projets avec des ressources liées.

IPathVariableManager définit l'API pour créer, manipuler et résoudre des variables de chemin. Il fournit également des méthodes de validation des noms et valeurs de variables avant de les créer, ainsi que d'installation d'un programme d'écoute à informer lorsque les définitions de variables changent. Vous pouvez obtenir une instance de cette classe avec IWorkspace.getPathVariableManager. Observez les exemples de code en fin de section pour en savoir plus.

La méthode IResource.getRawLocation peut servir à trouver l'emplacement non résolu d'une ressource liée. Il s'agit en fait de découvrir le nom de la variable de chemin au lieu de la résoudre à sa valeur. Si l'emplacement d'une ressource n'est pas défini avec une variable de chemin, la méthode getRawLocation fonctionne exactement comme celle getLocation.

Liens rompus

Les clients manipulant des ressources via un programme doivent être informés du risque de liens rompus. Un lien se rompt lorsque l'emplacement d'une ressource liée n'existe pas ou est relatif à une variable de chemin non définie. Les cas ci-après s'appliquent lors de l'utilisation du protocole IResource :

Compatibilité avec les plug-ins installés

Certains plug-ins ne pouvant gérer des ressources liées, il existe plusieurs mécanismes disponibles permettant de les désactiver. Si vous écrivez un plug-in requérant absolument que tout le contenu du projet se trouve à l'emplacement par défaut du projet, vous pouvez recourir à ces mécanismes pour empêcher les utilisateurs de créer des ressources liées à des endroits non désirés.

Le premier mécanisme consiste à une interdiction de la nature du projet. Si vous définissez votre propre nature de projet, vous pouvez dans la définition que cette nature est compatible avec des ressources liées. Voici un exemple de définition de nature comportant une interdiction de nature :

<extension
	id="myNature"
	name="My Nature"
	point="org.eclipse.core.resources.natures">
	<runtime>
		<run class="com.xyz.MyNature"/>
	</runtime>
	<options allowLinking="false"/>
</extension>

Le deuxième mécanisme permettant d'empêcher la création de ressources liées est le point d'ancrage Team. Si vous établissez votre propre implémentation de référentiel, vous pouvez utiliser le point d'extension org.eclipse.core.resources.teamHook pour empêcher la création de ressources liées dans des projets partagés avec votre type de référentiel. Par défaut, les fournisseurs de référentiel n'autorisent pas les ressources liées dans des projets connectés au référentiel. 

Si la prise en charge du référentiel est fournie par un plug-in plus ancien et étranger aux ressources liées, vous ne pourrez pas créer des ressources liées dans ces projets. 

Enfin, il existe un paramètre de préférence pouvant servir à désactiver des ressources liées pour tout l'espace de travail. Alors que les deux mécanismes précédent d'interdiction fonctionnent sur la base d'un projet, cette préférence concerne tous les projets dans l'espace de travail. Pour la définir via un programme, employez la préférence ResourcesPlugin.PREF_DISABLE_LINKING. Ce paramètre sera généralement utilisé avec le mécanisme de remplacement de préférences du dispositif primaire pour permettre à ce dernier de l'installation Eclipse de désactiver des ressources liées. Vous remarquez que même cette préférence définie, les utilisateurs ou les plug-ins peuvent toujours la désactiver.

Ressources liées dans le code

Prenons quelques exemples d'emploi de ressources liées dans du code. Commençons par définir une variable de chemin :

   IWorkspace workspace = ResourcesPlugin.getWorkspace();
   IPathVariableManager pathMan = workspace.getPathVariableManager();
   String name = "TEMP";
   IPath value = new Path("c:\\temp");
   if (pathMan.validateName(name).isOK() && pathMan.validateValue(value).isOK()) {
      pathMan.setValue(name, value);
   } else {
      //nom ou valeur incorrects, lancer une exception ou avertir l'utilisateur
   }
Nous pouvons à présent créer une ressource liée relative à la variable de chemin définie :
   IProject project = workspace.getProject("Project");//assume this exists
   IFolder link = project.getFolder("Link");
   IPath location = new Path("TEMP/folder");
   if (workspace.validateLinkLocation(location).isOK()) {
      link.createLink(location, IResource.NONE, null);
   } else {
      //emplacement incorrect, lancer une exception ou avertir l'utilisateur
   }
C'est terminé ! Vous disposez maintenant d'un dossier lié dans votre espace de travail appelé "Link" et figurant dans "c:\temp\folder".

Terminons avec des fragments de code pour cette ressource liée afin d'illustrer le comportement d'autres méthodes par rapport à elle :

   link.getFullPath() ==> "/Project/Link"
   link.getLocation() ==> "c:\temp\folder"
   link.getRawLocation() ==> "TEMP/folder"
   link.isLinked() ==> "true"
   
   IFile child = link.getFile("abc.txt");
   child.create(...);
   child.getFullPath() ==> "/Project/Link/abc.txt"
   child.getLocation() ==> "c:\temp\folder\abc.txt"
   child.getRawLocation() ==> "c:\temp\folder\abc.txt"
   child.isLinked() ==> "false"
   

Copyright IBM Corporation and others 2000, 2003.