Lorsque la plate-forme est en cours d'exécution et le plug-in de ressources est actif, l'espace de travail est représenté par une instance de IWorkspace, qui met à disposition un protocole pour accéder aux ressources contenues. Une instance IWorkspace représente une collection de fichiers et de répertoires associés dans le système de fichiers local. Vous pouvez accéder à l'espace de travail à partir de la classe du plug-in de ressources (définie dans org.eclipse.core.resources).
IWorkspace workspace = ResourcesPlugin.getWorkspace();
Lorsque le plug-in des ressources n'est pas en cours d'exécution, l'espace de travail existe uniquement dans le système de fichiers local et est visualisé ou manipulé par l'utilisateur via des outils basés sur un fichier standard. Regardons ce à quoi ressemble un espace de travail sur le disque tout en expliquant l'API du plug-in des ressources.
Lorsque vous avez installé le kit SDK de la plate-forme, vous avez dézippé les fichiers dans un répertoire de votre choix. Ce répertoire est le répertoire principal de la plate-forme. Il s'agit du répertoire qui contient entre autre, le répertoire plugins. Dans le répertoire principal de la plate-forme, il existe un répertoire appelé workspace qui est utilisé pour contenir des ressources qui sont créées et manipulées par la plate-forme. Si vous regardez dans le répertoire workspace, vous verrez des sous-répertoires distincts pour chaque projet présent dans l'espace de travail. A l'intérieur de ces sous-répertoires figurent les dossiers et les fichiers que chaque projet contient.
Si le SDK de notre exemple est installé dans c:\MySDK, alors à l'intérieur du répertoire c:\MySDK\workspace, nous trouvons des sous-répertoires sous les projets de l'espace de travail, MyWeb et MyServlet. Il s'agit des répertoires des programmes des projets. Les répertoires des programmes sont créés par la plate-forme lorsque l'utilisateur crée un projet.
A l'intérieur de chaque répertoire, figurent les fichiers et les dossiers du projet, présentés exactement comme dans l'arborescence des ressources de l'espace de travail. Tous les noms de fichiers sont identiques et le contenu des fichiers est le même qu'ils soient accessibles à partir du système de fichiers ou de l'espace de travail. La seule surprise est le fichier .project, présenté sous peu.
C:\MySDK\workspace (racine de l'espace de travail) .metadata\ (répertoire des métadonnées de la plate-forme) MyWeb\ (répertoire du contenu du projet pour MyWeb) .project index.html images\ logo.png MyServlet\ (répertoire du contenu du projet pour MyServlet) .project src\ main.java bin\ main.class
La plate-forme comporte un répertoire spécial .metadata destiné aux informations internes de la plate-forme. Le répertoire .metadata d'un espace de travail est considéré comme une "boîte noire". Les informations importantes concernant la structure de l'espace de travail, telles que les références d'un projet ou les propriétés d'une ressource, sont stockées dans les métadonnées de l'espace de travail et ne doivent être accessibles que par des outils via l'API de la plate-forme. Ces fichiers ne doivent jamais être édités ou manipulés à l'aide de l'API du système de fichiers générique.
Par ailleurs, chaque projet possède son propre fichier .project, dans lequel des métadonnées sont conservées. Ce fichier est principalement un équivalent sur disque des informations contenues dans un IProjectDescription de projet.
Outre le répertoire .metadata et les fichiers .project, les dossiers et les fichiers du répertoire de l'espace de travail sont disponibles pour d'autres outils. Ils peuvent être manipulés par des outils indépendants, tels que des éditeurs de texte et des utilitaires du système de fichiers. Cependant, l'utilisateur doit être très attentif au moment d'éditer ces fichiers dans le plan de travail et en dehors de ce dernier. L'édition d'un fichier est identique avec deux outils indépendants. Le plan de travail permet des opérations d'actualisation pour synchroniser la vue des ressources dans l'espace de travail avec l'état réel dans le système de fichiers et actualisé périodiquement l'espace de travail en fonction de l'état du système de fichiers.
L'API des ressources permet de manipuler cette arborescence de ressources dans le code. Nous allons examiner plusieurs fragments de code pour avoir un rapide aperçu de l'API des ressources. Cette dernière est définie dans une série d'interfaces dans org.eclipse.core.resources. Il existe des interfaces pour tous les types de ressources, tels que IProject, IFolder et IFile. Un protocole commun extensif est défini dans IResource. Nous utilisons également IPath de l'interface org.eclipse.core.runtime qui représente des chemins d'accès segmentés, des chemins d'accès au système de fichiers ou à une ressource par exemple.
La manipulation de ressources s'apparente beaucoup à celle de fichiers avec java.io.File. L'API est basée sur des descripteurs. Lorsque vous utilisez une API telle que getProject ou getFolder, vous obtenez un descripteur de la ressource. Il n'est ni garanti, ni obligatoire que la ressource même existe tant que vous n'essayez pas de l'utiliser. Si vous pensez qu'une ressource existe, vous pouvez recourir à la méthode exists pour le confirmer.
Pour naviguer dans l'espace de travail à partir d'un plug-in, nous devons d'abord obtenir IWorkspaceRoot, qui représente le niveau le plus haut dans la hiérarchie des ressources de l'espace de travail.
IWorkspaceRoot myWorkspaceRoot = ResourcesPlugin.getWorkspace().getRoot();
Dès que nous avons une racine de l'espace, nous pouvons accéder aux projets dans l'espace de travail.
IProject myWebProject = myWorkspaceRoot.getProject("MyWeb"); // ouvre si besoin est if (myWebProject.exists() && !myWebProject.isOpen()) myWebProject.open(null);
Pour pouvoir manipuler un projet, celui-ci doit d'abord être ouvert. L'ouverture du projet lit la structure du projet à partir du disque et crée la représentation objet en mémoire de l'arborescence des ressources du projet. L'ouverture d'un projet est une opération explicite du fait que chaque projet ouvert consume de la mémoire pour représenter l'arborescence des ressources en interne et les projets ouverts participent à des événements du cycle de vie des ressources (la génération par exemple) qui peuvent s'avérer interminables. En règle générale, les projets fermés ne peuvent pas être accessibles et apparaissent vides mêmes si les ressources sont toujours présentes dans le système de fichiers.
Vous noterez que de nombreux exemples de ressources transmettent un paramètre null lors de la manipulation des ressources. De nombreuses opérations sont suffisamment lourdes pour garantir la génération de rapports de progression et l'annulation utilisateur. Si votre code dispose d'une interface utilisateur, vous transmettrez généralement un IProgressMonitor qui permet au plug-in des ressources de générer un rapport de progression à mesure que les ressources sont manipulées et à l'utilisateur d'annuler l'opération s'il le souhaite. Pour le moment, nous transmettons simplement la valeur null, indiquant qu'il n'y a pas de contrôle de la progression.
Une fois un projet ouvert, vous pouvez accéder aux dossiers et fichiers qu'il contient, ainsi que qu'en créer d'autres. Dans l'exemple suivant, il est question de créer une ressource de fichier à partir du contenu d'un fichier situé en dehors de l'espace de travail.
IFolder imagesFolder = myWebProject.getFolder("images"); if (imagesFolder.exists()) { // crée un fichier IFile newLogo = imagesFolder.getFile("newLogo.png"); FileInputStream fileStream = new FileInputStream( "c:/MyOtherData/newLogo.png"); newLogo.create(fileStream, false, null); // ferme le flux de fichiers. }
Dans l'exemple ci-dessous, la première ligne obtient un identificateur pour le dossier d'images. Il faut vérifier que le dossier existe avant de pouvoir s'en servir. De même, quand on obtient le fichier newLogo, l'identificateur ne représente pas une vrai fichier jusqu'à ce que l'on crée le fichier à la dernière ligne. Dans cet exemple, on crée le fichier en le remplissant avec le contenu de logo.png.
Le fragment suivant est similaire au précédent, mais il copie le fichier newLogo du logo d'origine plutôt que d'en créer un à partir de son contenu.
IFile logo = imagesFolder.getFile("logo.png"); if (logo.exists()) { IPath newLogoPath = new Path("newLogo.png"); logo.copy(newLogoPath, false, null); IFile newLogo = imagesFolder.getFile("newLogo.png"); ... }
Enfin, nous allons créer un autre dossier d'images et déplacer le fichier nouvellement créé dedans. Comme effet secondaire de son déplacement, nous renommons le fichier.
... IFolder newImagesFolder = myWebProject.getFolder("newimages"); newImagesFolder.create(false, true, null); IPath renamedPath = newImagesFolder.getFullPath().append("renamedLogo.png"); newLogo.move(renamedPath, false, null); IFile renamedLogo = newImagesFolder.getFile("renamedLogo.png");
La plupart des méthodes d'API d ressources incluent un indicateur booléen force précisant si les ressources non synchronisées avec les fichiers du système local sont tout de même mises à jour. Reportez-vous à IResource pour en savoir plus. Vous pouvez également utiliser IResource.isSynchronized pour savoir si une ressource donnée est synchronisée avec le système de fichiers.
Dans l'exemple d'arborescence des ressources, nous avons présumé que tous les répertoires des programmes de projet se trouvent dans le répertoire workspace sous le répertoire racine de la plate-forme (C:\MySDK\workspace). Il s'agit de la configuration par défaut des projets. Cependant, le répertoire des programmes d'un projet peut être remappé sur n'importe quel répertoire du système de fichiers, éventuellement sur une autre unité de disque.
La capacité de mapper l'emplacement d'un projet indépendamment des autres projets permet à l'utilisateur de stocker le contenu d'un projet à un endroit qui tombe sous le sens pour le projet et l'équipe du projet. Le répertoire des programmes (contenu) d'un projet doit être considéré comme étant "en dehors". Ceci signifie que les utilisateurs peuvent créer, modifier et supprimer des ressources à l'aide du plan de travail et des plug-in, ou en utilisant directement le système de fichiers basé sur les outils et les éditeurs.
Les noms des chemins d'accès aux ressources ne sont pas des chemins d'accès complets au système de fichiers. Les chemins d'accès aux ressources ne correspondent pas toujours à l'emplacement du projet (en général, le répertoire workspace). Pour obtenir le chemin d'accès complet à une ressource, vous devez recherche son emplacement avec IResource.getLocation. Vous ne pouvez toutefois pas utiliser IProjectDescription.setLocation pour modifier l'emplacement car il s'agit d'une méthode setter pour une structure de données.
Inversement, si vous voulez extraire l'objet de ressource correspondant par rapport à un chemin donné, vous pouvez utiliser IWorkspaceRoot.getFileForLocation ou IWorkspaceRoot.getContainerForLocation.
Lorsque nous utilisons l'API des ressources pour modifier l'arborescence des ressources de notre espace de travail, les fichiers sont modifiés dans le système de fichiers en plus de la mise à jour des objets ressources. Qu'en est-il des modifications apportées aux fichiers de ressources en dehors de l'API de la plate-forme ?
Les modifications externes aux ressources ne sont pas reflétées dans l'espace de travail et les objets ressource tant qu'elles ne sont pas détectées par le plug-in des ressources. Le plug-in des ressources utilise également un mécanisme approprié pour chaque système d'exploitation natif donné pour la détection des modifications externes apportées au système de fichiers. Par ailleurs, les clients utilisent l'API de ressources pour synchroniser l'espace de travail et les objets de ressource avec le système de fichiers local en mode silencieux et sans intervention de l'utilisateur. L'utilisateur peut également forcer explicitement une actualisation dans la vue du navigateur de ressources du plan de travail.
Dans les API de ressources, de nombreuses méthodes incluent un paramètre force qui spécifie le mode de traitement des ressources situées en dehors de la synchronisation avec le système de fichiers. Les références de l'API pour chaque méthode fournissent des informations spécifiques sur ce paramètre. Des méthodes supplémentaires de l'API permettent un contrôle programmatique de la régénération du système de fichiers, tel que IResource.refreshLocal(int depth, IProgressMonitor monitor). Pour plus d'informations sur les coûts et l'utilisation correcte de ces méthodes, reportez-vous à la section IResource.
Les plug-ins qui fournissent leur propre mécanisme pour actualiser périodiquement l'espace de travail en fonction de l'état du système de fichiers externe peuvent utiliser le point d'extension org.eclipse.core.resources.refreshProviders. Pour plus d'informations, reportez-vous à la section régénérer les fournisseurs.