Resourcemerktekens

Plugins kunnen speciale bestandsextensies definiëren en editors aanbieden met speciale bewerkingsmogelijkheden voor de betreffende bestandstypen.   Tijdens het bewerken of bouwen van een resource moet een plugin resources soms van een tag voorzien om problemen of andere informatie aan de gebruiker mee te kunnen delen. Voor het beheer van dergelijke informatie worden resources gemarkeerd.

Een merkteken lijkt op een geel notitiepapiertje dat op een resource is geplakt. Op het merkteken kunt u informatie over een probleem schrijven (b.v. locatie, severity) of over een uit te voeren taak.  Anderzijds kunt u gewoon een locatie voor een merkteken noteren als bladwijzer. 

Gebruikers kunnen snel van merkteken naar merkteken in de resource gaan. De gebruikersinterface van de workbench ondersteunt het weergeven van bladwijzers, onderbrekingspunten, taken en problemen. Dit gebeurt aan de zijkant van de editor.  De merktekens kunnen ook worden weergegeven als items in views, bijvoorbeeld de taak- of bladwijzerview.

In de platformresources-API zijn methoden gedefinieerd voor het maken van merktekens, het instellen van merktekenwaarden en het uitbreiden van het platform met nieuwe merktekentypen. Het platform beheert de merktekens, maar de plugins zorgen voor het maken en verwijderen en de kenmerkwaarden.

Merktekens horen kleine, onopvallende objecten te zijn. Er kunnen honderden of zelfs duizenden merktekens in een project aanwezig zijn.  Het Java-compileerprogramma gebruikt bijvoorbeeld een merkteken om de gevonden problemen in de broncode te markeren.

Het platform verwijdert merktekens die aan gewiste resources zijn gekoppeld, maar plugins zorgen voor het verwijderen van merktekens die niet meer van toepassing zijn op nog wel bestaande resources.

Bewerkingen van merktekens

Het bewerken van een merkteken lijkt op het bewerken van een resource.  Merktekens zijn handleobjecten.  U kunt een merktekenhandle in een resource tegenkomen, maar u weet pas of het merkteken bestaat als u het protocol exists() gebruikt of op een andere manier bewerkingen uitvoert.  Als u zeker bent dat het merkteken bestaat, kunt u benoemde kenmerken zoeken die eraan toegewezen kunnen zijn.

Merktekens zijn eigendom van het platform en worden hierdoor ook beheerd. Hierdoor kunnen merktekens blijvend worden gemaakt en listeners op de hoogte gehouden van het toevoegen, wissen of wijzigen van merktekens.  Plugins zorgen voor het maken van noodzakelijke merktekens, het wijzigen van de kenmerken en het verwijderen ervan als de niet meer nodig zijn.

Merktekens maken

Merktekens worden niet direct met een constructor gemaakt. Ze worden gemaakt met een factorymethode (IResource.createMarker()) in de gekoppelde resource.

   IMarker marker = file.createMarker(IMarker.TASK);

Om een merkteken met een algemeen bereik te maken (niet gekoppeld aan een specifieke resource), kunt u de hoofdmap van het werkgebied gebruiken als resource (IWorkspace.getRoot()).

Merktekens wissen

De code voor het wissen van een merkteken is niet ingewikkeld.

  try {
      marker.delete();
  } catch (CoreException e) {
      // er is iets fout gegaan
   }

Als een merkteken wordt gewist, wordt het merktekenobject (handle) "verouderd." Plugins moeten het protocol IMarker.exists() gebruiken om te zorgen dat het merktekenobject geldig blijft.

Merktekens kunnen als batch worden verwijderd door de resource te vragen de merktekens te wissen. Deze methode is geschikt om veel merktekens tegelijkertijd te verwijderen of als afzonderlijke merktekens of ID's niet beschikbaar zijn.

   int depth = IResource.DEPTH_INFINITE;
  try {
      resource.deleteMarkers(IMarker.PROBLEM, true, depth);
  } catch (CoreException e) {
      // er is iets fout gegaan
   }

