Suivi des modifications des ressources

Le plug-in des ressources inclut un mécanisme d'événement permettant de notifier les parties intéressées des modifications apportées aux ressources. Si vous devez effectuer un suivi des modifications appliquées à l'arborescence de ressources lorsque votre plug-in est en cours d'exécution, vous pouvez enregistrer un IResourceChangeListener avec l'espace de travail. Votre écouteur sera averti des changements via un objet IResourceChangeEvent les décrivant.

Traitement des modifications de ressources

Pour effectuer le suivi des modifications apportées aux ressources, vous devez enregistrer un écouteur de modifications de ressources dans l'espace de travail.

   IResourceChangeListener listener = new MyResourceChangeReporter();
   ResourcesPlugin.getWorkspace().addResourceChangeListener(
      listener, IResourceChangeEvent.POST_CHANGE);

Votre écouteur sera averti chaque fois que des modifications seront apportées aux ressources de l'espace de travail. Les méthodes d'API de ressources qui modifient ces dernières déclenchent ces événements comme fragment du comportement documenté. Le commentaire de méthode pour une méthode d'API de ressources indique explicitement s'il déclenche ou non un événement de changement de ressources. Par exemple, ce qui suit est intégré au commentaire IFile.setContents() :

   Cette méthode modifie les ressources. Ces modifications sont rapportées dans un événement de modification de ressources sous-jacent, en indiquant que le contenu du fichier a été modifié.

Les méthodes qui créent, suppriment ou modifient une ressource déclenchent généralement ces événements. Les méthodes qui lisent des ressources, mais ne les écrivent pas, ne déclenchent généralement pas ces événements.

Modifications par lot et deltas de ressources

Si vous devez modifier plusieurs ressources simultanément, vous pouvez faire un lot de vos appels d'API de modification des ressources de telle sorte qu'un seul événement de modification de ressources soit envoyé pour la totalité des modifications. IWorkspace.run(runnable, monitor) est utilisé pour regrouper les opérations. Les événements de modification de ressources ne sont envoyés aux écouteurs enregistrés qu'une fois l'exécutable spécifié terminé. Tous les exécutables supplémentaires (imbriqués) créés dans l'exécutable sont considérés comme faisant partie de l'opération par lot parent et les modifications de ressources apportées à ces exécutables apparaissent dans la notification de changement de ressources du parent.

Vous devez autant que possible regrouper vos modifications par lot pour limiter la surcharge de diffusion de nombreuses modifications granulaires. Faute de quoi, le système risque d'être submergé de notifications de modification des ressources et d'auto-générations.

L'événement de modification des ressources décrit les spécificités de la modification (ou de l'ensemble des modifications) apportée(s) à l'espace de travail. L'événement contient un delta de ressources qui décrit l'effet réseau des changements. Par exemple, si vous ajoutez une ressource et la supprimez ultérieurement au cours d'un lot de modifications, la ressource n'apparaîtra pas dans le delta.

Le delta de ressources est structuré comme une arborescence enracinée dans la racine de l'espace de travail. L'arborescence du delta de ressources décrit les types de modification suivants :

Pour traverser une arborescence de deltas de ressources, vous pouvez implémenter l'interface IResourceDeltaVisitor ou traverser l'arborescence explicitement à l'aide de IResource.getAffectedChildren. Les visiteurs de deltas de ressources implémentent une méthode visit appelée par le delta des ressources lorsqu'il énumère chaque modification de l'arborescence.

Remarque : Les modifications apportées aux propriétés de session des ressources ou aux propriétés persistantes des ressources ne sont pas identifiées dans le delta des ressources.

Evénements de changement des ressources

Les événements de changement des ressources sont envoyés lorsqu'une modification (ou un lot de modifications) est envoyé à l'espace de travail. De plus, ces événements sont envoyés pour certaines opérations spécifiques dans l'espace de travail. Le tableau ci-dessous résume les types d'événements de changement de ressources et le moment où ils sont rapportés.

