tecgraf.javautils.gui
Class Task<R>

java.lang.Object
  tecgraf.javautils.gui.Task<R>

Type Parameters:

R - A classe do resultado da tarefa.

All Implemented Interfaces:

Runnable

public abstract class Task<R>
extends Object
implements Runnable

A classe Task modela uma tarefa possivelmente demorada executada no cliente. Uma thread é criada para a execução da tarefa, para que eventos de interface (como redesenho) possam ser atendidos. As interações de teclado e mouse, contudo, são bloqueadas. Caso a duração da tarefa ultrapasse um valor limite configurável, um diálogo modal contendo uma barra de progresso será exibido. Este diálogo será fechado automaticamente ao final da tarefa. Após um intervalo de valor configurável, um botão para fechamento do diálogo é oferecido ao usuário. O texto do botão (Fechar ou Cancelar) é também configurável, pois depende do tipo de tarefa, e do efeito de seu fechamento. Essa classe permite aninhamento. Isto é, se dentro do método performTask uma outra tarefa for criada e executada, o retorno visual para seu acompanhamento é dado na mesma janela da tarefa anterior, evitando que múltiplas janelas de acompanhamento sejam abertas. É importante notar que tarefas aninhadas devem, obrigatoriamente, usar os métodos beforeTaskUI e afterTaskUI para qualquer código que atue sobre a interface gráfica.

Author:

Tecgraf/PUC-Rio

Field Summary

static int	CANCEL_BUTTON Tipo de texto do cancelamento.
static int	CLOSE_BUTTON Tipo de texto de fechamento.
static int	DEFAULT_CANCEL_DELAY Tempo padrão para cancelamento.
protected Window	parentWindow Janela a partir da qual a tarefa é comandada.
protected JProgressBar	progressBar Barra de progresso.
protected JDialog	progressDialog Diálogo de progresso.
protected String	taskTitle Título da tarefa.
protected JTextPane	textPane Texto contendo mensagem, passo e tempos.

Constructor Summary

protected	Task() Cria uma task com bloqueio de janelas Dialog.ModalityType.APPLICATION_MODAL.
protected	Task(Dialog.ModalityType modality) Cria uma task.

Method Summary

protected void	afterTaskUI() Caso alguma manipulação da interface seja necessária após da execução da tarefa (através de performTask), ela deve ser realizada neste método.
protected void	beforeTaskUI() Caso alguma manipulação da interface seja necessária antes da execução da tarefa (através de performTask), ela deve ser realizada neste método.
protected void	cancelTask() Cancela a tarefa, em consequência do acionamento do botão de cancelamento.
boolean	execute(Window window, String title, String description) Sobrecarga de execute assumindo o tempo padrão para habilitar o botão de fechamento, o texto padrão (Fechar) para esse botão, que não é possível determinar a taxa de progresso, que não serão exibidos os passos e que não há imagem a ser exibida no diálogo de progresso.
boolean	execute(Window window, String title, String description, boolean showProgress, boolean showSteps) Sobrecarga de execute assumindo o tempo padrão para habilitar o botão de fechamento, o texto padrão (Fechar) para esse botão e que não há imagem a ser exibida no diálogo de progresso.
boolean	execute(Window window, String title, String description, ImageIcon icon) Sobrecarga de execute assumindo o tempo padrão para habilitar o botão de fechamento, o texto padrão (Fechar) para esse botão, que não é possível determinar a taxa de progresso e que não serão exibidos os passos.
boolean	execute(Window window, String title, String description, int cancelDelayInSecs, int cancelButtonType) Sobrecarga de execute assumindo que não é possível determinar a taxa de progresso, que não serão exibidos os passos e que não há imagem a ser exibida no diálogo de progresso.
boolean	execute(Window window, String title, String description, int cancelDelayInSecs, int cancelButtonType, boolean showProgress, boolean showSteps) Sobrecarga de execute assumindo que não há imagem a ser exibida no diálogo de progresso.
boolean	execute(Window window, String title, String description, int cancelDelayInSecs, int cancelButtonType, boolean showProgress, boolean showSteps, ImageIcon icon) Inicia a execução da tarefa.
void	executeNonBlocking(Window window, String title, String description) Inicia a execução da tarefa não bloqueante.
protected String[]	getAdditionalInfo()
protected int	getCancelDelaySecs() Consulta do tempo (em segundos) para aparecimento do botão de cancelamento após a task entrar.
protected Window	getDefaultParentWindow() Obtém a janela padrão de referência.
Exception	getError() Obtém o erro detetado durante a execução da tarefa.
int	getProgressDialogDelay() Tempo de espera para exibição do diálogo
R	getResult() Obtém o resultado da tarefa executada.
boolean	getStatus() Obtém o status da tarefa executada.
String	getTaskMessage()
protected void	handleError(Exception exception) Tratamento de erros específico para cada tipo de tarefa.
protected abstract void	performTask() Tarefa a ser executada.
void	run() Execução da tarefa.
void	setProgressDialogDelay(int progressDialogDelay) Configura tempo de espera para exibição do diálogo
void	setProgressDialogEnabled(boolean b) Desabilita exibição do diálogo de progresso durante execução da tarefa.
void	setProgressStatus(int percentage) Atualiza a barra de progresso.
protected void	setResult(R result) Armazena o resultado da tarefa executada, para obtenção posterior.
void	setStepText(String step) Atualiza o texto do passo corrente.
void	setUnknownStatus() Atualiza a barra de progresso para desconhecido.
boolean	wasCancelled() Verifica se a tarefa foi cancelada pelo usuário.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CANCEL_DELAY