Als u een groep merktekens wilt wissen, geeft u een merktekentype op, bijvoorbeeld IMarker.PROBLEM of null als u alle merktekens wilt wissen. Het tweede argument geeft aan of u merktekens van een subtype wilt wissen.  (We bespreken subtypen bij het definiëren van nieuwe merktekentypen.)  Het argument depth bepaalt hoe diep de wisactie gaat. 

U kunt merktekens wissen met IWorkspace.deleteMarkers(IMarker []).

Merktekenkenmerken

U kunt voor een merkteken de gekoppelde resource, het ID (uniek ten opzichte van de resource) en het type opvragen. U kunt ook toegang krijgen tot aanvullende informatie via generieke kenmerken.

Ieder type merkteken heeft een specifieke set kenmerken die door de creator van het merktekentype zijn gedefinieerd volgens de regels voor naamgeving.  In de interface IMarker wordt een set constanten gedefinieerd met de standaardkenmerknamen (en een aantal verachte waarden) van de platformmerktekentypen. De volgende methode bewerkt kenmerken met de platformconstanten.

   IMarker marker = file.createMarker(IMarker.TASK);
   if (marker.exists()) {
  try {
         marker.setAttribute(IMarker.MESSAGE, "A sample marker message");
         marker.setAttribute(IMarker.PRIORITY, IMarker.PRIORITY_HIGH);
  } catch (CoreException e) {
         // U moet de case afhandelen waarin het merkteken niet meer bestaat      }
   }

Kenmerken worden generiek beheerd als naam-waardeparen, waarbij de namen tekenreeksen zijn en de waarden een van de ondersteunde waardetypen (booleaans, geheel getal, tekenreeks). Door de beperking van waardetypen kan het platform de merktekens snel en eenvoudig permanent maken.

Query's naar merktekens uitvoeren

U kunt in resources een query uitvoeren naar merktekens en merktekens van onderliggende items. Een query in de hoofdmap van het werkgebied met een oneindige diepte richt zich bijvoorbeeld op alle merktekens in het werkgebied.

   IMarker[] problems = null;
   int depth = IResource.DEPTH_INFINITE;
  try {
      problems = resource.findMarkers(IMarker.PROBLEM, true, depth);
  } catch (CoreException e) {
      // er is iets fout gegaan
   }

Het resultaat dat door findMarkers wordt geretourneerd, is afhankelijk van de doorgegeven argumenten. In het bovenstaande codefragment zoeken we alle merktekens van het type PROBLEM die in de resource voorkomen en alle directe of indirecte onderliggende items. 

Als u null doorgeeft als type van het merkteken, krijgt u alle merktekentypen die aan de resource zijn gekoppeld. Het tweede argument geeft aan of u de onderliggende items van de resource wilt bekijken.  Het argument depth bepaalt de diepte van de zoekopdracht als u de onderliggende items van de resource bekijkt. De diepte kan een van de volgende waarden hebben: DEPTH_ZERO (alleen de betreffende resource), DEPTH_ONE (de resource en alle directe onderliggende items) of DEPTH_INFINITE (de resource en alle directe of indirecte onderliggende items).

Permanente merktekens

De standaardplatformmerktekens (taak, probleem en bladwijzer) zijn permanent. Dit betekent dat hun status wordt opgeslagen bij het afsluiten en opstarten van de workbench. Permanente merktekens kunnen echter naar keuze tijdelijk worden gemaakt door het gereserveerde kenmerk transient in te stellen op true (waar).

Nieuwe merktekentypen die door plugins worden gedeclareerd, zijn niet permanent, tenzij ze als zodanig zijn gedeclareerd.

Het platform uitbreiden met nieuwe merktekentypen

Plugins kunnen hun eigen merktekentypen definiëren met het extensiepunt org.eclipse.core.resources.markers. De standaardmerktekentypen voor problemen, taken en bladwijzers worden door het platform gedeclareerd in de pluginmarkup van de resource.

       <extension 
      id="problemmarker" 
      point="org.eclipse.core.resources.markers" 
      name="%problemName">
      <super type="org.eclipse.core.resources.marker"/>
      <persistent value="true"/>
      <attribute name="severity"/>
      <attribute name="message"/>
      <attribute name="location"/>
    </extension>    <extension 
      id="taskmarker" 
      point="org.eclipse.core.resources.markers" 
      name="%taskName">
      <super type="org.eclipse.core.resources.marker"/>
      <persistent value="true"/>
      <attribute name="priority"/>
      <attribute name="message"/>
      <attribute name="done"/>
      <attribute name="userEditable"/>      
    </extension>    <extension 
      id="bookmark" 
      point="org.eclipse.core.resources.markers" 
      name="%bookmarkName">
      <super type="org.eclipse.core.resources.marker"/>
      <persistent value="true"/>
      <attribute name="message"/>
      <attribute name="location"/>
    </extension>

Nieuwe merktekentypen worden afgeleid van bestaande typen met behulp van meervoudige overname. Nieuwe merktekentypen nemen alle kenmerken over van het supertype en voegen nieuwe kenmerken toe die zijn gedefinieerd als onderdeel van de declaratie. Ze nemen ook de kenmerken over van de supertypen van hun supertypen. In de volgende markup wordt een nieuw soort merkteken gedefinieerd in de hypothetische plugin com.example.markers.

       <extension 
      id="mymarker"
      point="org.eclipse.core.resources.markers" />
    <extension 
      id="myproblem"
      point="org.eclipse.core.resources.markers">
      <super type="org.eclipse.core.resources.problemmarker"/>
      <super type="com.example.markers.mymarker"/>
      <attribute name="myAttribute" />
      <persistent value="true" />
    </extension>

Let erop dat het type org.eclipse.core.resources.problemmarker in feite een van de vooraf gedefinieerde typen is (alias IMarker.PROBLEM). 

Het enige aspect van het supertype van een merkteken dat niet wordt overgenomen, is de permanentievlag.   De standaardwaarde van permanentie is false (onwaar), dus een merktekentype dat permanent gemaakt moet worden, moet <persistent value="true"/> bevatten.

Na het declareren van een nieuw merktekentype in het manifestbestand van de plugin, kunt u instances maken van het merktekentype com.example.markers.myproblem en vrij het kenmerk myAttribute instellen of ophalen.

Door nieuwe kenmerken te declareren kunt u gegevens aan merktekens koppelen die u elders wilt gebruiken (in uw views en editors). Merktekens van een bepaald type hoeven niet dezelfde waarden te hebben voor alle gedeclareerde kenmerken. De kenmerkdeclaraties zijn meer bedoeld voor het oplossen van problemen met de conventies voor naamgeving (iedereen gebruikt "message" om over de beschrijving van het merkteken te praten) dan voor het beperken van de content.

   public IMarker createMyMarker(IResource resource) {
  try {
         IMarker marker = resource.createMarker("com.example.markers.myproblem");
         marker.setAttribute("myAttribute", "MYVALUE");
         return marker;
  } catch (CoreException e) {
         // u moet de cases afhandelen waarin de kenmerkwaarde is afgewezen
      }
   }

U kunt een query naar uw eigen merktekentypen op dezelfde manier uitvoeren als een zoekopdracht naar platformmerktekentypen.  De onderstaande methode zoekt alle mymarkers die aan de betreffende doelresource zijn gekoppeld en tevens alle onderliggende items. Let erop dat de methode ook alle myproblems zoekt, omdat true wordt doorgegeven als waarde van het argument includeSubtypes.

   public IMarker[] findMyMarkers(IResource target) {
      String type = "com.example.markers.mymarker";
      IMarker[] markers = target.findMarkers(type, true, IResource.DEPTH_INFINITE);
   }