com.gargoylesoftware.base.gui

Class AbstractUIController

java.lang.Object

com.gargoylesoftware.base.gui.AbstractUIController

public abstract class AbstractUIController
extends java.lang.Object

An abstract superclass for GUI controller classes.

Swing uses an architecture similar to Model-View-Controller (MVC) in which the model, view and controller components are kept seperate from each other. This class provides some common behaviour that is useful for controller objects. This includes support for:

• Starting and managing worker threads. See startTask(WorkerTask), taskComplete(WorkerTask), taskSuccessful(WorkerTask), taskExceptionThrown(WorkerTask,Exception), taskErrorThrown(WorkerTask,Throwable)
  
• Simple support for localization. See setLocale(Locale), getLocale(), localeChanged(Locale)

Version:

$Revision: 1.6 $

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	AbstractUIController.TaskRunnable

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.Locale	locale_

Constructor Summary

Constructors

Constructor and Description
AbstractUIController() Create a new controller.

Method Summary

Modifier and Type	Method and Description
protected void	assertNotNull(java.lang.String fieldName, java.lang.Object object) Throw an exception if the specified object is null
java.util.Locale	getLocale() Return the current locale.
protected abstract void	localeChanged(java.util.Locale locale) The current locale has changed - update all locale specific information.
void	run() The main entry point into this controller
protected abstract void	runImpl() Subclasses will override this to provide the run logic
void	setLocale(java.util.Locale locale) Set the current locale
protected void	startTask(WorkerTask task) Start a WorkerTask.
protected void	taskComplete(WorkerTask task) A callback that will be invoked when a task has completed whether it was successful or not.
protected void	taskErrorThrown(WorkerTask task, java.lang.Throwable throwable) A callback that will be invoked when a system error is thrown during the processing of a WorkerTask.
protected void	taskExceptionThrown(WorkerTask task, java.lang.Exception exception) A callback that will be invoked when an exception is thrown during the processing of a WorkerTask.
protected void	taskSuccessful(WorkerTask task) A callback that will be invoked when a task completed successfully.

Methods inherited from class java.lang.Object

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

Field Detail

locale_

private java.util.Locale locale_

Constructor Detail

AbstractUIController

public AbstractUIController()

Create a new controller.

Method Detail

setLocale

public final void setLocale(java.util.Locale locale)

Set the current locale

Parameters:

locale - the new locale

getLocale

public final java.util.Locale getLocale()

Return the current locale.

Returns:

The current locale

run

public final void run()

The main entry point into this controller

runImpl

protected abstract void runImpl()

Subclasses will override this to provide the run logic

startTask

protected final void startTask(WorkerTask task)

Start a WorkerTask. This involves running some code on a background thread and then some more on the ui thread. See WorkerTask for more details.

When the task has completed, one of the following callbacks will be called based on the success of the task.

• If the task completed without error then taskSuccessful() will be called
• If an exception was thrown during processing of the task then taskExceptionThrown() will be called
• If an error was thrown during processing of the task then taskErrorThrown() will be called

Finally, the method taskSuccessful() will be called will be called to signal the completion of the task

Parameters:

task - The WorkerTask that is about to execute.

taskExceptionThrown

protected void taskExceptionThrown(WorkerTask task,
                                   java.lang.Exception exception)

A callback that will be invoked when an exception is thrown during the processing of a WorkerTask. Note that errors and other throwables will processed by the method taskErrorThrown(WorkerTask,Throwable).

The default behaviour is to print the stack trace of the caught exception to System.out. Override this method to provide custom error handling.

Parameters:

task - The task that failed

exception - The exception that was caught.

taskErrorThrown

protected void taskErrorThrown(WorkerTask task,
                               java.lang.Throwable throwable)

A callback that will be invoked when a system error is thrown during the processing of a WorkerTask. System errors are any throwable objects not descended from Exception. Typically, only system level code will be concerned by the errors handled by this method. Application code should only be concerned with the errors handled by taskExceptionThrown(WorkerTask,Exception). The default behaviour is to print the stack trace of the caught error to System.out. Override this method to provide custom error handling.

Parameters:

task - The task that failed

throwable - The throwable object that was caught

taskSuccessful

protected void taskSuccessful(WorkerTask task)

A callback that will be invoked when a task completed successfully. Override this method to provide custom handling on completion of a task.

The default behaviour is to do nothing. Override this to provide custom behaviour.

Parameters:

task - The task that just finished.

taskComplete

protected void taskComplete(WorkerTask task)

A callback that will be invoked when a task has completed whether it was successful or not. Override this method to provide custom handling on completion of a task. The default behaviour is to do nothing. Override this to provide custom behaviour.

Parameters:

task - The task that just finished.

localeChanged

protected abstract void localeChanged(java.util.Locale locale)

The current locale has changed - update all locale specific information. All logic that sets locale sensitive information should be executed in this method.

Parameters:

locale - The new locale

assertNotNull

protected final void assertNotNull(java.lang.String fieldName,
                                   java.lang.Object object)

Throw an exception if the specified object is null

Parameters:

fieldName - The name of the paremeter we are checking

object - The value of the parameter we are checking