Jobs die lang actief zijn (meer dan een seconde) moeten hun voortgang melden aan de IProgressMonitor die wordt doorgegeven aan de methode run van de job. De workbenchvoortgangsview geeft alle voortgangsberichten en eenheden van voltooid werk weer die aan de monitor ter beschikking gesteld worden.
De verstrekte voortgangsmonitor moet ook worden gebruikt om te controleren op annuleringsverzoeken uit de voorgangsview. Als een gebruiker (of een plugin die een job-API gebruikt) probeert een job te annuleren, retourneert de IProgressMonitor-methode isCanceled() de waarde true. De job is ervoor verantwoordelijkheid om regelmatig de annuleringsstatus te controleren en op een annulering te reageren door de methode run af te sluiten. De volgende run-methode meldt voortgang en reageert op jobannuleringen:
public IStatus run(IProgressMonitor monitor) { final int ticks = 6000; monitor.beginTask("Wat werk doen", ticks); try { for (int i = 0; i < ticks; i++) { if (monitor.isCanceled()) return Status.CANCEL_STATUS; monitor.subTask("Processing tick #" + i); //... wat werk doen ... monitor.worked(1); } } finally { monitor.done(); } return Status.OK_STATUS;
}
De methode beginTask wordt gebruikt om de taak in de corresponderende voortgangsview een naam te geven en om de totale hoeveelheid werk te berekenen. Op basis hiervan kan de view de voortgang berekenen. De subTask-berichten worden na het werk als onderliggend item afgebeeld in de voortgangsstructuurberichten. De voortgangsview berekent het voltooide percentage op basis van de hoeveelheid werk die is gemeld in de worked-aanroepen en geeft dit weer.
Zoals u ziet, is de klasse IProgressMonitor ontworpen met corresponderende ondersteuning voor een gebruikersinterface in gedachten. De gebruikersinterfaceplugin van het platform biedt ondersteuning, zodat de workbench de voortgang van actieve jobs kan weergeven. U kunt hier bij het instellen van uw jobs rekening mee houden en bepalen hoe ze worden weergegeven.
Zie Ondersteuning voor gemeenschappelijk gebruik van de workbench voor een gedetailleerde bespreking van de beschikbare API's voor weergave van de jobvoortgang.
Wat moet u doen als uw job een implementatiedetail op laag niveau is dat u niet voor gebruikers wilt weergeven? U kunt de job met een vlag aanduiden als systeemjob. Een systeemtaak lijkt op andere taken, maar de corresponderende ondersteuning voor de gebruikersinterface stelt geen voortgangsview in en beeldt geen andere functies van de gebruikersinterface voor het uitvoeren van een taak af. Als uw taak niet direct door een gebruiker is geïnitialiseerd of als het geen periodieke job is die door een gebruiker kan worden geconfigureerd, moet de job een systeemjob zijn. Het protocol voor het instellen van een systeemjob is eenvoudig:
class TrivialJob extends Job { public TrivialJob() { super("Trivial Job"); setSystem(true); } ... }
De aanroep van setSystem moet worden gedaan voordat de job is gepland. Er wordt een uitzondering gegenereerd als u deze aanroep probeert voor een momenteel wachtende, niet-actieve of uitgevoerde job.
Als uw job een langdurige bewerking is die door een gebruiker wordt geïnitialiseerd, moet u de job met een vlag markeren als gebruikersjob. Een gebruikersjob wordt in een modaal voortgangsvenster weergegeven. Dit venster bevat een knop om het naar de achtergrond te verplaatsen. De workbench definieert een gebruikersvoorkeur die bepaalt of deze dialoogvensters modaal zijn. Door de taak te definiëren als gebruikerstaak past de voortgangsweergave zich automatisch aan de gebruikersvoorkeuren aan. Het protocol voor het instellen van een gebruikersjob lijkt er veel op:
class TrivialJob extends Job { public TrivialJob() { super("Trivial Job"); setUser(true); } ... }
De aanroep van setUser moet worden gedaan voordat de job is gepland.
Voortgangsgroepen zijn een ander mechanisme voor het beïnvloeden van de manier waarop een job wordt afgebeeld in de gebruikersinterface. Als het gepaster is om een een verzameling voortgangsinformatie over verschillende jobs af te beelden in de gebruikersinterface, kunt u een speciale IProgressMonitor maken die als groep gerelateerde jobs fungeert. U maakt deze monitor met het IJobManager-protocol. In het volgende codefragment ziet u hoe u een voortgangsgroep maakt en deze aan een job koppelt.
... IJobManager jobMan = Platform.getJobManager(); myGroup = jobMan.createProgressGroup(); job.setProgressGroup(myGroup, 600); // werkeenheden opgeven die de job moet weetgeven. job.schedule() ...
Met de groepsfunctie kunnen plugins taken opdelen in meerdere jobs en deze aan de gebruiker melden alsof het één taak betreft. De voortgangsgroepsmonitor berekent het voltooide percentage aan de hand van alle jobs in de groep.
Een job moet in een voortgangsgroep worden geplaatst voordat deze wordt gepland. Nadat het uitvoeren van de job is voltooid, wordt de verwijzing naar de voortgangsgroep verwijderd. Als de job opnieuw gepland moet worden, moet deze eerst opnieuw in de groep worden geplaatst.