Reportar progresso

Os trabalhos de longa execução (os que duram mais de um segundo) devem reportar progresso ao IProgressMonitor que é transmitido ao método run do trabalho. A vista de progresso da área de trabalho mostra todas as mensagens de progresso e unidades de trabalho concluído atribuídas a este supervisor.

O supervisor de progresso indicado também deve ser usado para verificar pedidos de cancelamento realizados na vista de progresso. Quando um utilizador (ou plug-in a utilizar a API do trabalho) tenta cancelar um um trabalho, o método isCanceled() do IProgressMonitor devolve true. É da responsabilidade do trabalho verificar frequentemente o estado de cancelamento de um trabalho e reagir a um cancelamento saindo do método run tão breve quanto possível assim que detectar um cancelamento. O seguinte método run reporta progresso e reage a cancelamentos de trabalhos:

            public IStatus run(IProgressMonitor monitor) {
      final int ticks = 6000;
      monitor.beginTask("A realizar trabalho", ticks);
  try {
         for (int i = 0; i < ticks; i++) {
            if (monitor.isCanceled())
               return Status.CANCEL_STATUS;
            monitor.subTask("A processar visto #" + i);
            //... realizar trabalho ...
            monitor.worked(1);
         }
      } finally {
         monitor.done();
      }
      return Status.OK_STATUS;
}

O método beginTask é utilizado para denominar a tarefa na vista de progresso correspondente e estabelecer o volume total de trabalho a realizar de modo a que a vista possa calcular progresso. As mensagens subTask aparecem como descendente na árvore de progresso à medida que o trabalho é realizado. A vista de progresso irá calcular e apresentar uma percentagem de conclusão baseada no volume de trabalho reportado nas chamadas worked.

Supervisores de progresso e a UI

Como podemos ver, a classe IProgressMonitor está concebida com suporte de UI correspondente em mente. O plug-in da UI da plataforma faculta suporte para que a área de trabalho possa mostrar progresso para trabalhos em execução. Poderá configurar os seus trabalhos com isto em mente, de modo a poder controlar a respectiva apresentação.

Consulte Suporte de Simultaneidade de Área de Trabalho para uma abordagem detalhada das APIs disponíveis para mostrar progresso de trabalhos.

Trabalhos de sistema

E se o trabalho for um detalhe de implementação de baixo nível que não quer mostrar aos utilizadores? Poderá sinalizar o trabalho como trabalho de sistema. Um trabalho de sistema é tal e qual outro trabalho qualquer, salvo que o suporte de UI correspondente não configura uma vista de progresso nem mostra outras #affordances associadas à execução de um trabalho. Se o trabalho não for directamente iniciado por um utilizador nem tarefa periódica que possa ser configurada pelo utilizador, deverá ser mesmo um trabalho de sistema. O protocolo para definir um trabalho de sistema é simples:

   class TrivialJob extends Job {
      public TrivialJob() {
         super("Trabalho Trivial");
         setSystem(true);
      }
      ...
   }

A chamada setSystem deve ser feita antes de o trabalho ser agendado. Será desencadeada uma excepção se tentar esta chamada num trabalho que esteja em espera, dormente ou em execução.

Trabalhos de utilizador

Se o trabalho for uma operação de longa execução iniciada por um utilizador, deverá sinalizar o trabalho como trabalho de utilizador. Um trabalho de utilizador aparece num diálogo de progresso modal que faculta um botão para mover o diálogo para segundo plano. A área de trabalho define uma preferência de utilizador que controla se estes diálogos são ou não modais. Ao definir o seu trabalho como trabalho de utilizador, o feedback de progresso irá automaticamente adaptar-se à preferência de utilizador para visualização de progresso. O protocolo para definir um trabalho de utilizador é semelhante:

   class TrivialJob extends Job {
      public TrivialJob() {
         super("Trabalho Trivial");
         setUser(true);
      }
      ...
   }

A chamada setUser também deve ser feita antes de o trabalho ser agendado.

Grupos de progresso

Os grupos de progresso são outro mecanismo que pode ser usado para influenciar a maneira de mostrar um trabalho na UI. Quando for mais apropriado mostrar o progresso agregado de vários trabalhos relacionados na UI, pode ser criado um IProgressMonitor especial que represente um grupo de trabalhos relacionados. Este supervisor é criado com o protocolo IJobManager. A porção de código seguinte mostra como criar um grupo de progresso e associá-lo a um trabalho.

   ...
   IJobManager jobMan = Platform.getJobManager();
   oMeuGrupo = jobMan.createProgressGroup();
   job.setProgressGroup(oMeuGrupo, 600);  // especificar as unidades de trabalho que o trabalho deve mostrar.
   job.schedule()
   ...

A função de grupos permite aos plug-ins dividir tarefas em vários trabalhos se necessário, mas reporta-os ao utilizador como se de uma única tarefa se tratasse. O supervisor de grupos de progresso trata dos detalhes de calcular a percentagem de conclusão relativa a todos os trabalhos no grupo.

É necessário colocar o trabalho no grupo de progresso antes de o agendadar. Quando um trabalho terminar de executar, perde-se a a respectiva referência ao grupo de progresso. Se o trabalho tiver de ser novamente agendado, deverá ser definido outra vez dentro do grupo antes de ser agendado.