public static final int DEFAULT_CANCEL_DELAY

Tempo padrão para cancelamento.

See Also:

Constant Field Values

CANCEL_BUTTON

public static final int CANCEL_BUTTON

Tipo de texto do cancelamento.

See Also:

Constant Field Values

CLOSE_BUTTON

public static final int CLOSE_BUTTON

Tipo de texto de fechamento.

See Also:

Constant Field Values

parentWindow

protected Window parentWindow

Janela a partir da qual a tarefa é comandada.

progressDialog

protected JDialog progressDialog

Diálogo de progresso.

textPane

protected JTextPane textPane

Texto contendo mensagem, passo e tempos.

progressBar

protected JProgressBar progressBar

Barra de progresso.

taskTitle

protected String taskTitle

Título da tarefa.

Constructor Detail

Task

protected Task()

Cria uma task com bloqueio de janelas Dialog.ModalityType.APPLICATION_MODAL.

Task

protected Task(Dialog.ModalityType modality)

Cria uma task.

Parameters:

modality - tipo de bloqueio das janelas

Method Detail

beforeTaskUI

protected void beforeTaskUI()

Caso alguma manipulação da interface seja necessária antes da execução da tarefa (através de performTask), ela deve ser realizada neste método. Seu conteúdo é executado na EDT e, após seu término, a performTask é executada em uma thread própria.

performTask

protected abstract void performTask()
                             throws Exception

Tarefa a ser executada. Esse método deve ser implementado para executar a tarefa.

Throws:

Exception - quando a ocorrência de um erro (representado pela exceção) impediu a realização da tarefa

afterTaskUI

protected void afterTaskUI()

Caso alguma manipulação da interface seja necessária após da execução da tarefa (através de performTask), ela deve ser realizada neste método. Seu conteúdo é executado na EDT após o término de performTask.

run

public final void run()

Execução da tarefa. Especializações dessa classe (tarefas remotas, tarefas locais) realizam o tratamento adequado para erros que possam ocorrer durante a execução da tarefa.

Specified by:

run in interface Runnable

setResult

protected final void setResult(R result)

Armazena o resultado da tarefa executada, para obtenção posterior.

Parameters:

result - o resultado da tarefa

getResult

public final R getResult()

Obtém o resultado da tarefa executada.

Returns:

o valor de resultado da tarefa

getStatus

public final boolean getStatus()

Obtém o status da tarefa executada.

Returns:

true se a tarefa foi completada false se um erro (exceção) impediu a realização da tarefa

getError

public final Exception getError()

Obtém o erro detetado durante a execução da tarefa.

Returns:

exceção que representa o erro

wasCancelled

public boolean wasCancelled()