Type d'événement

Description

PRE_CLOSE

Notifie les écouteurs qu'un projet va être fermé. Cet événement peut être utilisé pour extraire et sauvegarder les informations nécessaires de la représentation en mémoire (des propriétés de session, par exemple) d'un projet avant qu'il ne soit fermé. (Lorsqu'un projet est fermé, la représentation en mémoire est supprimée.) L'espace de travail est verrouillé (aucune ressource ne pouvant être mise à jour) pendant cet événement. L'événement contient le projet qui est en cours de fermeture.

PRE_DELETE

Notifie les écouteurs qu'un projet va être supprimé. Cet événement peut être utilisé pour effectuer des opérations de nettoyage, telles que la suppression d'un état sauvegardé, relatif au projet de votre répertoire de plug-in. L'espace de travail est verrouillé (aucune ressource ne pouvant être mise à jour) pendant cet événement. L'événement contient le projet en cours de suppression.

PRE_AUTOBUILD

Notifies les écouteurs avant qu'une auto-génération ne se produise. Cet événement est diffusé lorsque la plateforme détecte qu'une auto-génération est nécessaire, que ce mode soit ou non activé. L'espace de travail n'est pas verrouillé au cours de cet événement (les ressources peuvent donc être mises à jour). L'événement contient un delta de ressources décrivant les modifications qui ont eu lieu depuis que le dernier événement POST_CHANGE a été rapporté.

POST_AUTOBUILD

Notifie les écouteurs après qu'une auto-génération ait eu lieu. Cet événement est diffusé après que la plateforme ait effectué une auto-génération, que ce mode soit ou non activé. L'espace de travail n'est pas verrouillé au cours de cet événement (les ressources peuvent donc être mises à jour). L'événement contient un delta de ressources décrivant les modifications qui ont eu lieu depuis que le dernier événement POST_CHANGE a été rapporté.

POST_CHANGE

Décrit un ensemble de modifications qui se sont produites dans l'espace de travail depuis que le dernier événement POST_CHANGE a été rapporté. Déclenché après une API de modification de ressources, utilisé individuellement ou dans un lot de modifications de l'espace de travail. Déclenché également après l'exécution d'une notification PRE_AUTOBUILD ou POST_AUTOBUILD. L'événement contient un delta de ressources décrivant les modifications nettes depuis le dernier événement POST_CHANGE. L'espace de travail est verrouillé (aucune ressource ne pouvant être mise à jour) au cours de cet événement.

Implémentation d'un écouteur de changement de ressources

L'exemple suivant implémente un écouteur de changement de ressources basé sur une console. Un écouteur de changement de ressources est enregistré pour des types d'événements spécifiques et des informations sur ces événements sont affichées sur la console :

   IResourceChangeListener listener = new MyResourceChangeReporter();
   ResourcesPlugin.getWorkspace().addResourceChangeListener(listener,
      IResourceChangeEvent.PRE_CLOSE
      | IResourceChangeEvent.PRE_DELETE
      | IResourceChangeEvent.PRE_AUTO_BUILD
      | IResourceChangeEvent.POST_AUTO_BUILD
      | IResourceChangeEvent.POST_CHANGE);

L'écouteur vérifie pour chaque type d'événement et rapporte des informations sur les ressources qui ont été modifiées et les types de changements qui ont eu lieu. Bien que cet exemple soit conçu pour montrer un écouteur général traitant tous les types d'événements de ressources, un écouteur standard ne serait affecté qu'à un seul type d'événement.

