Resurssien merkinnät

Lisäosat voivat määrittää erikoistuneita tiedoston tunnisteita ja lisätä muokkausohjelmia, joissa on erikoismuokkaustoimintoja näitä tiedostolajeja varten. Resurssin muokkauksen (tai koonnin) aikana lisäosan voi olla tarpeen merkitä resurssit, jotta se voi ilmoittaa käyttäjälle ongelmista tai muista tiedoista.Tällaisia tietoja hallitaan resurssien merkintämenetelmän avulla.

Merkintä on kuin keltainen muistilappu, joka on kiinnitetty resurssiin. Merkinnässä on tietoja ongelmasta (esimerkiksi sen sijainti ja vakavuus) tai tarpeellisesta tehtävästä. Voit myös käyttää merkintää yksinkertaisesti kirjanmerkkinä. 

Käyttäjät voivat siirtyä resurssin merkittyyn sijaintiin nopeasti. Työympäristön käyttöliittymä tukee kirjanmerkkien, keskeytyskohtien, tehtävien ja ongelmien esitystä muokkausohjelman sivussa.  Merkinnät voi näyttää myös kohteina näkymissä, esimerkiksi tehtävien tai kirjanmerkkien näkymässä.

Ympäristön resurssien sovellusohjelmaliittymä määrittää metodeja, joiden avulla voi luoda merkintöjä, määrittää merkintöjen arvoja ja laajentaa ympäristöä uusilla merkintälajeilla. Ympäristö hallitsee merkintöjä, lisäosat niiden luontia ja poistoa sekä määritteiden arvoja.

Merkintöjen on tarkoitus olla pieniä, suppeita objekteja. Yhdessä projektissa niitä voi olla satoja, jopa tuhansia. Esimerkiksi Java-kääntäjä merkitsee kunkin lähdekoodista löytämänsä ongelman merkinnällä.

Ympäristö poistaa poistettuihin resursseihin liitetyt merkinnät, mutta lisäosat vastaavat vanhentuneiden merkintöjensä poistosta, kun merkinnät eivät enää päde yhä olemassa olevaan resurssiin.

Merkintöjen toiminnot

Merkinnän käsittely on samanlaista kuin resurssin käsittely. Merkinnät ovat kahvaobjekteja. Voit noutaa merkinnän kahvan resurssista, mutta et voi olla varma, onko se todella olemassa, ennen kuin käytät exists()-käytäntöä tai muutoin yrität käsitellä sitä. Kun olet varmistanut, että merkintä on olemassa, voit tehdä kyselyn, joka koskee sille ehkä määritettyjä nimettyjä määritteitä.

Ympäristö omistaa merkinnät ja hallitsee niitä sekä huolehtii merkintöjen pysyvyydestä ja ilmoittaa kuuntelutoiminnoille, kun merkintöjä lisätään, poistetaan tai muutetaan. Lisäosat vastaavat tarvittavien merkintöjen luonnista, niiden määritteiden muuttamisesta ja merkintöjen poistosta, kun niitä ei enää tarvita.

Merkintöjen luonti

Merkintöjä ei luoda suoraan konstruktorin avulla. Ne luodaan käyttämällä factory-metodia (IResource.createMarker()) asiaan liittyvässä resurssissa.

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

Voit luoda merkinnän, jolla on yleisvaikutusalue (eli se ei liity mihinkään tiettyyn resurssiin), käyttämällä resurssina työtilan juurta (IWorkspace.getRoot()).

Merkintöjen poisto

Merkinnän poiston koodi on yksinkertainen.

   try {
      marker.delete();
  } catch (CoreException e) {
      // Jokin meni pieleen
   }

Kun merkintä poistetaan, sen merkintäobjektista (kahvasta) tulee "vanhentunut". Lisäosien on varmistettava IMarker.exists()-käytännön avulla, että merkintäobjekti on yhä kelvollinen.

Merkinnät voi poistaa eräajossa pyytämällä resurssia poistamaan merkintänsä. Tämä metodi on hyödyllinen, jos on tarpeen poistaa useita merkintöjä kerralla tai jos yksittäiset merkintäviittaukset tai tunnukset eivät ole käytettävissä.

   int depth = IResource.DEPTH_INFINITE;
   try {
      resource.deleteMarkers(IMarker.PROBLEM, true, depth);
  } catch (CoreException e) {
      // jokin meni pieleen
   }

Voit poistaa joukon merkintöjä määrittämällä poistettavan merkinnän lajin, esimerkiksi IMarker.PROBLEM, tai null, jos haluat poistaa kaikki merkinnät. Toinen argumentti osoittaa, poistetaanko merkintöjen alilajit. (Alilajeja käsitellään tuonnempana uusien merkintälajien määrityksen yhteydessä.) Depth-argumentti määrää poiston syvyyden. 

Voit poistaa merkintöjä myös IWorkspace.deleteMarkers(IMarker[])-metodin avulla.

Merkintöjen määritteet

Voit kysyä merkintään liittyvää resurssia, merkinnän tunnusta (yksilöllinen suhteessa kyseiseen resurssin) ja sen lajia. Voit myös käyttää lisätietoja yleisten määritteiden avulla.