Verifica se a tarefa foi cancelada pelo usuário. Esse método pode ser periodicamente chamado por uma implementação de performTask que execute uma tarefa composta de uma sequência de passos, ou subtarefas.

Returns:

true se o botão de cancelamento foi acionado (cancelando a tarefa)

cancelTask

protected void cancelTask()

Cancela a tarefa, em consequência do acionamento do botão de cancelamento.

handleError

protected void handleError(Exception exception)

Tratamento de erros específico para cada tipo de tarefa. Esse tratamento é chamado na EDT. Essa implementação representa um tratamento mínimo, apenas para erros no cliente. Qualquer exceção lançada durante a execução do método performTask é repassada para este método para tratamento.

Parameters:

exception - - exceção que representa o erro durante execução da tarefa.

executeNonBlocking

public final void executeNonBlocking(Window window,
                                     String title,
                                     String description)

Inicia a execução da tarefa não bloqueante. Cria uma thread para executar a tarefa, e aguarda o seu término durante tempo especificado através do método

Parameters:

window - janela a partir da qual a tarefa foi comandada

title - título do diálogo de progresso

description - mensagem no diálogo de progresso

execute

public final boolean execute(Window window,
                             String title,
                             String description,
                             int cancelDelayInSecs,
                             int cancelButtonType,
                             boolean showProgress,
                             boolean showSteps,
                             ImageIcon icon)

Inicia a execução da tarefa. Cria uma thread para executar a tarefa, e aguarda o seu término durante tempo especificado através do método setProgressDialogDelay, ou o padrão de dois segundo. Se após esse tempo a tarefa ainda não tiver terminado, cria e exibe o diálogo modal de progresso. Se a tarefa for executada até o final (sem falhas sinalizadas por exceções), o valor true é retornado. O resultado da tarefa pode ser obtido através da chamada ao método getResult. Se uma exceção for lançada durante a execução da tarefa (incluindo seu cancelamento), o valor false é retornado, e nenhum resultado estará disponível. Antes deste retorno, o procedimento para tratamento específico de erros (definido nas subclasses) é invocado. O diálogo de progresso pode ser configurado de forma a exibir e atualizar os sucessivos passos de uma tarefa. Também pode ser configurado para permitir a atualização do percentual da tarefa já executado (quando o progresso puder ser determinado e for habilitado).

Parameters:

window - janela a partir da qual a tarefa foi comandada

title - título do diálogo de progresso

description - mensagem no diálogo de progresso

cancelDelayInSecs - intervalo em segundos para habilitar o botão de fechamento (se 0, é imediato)

cancelButtonType - determina o tipo do botão de cancelamento (CANCEL ou CLOSE)

showProgress - indica se a taxa de progresso pode ser determinada

showSteps - indica se exibe passo corrente

icon - imagem associada

Returns:

true se a tarefa foi executada até o final e há um resultado ou false se a ocorrência de um erro impediu a execução da tarefa e não há resultado associado.

getDefaultParentWindow

protected Window getDefaultParentWindow()

Obtém a janela padrão de referência.

Returns:

a janela padrão.

setStepText

public void setStepText(String step)

Atualiza o texto do passo corrente.

Parameters:

step - identificação do passo corrente

setProgressStatus

public void setProgressStatus(int percentage)

Atualiza a barra de progresso.

Parameters:

percentage - percentual da tarefa já completada

setUnknownStatus

public void setUnknownStatus()

Atualiza a barra de progresso para desconhecido.

getCancelDelaySecs

protected int getCancelDelaySecs()

Consulta do tempo (em segundos) para aparecimento do botão de cancelamento após a task entrar.

Returns:

o tempo

execute

public final boolean execute(Window window,
                             String title,
                             String description,
                             int cancelDelayInSecs,
                             int cancelButtonType,
                             boolean showProgress,
                             boolean showSteps)

Sobrecarga de execute assumindo que não há imagem a ser exibida no diálogo de progresso.

Parameters:

window - janela a partir da qual a tarefa foi comandada

title - título do diálogo de progresso

description - mensagem no diálogo de progresso

cancelDelayInSecs - intervalo em segundos para habilitar o botão de fechamento (se 0, é imediato)

