Erőforrásjelzők

Tudjuk, hogy a bedolgozók megadhatnak speciális fájlkiterjesztéseket és kiegészítő-szerkesztőket, amelyek speciális szerkesztési funkciókat biztosítanak ezekhez a fájlokhoz. Az erőforrás-szerkesztés (vagy építés) során a bedolgozónak címkeerőforrásokra lehet szüksége a hiba- vagy egyéb információk felhasználó számára eljuttatásához.Az erőforrásjelzési mechanizmus kezeli ezeket az információkat.

A jelző úgy néz ki, mint egy öntapadós sárga cetli az erőforráshoz ragasztva. A jelzőn a problémával (például hely, fontosság) vagy a végrehajtandó feladattal kapcsolatos információk rögzíthetők. Vagy egyszerűen rögzítheti a jelző helyét könyvjelzőként. 

A felhasználók gyorsan a megjelölt helyre ugorhatnak az erőforrásban. A munkaterület UI támogatja a könyvjelzők, töréspontok, feladatok és problémák megjelenítését a szerkesztő oldala mentén.  Ezek a jelzők szintén megjeleníthetők nézetekként, mint például a feladatok vagy könyvjelzők nézet.

A platform-erőforrások API jelzők létrehozásához, jelzőértékek beállításához és a platform új jelzőtípusokkal kiterjesztéséhez ad meg metódusokat. Miközben a platform kezeli a jelzőket, ezek a bedolgozók, amelyek vezérlik a létrehozást, eltávolítást és az attribútumértékeket.

A jelzők lehetőleg kicsi, könnyűsúlyú objektumok legyenek. Egy projektben több száz, esetleg több ezer jelző is létezhet. A Java fordító például egy jelzőt használ a forráskódban talált probléma jelzése érdekében.

A platform eldobja a törölt erőforrásokhoz rendelt jelzőket, de a bedolgozók felelősek az elévült jelzők eltávolításáért, ha a továbbiakban nem érvényesek a létező erőforrásokra.

Jelzőműveletek

A jelző kezelése hasonlít az erőforrás kezeléséhez. A jelzők kezelik az objektumokat.  Az erőforrástól lekérhet egy jelzőkezelőt, de nem fogja tudni, hogy valójában létezik-e, amíg nem használja az exists() protokollt, vagy másképp meg nem próbálja kezelni azt.  Ha megállapította, hogy a jelző létezik, akkor lekérheti a hozzárendelt megnevezett attribútumokat.

A jelzőket a platform kezeli és birtokolja, amely foglalkozik a jelzők állandóvá tételével és értesíti a figyelőket a jelzők hozzáadásáról, törléséről vagy módosításáról. A bedolgozók felelősek a szükséges jelzők létrehozásáért, attribútumaik módosításáért és eltávolításukért, amennyiben a továbbiakban nincs rájuk szükség.

Jelzőlétrehozás

A jelzők nem kerülnek közvetlenül létrehozásra egy konstruktor segítségével. Egy gyár metódus (IResource.createMarker()) segítségével kerülnek létrehozásra a társított erőforráson.

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

A globális hatókörrel rendelkező jelző létrehozásához (nincs hozzárendelve adott erőforráshoz) erőforrásként használhatja a munkaterület-gyökeret (IWorkspace.getRoot()).

Jelzőtörlés

A jelző törlésének kódja egyszerű.

      try {
      marker.delete();
      } catch (CoreException e) {
      // Valami elromlott
   }

A jelző törlésekor a jelzőobjektum (kezelő) "elévültté" válik. A bedolgozóknak az IMarker.exists() protokollt kell használnia a jelzőobjektum érvényessé tétele érdekében.

A jelzők törölhetők kötegben megkérve az erőforrást arra, hogy törölje a jelzőket. Ez a metódus számos jelző egyidejű eltávolítása esetén hasznos, vagy ha az egyedi jelzőhivatkozások illetve azonosítók nem elérhetők.

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

Jelzőcsoportok törlésekor megadhat egy törlendő jelzőtípust, mint például az IMarker.PROBLEM, vagy üres értéket az összes jelző törléséhez. A második argumentum jelzi, hogy törölni kívánja-e az altípusjelzőket.  (Az altípusokat új jelzőtípusok létrehozásakor tekintjük meg.) A mélység argumentum szabályozza a törlés mélységét. 

A jelzőket az IWorkspace.deleteMarkers(IMarker []) segítségével is törölheti.

Jelzőattribútumok

Egy jelző megadásával lekérheti a hozzárendelt erőforrást, az azonosítót (egyedi ehhez az erőforráshoz viszonyítva) és a típusát. További információk az általános attribútumokon keresztül érhetők el.