Kullakin merkinnän lajilla on tietty määritejoukko, jonka merkintälajin luoja määrittää nimeämiskäytäntöjen avulla.  IMarker-rajapinta määrittää joukon vakioita, jotka sisältävät ympäristön merkintälajien tavalliset määritteiden nimet (sekä joitakin odotettuja arvoja). Seuraava metodi käsittelee määritteitä ympäristön vakioiden avulla.

   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) {
         // On käsiteltävä tapaus, jossa merkintää ei enää ole      }
   }

Määritteitä ylläpidetään nimi/arvo-pareina, missä nimet ovat merkkijonoja ja arvot voivat olla mitä tahansa tuettuja arvolajeja (totuusarvo, kokonaisluku, merkkijono). Arvolajeja rajoittamalla ympäristö voi tehdä merkinnät pysyviksi nopeasti ja yksinkertaisesti.

Merkintöjen kysely

Resursseihin voi kohdistaa niiden merkintöjä koskevan kyselyn ja merkintöihin niiden aliobjekteja koskevan kyselyn. Esimerkiksi työtilan juuren kysely määrittämättömässä syvyydessä kattaa työtilan kaikki merkinnät.

   IMarker[] problems = null;
   int depth = IResource.DEPTH_INFINITE;
   try {
      problems = resource.findMarkers(IMarker.PROBLEM, true, depth);
  } catch (CoreException e) {
      // jokin meni pieleen
   }

Kohteen findMarkers palauttama tulos määräytyy välitettyjen argumenttien mukaan. Edellä kuvatussa katkelmassa etsitään kaikkia merkintöjä, joiden laji on PROBLEM ja jotka ovat resurssissa ja niiden kaikkia suoria ja epäsuoria jälkeläisiä. 

Jos välität merkinnän lajina arvon null, järjestelmä palauttaa kaikki resurssiin liittyvät merkintälajit. Toinen argumentti määrittää, tarkastellaanko resurssin aliobjekteja.  depth-argumentti hallitsee haun syvyyttä, kun tarkastelet resurssin aliobjekteja.Syvyys voi olla DEPTH_ZERO (vain resurssi), DEPTH_ONE (resurssi ja kaikki sen suorat jälkeläiset) tai DEPTH_INFINITE (resurssi ja kaikki sen suorat ja epäsuorat jälkeläiset).

Merkinnän pysyvyys

Ympäristön tavalliset merkinnät (task, problem ja bookmark) ovat pysyviä. Tämä tarkoittaa, että niiden tila tallentuu työympäristön lopetuksessa ja aloituksessa. Pysyvän lajin merkinnöistä voi kuitenkin tehdä valikoidusti väliaikaisia määrittämällä varatun määritteen transient arvoksi true.

Lisäosien esittelemät uudet merkintälajit eivät ole pysyviä, jos niitä ei esitellä sellaisiksi.

Ympäristön laajennus uusilla merkintälajeilla

Lisäosat voivat esitellä omat merkintälajinsa org.eclipse.core.resources.markers-laajennuspisteen avulla. Ympäristö esittelee ongelmien, tehtävien ja kirjanmerkkien vakiomerkintälajit resurssien lisäosan merkinnässä.

   <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>

Uudet merkintälajit johdetaan aiemmista moniperiytymisen avulla. Uudet merkintälajit perivät kaikki ylityyppiensä määritteet ja lisäävät uudet määritteet, jotka on määritetty osana esittelyä. Ne perivät väliaikaisesti määritteet ylityyppiensä ylityypeiltä. Seuraava merkintä määrittää uudenlaisen merkinnän kuvitteelliseen com.example.markers-lisäosaan.

   <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>

Huomaa, että laji org.eclipse.core.resources.problemmarker on todellisuudessa yksi ennalta määritetyistä lajeista (eli IMarker.PROBLEM). 

Merkinnän ylityypin ainoa ominaisuus, joka ei periydy, on persistence-määrite.  Sen oletusarvo on false, joten jokaisen pysyväksi tarkoitetun merkintälajin on määritettävä <persistent value="true"/>.

Kun uusi merkintälaji on esitelty lisäosan manifest-tiedostossa, voit luoda com.example.markers.myproblem-merkintälajin ilmentymiä ja asettaa tai hakea vapaasti myAttribute-määritteen.

Uusia määritteitä esittelemällä voit liittää tietoja merkintöihin, joita aiot käyttää muualla (näkymissä ja muokkausohjelmissa). Tietyn lajisilla merkinnöillä ei tarvitse olla arvoja kaikille esitellyille määritteille. Määritteiden esittelyn tarkoitus on pikemminkin ratkaista nimeämiskäytäntöjen ongelmia (jotta kaikki käyttävät sanaa "message" puhuessaan merkinnän kuvauksesta) kuin rajoittaa sisältöä.

   public IMarker createMyMarker(IResource resource) {
   try {
         IMarker marker = resource.createMarker("com.example.markers.myproblem");
         marker.setAttribute("myAttribute", "MYVALUE");
         return marker;
  } catch (CoreException e) {
         // On käsiteltävä tapaukset, joissa määritearvo on hylätty
      }
   }

Voit tehdä omia merkintälajejasi koskevan kyselyn samalla tavoin kuin ympäristön merkintälajeja koskevan kyselyn. Seuraava metodi etsii kaikki mymarker-merkinnät, jotka liittyvät tiettyyn kohderesurssiin, sekä kaikki jälkeläiset. Huomaa, että se etsii myös kaikki myproblems-merkinnät, koska argumentille includeSubtypes välitetään arvo true.

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