cancelButtonType - determina o tipo do botão de cancelamento (CANCEL ou CLOSE)

showProgress - indica se a taxa de progresso pode ser determinada

showSteps - indica se exibe passo corrente

Returns:

true se a tarefa foi executada até o final e há um resultado ou false se a ocorrência de um erro impediu a execução da tarefa e não há resultado associado.

execute

public final boolean execute(Window window,
                             String title,
                             String description)

Sobrecarga de execute assumindo o tempo padrão para habilitar o botão de fechamento, o texto padrão (Fechar) para esse botão, que não é possível determinar a taxa de progresso, que não serão exibidos os passos e que não há imagem a ser exibida no diálogo de progresso.

Parameters:

window - janela a partir da qual a tarefa foi comandada

title - título do diálogo de progresso

description - mensagem no diálogo de progresso

Returns:

true se a tarefa foi executada até o final e há um resultado ou false se a ocorrência de um erro impediu a execução da tarefa e não há resultado associado.

execute

public final boolean execute(Window window,
                             String title,
                             String description,
                             ImageIcon icon)

Sobrecarga de execute assumindo o tempo padrão para habilitar o botão de fechamento, o texto padrão (Fechar) para esse botão, que não é possível determinar a taxa de progresso e que não serão exibidos os passos.

Parameters:

window - janela a partir da qual a tarefa foi comandada

title - título do diálogo de progresso

description - mensagem no diálogo de progresso

icon - imagem associada

Returns:

true se a tarefa foi executada até o final e há um resultado ou false se a ocorrência de um erro impediu a execução da tarefa e não há resultado associado.

execute

public final boolean execute(Window window,
                             String title,
                             String description,
                             boolean showProgress,
                             boolean showSteps)

Sobrecarga de execute assumindo o tempo padrão para habilitar o botão de fechamento, o texto padrão (Fechar) para esse botão e que não há imagem a ser exibida no diálogo de progresso.

Parameters:

window - janela a partir da qual a tarefa foi comandada

title - título do diálogo de progresso

description - mensagem no diálogo de progresso

showProgress - indica se a taxa de progresso pode ser determinada

showSteps - indica se exibe passo corrente

Returns:

true se a tarefa foi executada até o final e há um resultado ou false se a ocorrência de um erro impediu a execução da tarefa e não há resultado associado.

execute

public final boolean execute(Window window,
                             String title,
                             String description,
                             int cancelDelayInSecs,
                             int cancelButtonType)

Sobrecarga de execute assumindo que não é possível determinar a taxa de progresso, que não serão exibidos os passos e que não há imagem a ser exibida no diálogo de progresso.

Parameters:

window - janela a partir da qual a tarefa foi comandada

title - título do diálogo de progresso

description - mensagem no diálogo de progresso

cancelDelayInSecs - intervalo em segundos para habilitar o botão de fechamento (se 0, é imediato)

cancelButtonType - determina o tipo do botão de cancelamento (CANCEL ou CLOSE)

Returns:

true se a tarefa foi executada até o final e há um resultado ou false se a ocorrência de um erro impediu a execução da tarefa e não há resultado associado.

getProgressDialogDelay

public final int getProgressDialogDelay()

Tempo de espera para exibição do diálogo

Returns:

Tempo em segundos

setProgressDialogDelay

public final void setProgressDialogDelay(int progressDialogDelay)

Configura tempo de espera para exibição do diálogo

Parameters:

progressDialogDelay - tempo em segundos

setProgressDialogEnabled

public final void setProgressDialogEnabled(boolean b)

Desabilita exibição do diálogo de progresso durante execução da tarefa.

Parameters:

b - indicativo de progresso habilitado.

getTaskMessage

public String getTaskMessage()

Returns:

a mensagem que aparece no diálogo de progresso dessa tarefa.

getAdditionalInfo

protected String[] getAdditionalInfo()

Returns:

lista de informações adicionais que vão aparecer nos diálogos de erro para essa tarefa, e serão enviadas ao email do administrador se necessário. Ex: 'Nome do projeto', 'Caminho do arquivo'. Cada informação será mostrada em uma linha. Retornar NULL para nenhuma informação adicional.