Vi ved, at plugins kan definere specialiserede filtyper og levere editorer, der stiller specialiserede redigeringsfunktioner for disse filtyper til rådighed. Mens en ressource redigeres (eller bygges), har en plugin muligvis brug for at kode ressourcer for at kommunikere problemer eller andre oplysninger til brugeren. Mekanismen til ressourcemarkering bruges til at administrere denne type oplysninger.
En markering ligner en gul 'post-it', der er påsat en ressource. På markeringen kan du registrere oplysninger om et problem, f.eks. placering, niveau, eller en opgave, der skal udføres. Eller du kan blot registrere en placering til en markering som et bogmærke.
Brugere kan hurtigt springe til den markerede placering i en ressource. Arbejdsbænkens grænseflade understøtter præsentation af bogmærker, breakpointer, opgaver og problemer sammen med editoren. Disse markeringer kan også vises som elementer i oversigter, f.eks. som opgaver eller bogmærkeoversigter.
Platformressource-API'et definerer metoder for oprettelse af markeringer, angivelse af markeringsværdier og udvidelse af platformen med nye markeringstyper. Det er platformen, der administrerer markeringer, og det er plugins, der styrer deres oprettelse, fjernelse og attributværdier.
Markeringer skal være små letvægtsobjekter. Der kan være hundredvis endda tusindvis af markeringer i et enkelt projekt. Java-compileren bruger f.eks. en markering til at markere hvert problem, der registreres i kildekoden.
Platformen kasserer de markeringer, der er knyttet til ressourcer, som er slettet, men plugins er ansvarlige for at fjerne deres overflødige markeringer, når de ikke længere gælder for en ressource, der stadig findes.
Manipulation af en markering ligner markering af en ressource. Markeringer er referenceobjekter. Du kan hente en markeringsreference fra en ressource, men du ved ikke, om den faktisk findes, før du bruger protokollen exists() eller prøver på at arbejde med den på anden vis. Når du har konstateret, at en markering findes, kan du forespørge på navngivne attributter, som muligvis er blevet knyttet til den.
Markeringer ejes og styres af den platform, som sørger for, at markeringerne er vedvarende, og for at underrette lyttere, når markeringer tilføjes, slettes eller ændres. Plugins er ansvarlige for oprettelse af nødvendige markeringer, ændring af deres attributter og fjernelse af dem, når der ikke længere er behov for dem.
Markeringer oprettes ikke direkte vha. en konstruktør. De oprettes ved, at der anvendes en fabriksmetode IResource.createMarker()) på den tilknyttede ressource.
IMarker marker = file.createMarker(IMarker.TASK);
For at oprette en markering med globalt omfang (som ikke er tilknyttet nogen specifik ressource) skal du bruge arbejdsområdets rod (IWorkspace.getRoot()) som ressourcen.
Koden for sletning af en markering er ganske enkel.
try { marker.delete(); } catch (CoreException e) { // Der er opstået en fejl }
Når en markering slettes, bliver dets markeringsobjekt (reference) "forældet." Plugins skal bruge protokollen IMarker.exists() til at sikre, at et markeringsobjekt stadig er gyldigt.
Markeringer kan slettes batchvis. Du beder en ressource om at slette sine egne markeringer. Denne metode er nyttig, hvis du skal fjerne mange markeringer på en gang, eller hvis referencerne eller id'erne for en markering ikke er tilgængelige.
int depth = IResource.DEPTH_INFINITE; try { resource.deleteMarkers(IMarker.PROBLEM, true, depth); } catch (CoreException e) { // Der er opstået en fejl }
Når du sletter en grupper markeringer, skal du angive, hvilken type markering du vil slette, f.eks. IMarker.PROBLEM, eller Null, hvis du vil slette alle markeringer. Det andet argument angiver, om du vil slette undertypemarkeringer. (Undertyper gennemgås under definition af markeringstyper). Argumentet depth styrer, hvor dybt sletningen skal udføres.
IWorkspace.deleteMarkers(IMarker []).
For en given markering kan du bede om at få oplyst dens tilknyttede ressource, dens id (entydig i forhold til den pågældende ressource) og dens type. Du kan også få adgang til yderligere oplysninger via generiske attributter.
Hver type markering har et bestemt sæt attributter, der defineres af den person, som opretter markeringstypen vha. navngivningsregler. Grænsefladen IMarker definerer et sæt konstanter, der indeholder standardattributnavne (og nogle af de forventede værdier) for platformens markeringstyper. Følgende metode manipulerer attributter vha. platformens konstanter.
IMarker marker = file.createMarker(IMarker.TASK); if (marker.exists()) { try { marker.setAttribute(IMarker.MESSAGE, "Eksempel på markeringsmeddelelse"); marker.setAttribute(IMarker.PRIORITY, IMarker.PRIORITY_HIGH); } catch (CoreException e) { // Du skal håndtere den situation, hvor markeringen ikke eksisterer længere } }
Attributter vedligeholdes generisk som navne/værdipar, hvor navnene er strenge, og en værdi kan være en hvilken som helst af de understøttede værdityper (boolesk, heltal, streng). Begrænsningen på værdityper tillader, at platformen kan levere markeringerne vedvarende.
Du kan forespørge på ressourcer efter deres markeringer og på markeringerne efter deres underordnede elementer. Du kan f.eks. forespørge med ubegrænset dybde på arbejdsområdets rod for at inkludere alle markeringerne i arbejdsområdet.
IMarker[] problems = null; int depth = IResource.DEPTH_INFINITE; try { problems = resource.findMarkers(IMarker.PROBLEM, true, depth); } catch (CoreException e) { // Der er opstået en fejl }
Det resultat, der returneres af findMarkers, afhænger af de angivne argumenter. I ovenstående stykke kode søges efter alle markeringer, der har typen PROBLEM, som vises for ressource, og alle dens direkte og indirekte underordnede elementer.
Hvis du angiver Null som markeringstype, vises alle de markeringstyper, der er knyttet til ressourcen. Det andet argument angiver, om du vil have ressourcens underordnede elementer vist. Argumentet depth styrer dybden af søgningen, når du undersøger ressourcens underordnede elementer. Dybden kan være DEPTH_ZERO (kun den angivne ressource), DEPTH_ONE (ressourcen og alle dens direkte underordnede elementer) eller DEPTH_INFINITE (ressourcen og alle dens direkte og indirekte underordnede elementer).
Platformens standardmarkeringer (opgave, problem og bogmærke) er persistent (vedvarende). Det betyder, at deres tilstand vil fortsat være gældende også ved lukning og genstart af arbejdsbænken. Men markeringer, der har typen persistent, kan individuelt gøres midlertidige, ved at du angiver true for den reserverede attribut transient.
Nye markeringstyper, der er erklæret af plugins, er ikke vedvarende, medmindre de er erklæret vedvarende.
Plugins kan erklære deres egen markeringstype vha. udvidelsespunktet org.eclipse.core.resources.markers.Standardmarkeringstyperne for problemer, opgaver og bogmærker erklæres af platformen i plugin'ens kode for ressourcer.
<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 markeringstyper afledes fra eksisterende typer vha. multi-overtagelse. Nye markeringstyper overtager alle attributterne fra deres supertyper og tilføjer nye attributter, der er defineret som en del af erklæringen. De overtager også midlertidigt attributter fra de typer, der er overordnet deres supertyper. Følgende kode definerer en ny slags markering i en hypotetisk 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>
Bemærk, at typen org.eclipse.core.resources.problemmarker faktisk er en af de foruddefinerede typer (IMarker.PROBLEM).
Det eneste, som ikke overtages fra en markerings supertype, er persistence-flaget. Standardværdien for persistence (vedvarende) er false. Så en markeringstype, der skal være vedvarende, skal angive <persistent value="true"/>.
Når du har erklæret den nye markeringstype i plugin-manifestfilen, kan du oprette forekomster af markeringstypen com.example.markers.myproblem og frit angive eller hente attributten myAttribute.
Når du erklærer nye attributter, kan du knytte data til de markeringer, du planlægger at bruge andetsteds (i oversigter og editorer). Markeringer af en bestemt type behøver ikke at have værdier for alle de erklærede attributter. Attributerklæringerne bruges hovedsageligt til løsning af problemer i forbindelse med navngivningsregler (alle benytter betegnelsen "message" for en markeringsbeskrivelse) og ikke så meget til begrænsning af indhold.
public IMarker createMyMarker(IResource resource) { try { IMarker marker = resource.createMarker("com.example.markers.myproblem"); marker.setAttribute("myAttribute", "MYVALUE"); return marker; } catch (CoreException e) { // Du skal håndtere de situationer, hvor attributværdien afvises } }
Du kan forespørge på dine egne markeringstyper på samme måde som på platformens markeringstyper. Metoden nedenfor finder alle mymarkers, der er knyttet til den givne målressource, og alle underordnede elementer. Bemærk, at dette også finder alle myproblems, da 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); }