L'implémentation de POST_CHANGE utilise une autre classe pouvant être utilisée pour visiter les changements apportés au delta de ressources.

   import org.eclipse.resources.*;
   import org.eclipse.runtime.*;

   public class MyResourceChangeReporter implements IResourceChangeListener {
      public void resourceChanged(IResourceChangeEvent event) {
         IResource res = event.getResource();
         switch (event.getType()) {
            case IResourceChangeEvent.PRE_CLOSE:
               System.out.print("Projet ");
               System.out.print(res.getFullPath());
               System.out.println(" en cours de fermeture.");
               break;
            case IResourceChangeEvent.PRE_DELETE:
               System.out.print("Projet ");
               System.out.print(res.getFullPath());
               System.out.println(" en cours de suppression.");
               break;
            case IResourceChangeEvent.POST_CHANGE:
               System.out.println("Les ressources ont été modifiées.");
               event.getDelta().accept(new DeltaPrinter());
               break;
            case IResourceChangeEvent.PRE_AUTO_BUILD:
               System.out.println("L'auto-génération va démarrer.");
               event.getDelta().accept(new DeltaPrinter());
               break;
            case IResourceChangeEvent.POST_AUTO_BUILD:
               System.out.println("Auto-génération terminée.");
               event.getDelta().accept(new DeltaPrinter());
               break;
         }
      }
   }

La classe DeltaPrinter implémente l'interface IResourceDeltaVisitor pour interroger le delta de ressources. La méthode visit() est appelée pour chaque changement de ressources apporté au delta de ressources. Le visiteur utilise une valeur de retour pour indiquer si les deltas des ressources enfant doivent être visités.

   class DeltaPrinter implements IResourceDeltaVisitor {
      public boolean visit(IResourceDelta delta) {
         IResource res = delta.getResource();
         switch (delta.getKind()) {
            case IResourceDelta.ADDED:
               System.out.print("Ressource ");
               System.out.print(res.getFullPath());
               System.out.println(" ajoutée.");
               break;
            case IResourceDelta.REMOVED"
               System.out.print("Ressource ");
               System.out.print(res.getFullPath());
               System.out.println(" supprimée.");
               break;
            case IResourceDelta.CHANGED:
               System.out.print("Ressource ");
               System.out.print(res.getFullPath());
               System.out.println(" modifiée.");
               break;
         }
         return true; // visiter les enfants
      }
   }

De plus amples informations peuvent être obtenues du delta de ressources fourni. Le fragment ci-dessous montre comment le cas IResourceDelta.CHANGED peut être implémenté pour détailler les changements de ressources.

   ...
   case IResourceDelta.CHANGED:
      System.out.print("Ressource ");
      System.out.print(delta.getFullPath());
      System.out.println(" modifiée.");
      int flags = delta.getFlags();
      if ((flags & IResourceDelta.CONTENT) != 0) {
            System.out.println("--> Contenu modifié");
      }
      if ((flags & IResourceDelta.REPLACED) != 0) {
            System.out.println("--> Contenu remplacé");
      }
      if ((flags & IResourceDelta.MARKERS) != 0) {
            System.out.println("--> Marqueur modifié");
            IMarkerDelta[] markers = delta.getMarkerDeltas();
            // si les marqueurs vous intéressent, observez ces deltas.
      }
      break;
   ...

Pour une description complète des deltas de ressources, des visiteurs et des deltas de marqueurs, consultez la spécification de l'API pour IResourceDelta, IResourceDeltaVisitor et IMarkerDelta.

Remarque : Les écouteurs de changement de ressources sont utiles pour effectuer le suivi des modifications apportées aux ressources pendant l'activation de votre plug-in. Si votre plug-in enregistre un écouteur de changement de ressources pendant son code de démarrage, il est possible que de nombreux événements de changement de ressources soient déclenchés avant l'activation de votre plug-in. Le delta de ressources contenu dans le premier événement de changement de ressources reçu par votre plug-in ne contiendra pas la totalité des modifications effectuées depuis la dernière activation du plug-in. Si vous devez effectuer le suivi des changements réalisés entre les activations de votre plug-in, vous devez utiliser le support fourni pour la sauvegarde du plan de travail. Ceci est décrit à la section Participation à la sauvegarde de l'espace de travail.

Copyright IBM Corporation and others 2000, 2003.