Minden jelzőtípus rendelkezik adott attribútumhalmazzal, amelyet a jelzőtípus létrehozója ad meg az elnevezési megállapodások alkalmazásával.   Az IMarker felület megad egy konstanshalmazt, amely tartalmazza a szabványos attribútumneveket (és az elvárt értékek egy részét) a platformjelző-típusokhoz. Az alábbi metódus a platformkonstansok segítségével kezeli az attribútumokat.

   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) {
         // Kezelni kell az esetet, amelyben a jelző már nem létezik  }
   }

Az attribútumok általánosan név/érték párokként kerülnek kezelésre, ahol a nevek karaktersorozatok és az érték a támogatott értéktípusok bármelyike lehet (boolean, integer, string). Az értéktípusok korlátozásai segítségével a platform gyorsan és egyszerűen állandóvá teheti a jelzőket.

Jelzők lekérése

Az erőforrások lekérhetők a jelzőikhez és a leszármazottjuk jelzőihez. Ha például a munkaterület gyökeret végtelen mélységgel kéri le, akkor a munkaterület összes jelzője figyelembe lesz véve.

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

A findMarkers által visszaadott eredmény az átadott argumentumoktól függ. A fenti részletben az összes PROBLEM típusú jelzőt megkeressük, amely megjelenik az erőforráson és a közvetlen vagy közvetett leszármazottján. 

Ha üres értéket ad át jelzőtípusként, akkor megkapja az erőforráshoz rendelt összes jelzőtípust. A második argumentum megadja, hogy meg kívánja-e jeleníteni az erőforrás leszármazottjait. A mélység argumentum szabályozza a keresés mélységét az erőforrás leszármazottjainak megtekintésekor. A mélység lehet DEPTH_ZERO (csak az adott erőforrás), DEPTH_ONE (az erőforrás és az összes közvetlen leszármazott) vagy DEPTH_INFINITE (az erőforrás, illetve az összes közvetlen és közvetett leszármazott).

Jelzőállandóság

A platform szabványos jelzői (feladat, probléma és könyvjelző) állandóak. Ez az jelenti, hogy az állapotuk mentésre kerül a munkaállomás leállítása és indítása során. Az állandó jelzők ideiglenessé tehetők a fenntartott transient attribútum igazra állatásával.

A bedolgozó által deklarált új jelzőtípusok nem állandóak, hacsak nem úgy kerülnek deklarálásra.

Platform kiterjesztése új jelzőtípusokkal

A bedolgozók az org.eclipse.core.resources.markers kiterjesztési pont segítségével deklarálhatnak saját jelzőtípusokat. A problémák, feladatok és könyvjelzők szabványos jelzőtípusait a platform deklarálja az erőforrások bedolgozó jelzőjében.

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

Az új jelzőtípusok a meglévőkből származtathatók többszörös öröklés segítségével. Az új jelzőtípusok öröklik az összes attribútumot a szupertípusoktól és hozzáadják a deklaráció részeként megadott új attribútumokat. Tranzitív módon öröklik az attribútumokat a szupettípusok szupertípusaitól. Az alábbi jelző egy új jelzőtípust ad meg a com.example.markers elképzelt termékben.

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

Ne feledje el, hogy az org.eclipse.core.resources.problemmarker típus valójában az előre meghatározott típusok egyike (IMarker.PROBLEM). 

Az egyetlen jellemzője a jelző szupertípusnak, hogy nem örökli az állandóság jelzőt.  Az állandóság alapértelmezett értéke hamis, így azon jelzőtípusoknak, amelyeknek állandónak kell lennie, a <persistent value="true"/> értéket kell megadni.

Az új jelzőtípus bedolgozó leírófájlban megadása után létrehozhatja a com.example.markers.myproblem jelzőtípus példányait és szabadon beállíthatja vagy lekérheti a myAttribute attribútumot.

Új attribútumok deklarálásával adatokat rendelhet hozzá a jelzőkhöz, amelyeket máshol kíván használni (a nézetekben és szerkesztőkben). Egy adott típus jelzői nem rendelkeznek értékekkel az összes deklarált attribútumhoz. Az attribútumdeklaráció inkább az elnevezési megállapodások problémáinak megoldása (így mindenki az "üzenetet" használja a jelző leírásáról beszélgetéshez), mint a tartalom megszorítása.

   public IMarker createMyMarker(IResource resource) {
      try {
         IMarker marker = resource.createMarker("com.example.markers.myproblem");
         marker.setAttribute("myAttribute", "MYVALUE");
         return marker;
      } catch (CoreException e) {
         // Kezelni kell az eseteket, amelyben az attribútumérték visszautasításra kerül
      }
   }

A saját jelzőtípusok ugyanúgy kérhetők le, mint a platform-jelzőtípusok.  Az alábbi metódus kikeresi az adott célerőforráshoz rendelt összes mymarkers elemet és az összes leszármazottját. Ne feledje el, hogy az összes myproblems is megjelenik, mivel az includeSubtypes argumentum igaz értéket kapott.

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