Vi vet at plugin-moduler kan definere spesialfiltyper og oppgi redigeringsprogrammer med spesialfunksjoner for redigering av filtypene. I løpet av redigeringsprosessen (eller byggingen), kan det være at en plugin-modul må merke ressurser for å gi brukeren beskjed om problemer eller formidle annen informasjon.Ressursmerkingen brukes til å styre slik informasjon.
Et merke er som en gul lapp som er festet til en ressurs. Du kan registrere informasjon i merket, enten om et problem (for eksempel plassering og alvorsgrad) eller om en oppgave som skal utføres. Du kan også registrere en plassering av et merke som et bokmerke.
Brukere kan raskt gå til denne plasseringen i en ressurs. Arbeidsbenkgrensesnittet støtter presentasjonen av bokmerker, avbruddspunkter, oppgaver og problemer på siden av redigeringsprogrammet. Disse merkene kan også vises som elementer i visninger, for eksempel oppgaver eller bokmerkevisning.
Plattformressursenes programmeringsgrensesnitt definerer metoder for opprettelse av merker, definering av merkeverdier og utvidelse av plattformen med nye merketyper. Plattformen håndterer merker, mens plugin-modulene styrer opprettelse, fjerning og attributtverdier.
Det er meningen at merkene skal være små enkle objekter. Det kan finnes hundre- eller tusenvis av merker i ett og samme prosjekt. Java-kompilatoren bruker for eksempel merker til å flagge problemer i kildekoden.
Plattformen fjerner merker som er tilknyttet slettede ressurser, mens plugin-moduler fjerner gamle merker som ikke lenger kan brukes på en ressurs som fortsatt eksisterer.
Manipulering av merker likner på manipulering av ressurser. Merker er referanseobjekter. Du kan hente en merkereferanse fra en ressurs, men du må bruke protokollen exists() eller prøve å manipulere på annen måte før du faktisk vet om det finnes. Når det er på det rene at merket eksisterer, kan du opprette en spørring etter navngitte attributter som kan være tilordnet merket.
Merker eies og styres av plattformen, som gjør dem permanente og varsler lyttere etter hvert som de legges til, slettes eller endres. Plugin-moduler kan opprette merker når dette er nødvendig, endre attributtene og fjerne dem når det ikke lenger er behov for dem.
Merker opprettes direkte ved hjelp av en konstruktør. De opprettes ved hjelp av factory-metoden IResource.createMarker() i den tilknyttede ressursen.
IMarker marker = file.createMarker(IMarker.TASK);
Hvis du vil opprette et merke med globalt omfang (som ikke er tilknyttet noen spesifikk ressurs), kan du bruke arbeidsområderoten IWorkspace.getRoot() som ressurs.
Koden for sletting av merker er enkel.
try { marker.delete(); } catch (CoreException e) { // Something went wrong }
Når et merke slettes, blir merkeobjektet (referansen) "foreldet." Plugin-modulene bruker protokollen IMarker.exists() til å kontrollere at et merkeobjekt fortsatt er gyldig.
Merker kan slettes i en satsvis kjøring ved å be en ressurs om å slette merkene. Dette er nyttig hvis det skal fjernes mange merker på en gang eller hvis enkelte merkereferanser eller -IDer ikke er tilgjengelige.
int depth = IResource.DEPTH_INFINITE; try { resource.deleteMarkers(IMarker.PROBLEM, true, depth); } catch (CoreException e) { // something went wrong }
Hvis du sletter grupper av merker, angir du hvilken merketype som skal slettes, for eksempel IMarker.PROBLEM eller null for å slette alle merker. Det andre argumentet angir om du vil slette subtypemerker. (Vi kommer tilbake til subtyper når vi skal definere nye merketyper.) Argumentet depth angir hvor omfattende slettingen skal være.
Du kan også slette merker ved hjelp av IWorkspace.deleteMarkers(IMarker []).
Hvis du har et merke, kan du be om å få oppgitt den tilknyttede ressursen, IDen (unik i forhold til ressursen) og typen. Du får også tilgang til ytterligere informasjon via generiske attributter.
Hver merketype har et bestemt sett med attributter som den som oppretter merketypen, definerer ved hjelp av navngivningsregler. IMarker-grensesnittet definerer et sett med konstanter som inneholder standard attributtnavn (og noen av de forventede verdiene) for plattformens merketyper. Metoden nedenfor manipulerer attributter ved hjelp av plattformkonstanter.
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) { // You need to handle the case where the marker no longer exists } }
Attributter vedlikeholdes generisk som navn/verdi-par, der navnet er strenger og en verdi kan være en hvilken som helst av de støttede verditypene (boolsk, heltall, streng). Begrensningene for verditype gjør det mulig for plattformen å raskt og enkelt holde fast ved merkene.
Det kan uføres spørringer i ressurser etter merker og merker for underordnede ressurser. Hvis du for eksempel utfører en spørring i arbeidsområderoten med ubegrenset omfang, blir alle merker i arbeidsområdet tatt i betraktning.
IMarker[] problems = null; int depth = IResource.DEPTH_INFINITE; try { problems = resource.findMarkers(IMarker.PROBLEM, true, depth); } catch (CoreException e) { // something went wrong }
Resultatet som returneres av findMarkers avhenger av hvilke argumenter som sendes. I snutten ovenfor ser vi etter alle merker av typen PROBLEM som vises i ressursen, og i alle de direkte og indirekte underliggende elementer.
Hvis du sender null som merketype, får du alle merketyper som er tilknyttet ressursen. Det andre argumentet angir om du vil se på de underordnede ressursene. depth-argumentet styrer omfanget av søkingen når du ser på de underordnede ressursene. Omfanget kan være DEPTH_ZERO (bare den oppgitte ressursen), DEPTH_ONE (ressursen og alle direkte underordnede ressurser) eller DEPTH_INFINITE (ressursen og alle direkte og indirekte underordnede elementer).
Plattformens standardmerker (oppgave, problem og bokmerke) er persistente. Dette betyr at tilstanden lagres mellom avslutning og oppstart av arbeidsbenken. Merker av en persistent type kan imidlertid selektivt gjøres midlertidige ved å sette det reserverte attributtet transient til "true".
Nye merketyper som er deklarert av plugin-moduler, er ikke persistente med mindre de deklareres slik.
Plugin-moduler kan deklarere sine egne merketyper ved hjelp av utvidelsespunktet org.eclipse.core.resources.markers. Standard merketyper for problemer, oppgaver og bokmerker er deklarert av plattformen i kodetypen til ressursenes plugin-modul.
<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>
Nye merketyper avledes av eksisterende typer ved hjelp av sammensatt arv. Nye merketyper arver alle attributtene fra supertypene og legger til eventuelle nye attributter som er definert som en del av deklarasjonen. De arver også transitivt attributter fra supertypene til supertypene. Følgende kodetype definerer en ny type merke i en hypotetisk plugin-modul for 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>
Merk at typen org.eclipse.core.resources.problemmarker er en av de forhåndsdefinerte typene (også kjent som IMarker.PROBLEM).
Det eneste som ikke arves fra supertypen, er persistensflagget. Standardverdien for persistens er "false". Hvis en merketype skal være persistent, må det derfor angis <persistent value="true"/>.
Etter at den nye merketypen er deklarert i plugin-manifestfilen, kan du opprette forekomster av merketypen com.example.markers.myproblem og fritt definere eller hente attributtet myAttribute.
Ved å deklarere nye attributter kan du knytte data til merker som du skal bruke andre steder (i visningene og redigeringsprogrammene). Merker av en bestemt type trenger ikke verdier for alle de deklarerte attributtene. Attributtdeklarasjonene skal i hovedsak løse problemer med navngivningsregler (derfor bruker alle "message" for beskrivelsen av et merke) og ikke begrense innholdet.
public IMarker createMyMarker(IResource resource) { try { IMarker marker = resource.createMarker("com.example.markers.myproblem"); marker.setAttribute("myAttribute", "MYVALUE"); return marker; } catch (CoreException e) { // You need to handle the cases where attribute value is rejected } }
Du kan utføre spørringer etter dine egne merketyper på samme måte som du utfører spørringer etter plattformens merketyper. Metoden nedenfor finner alle mymarkers som er tilknyttet den gitte målressursen og alle underordnede elementer. Merk at den også finner alle myproblems, siden "true" sendes for argumentet includeSubtypes.
public IMarker[] findMyMarkers(IResource target) { String type = "com.example.markers.mymarker"; IMarker[] markers = target.findMarkers(type, true, IResource.DEPTH_INFINITE); }