com.ehsbe.commons.gui.wizard
Class Task

java.lang.Object
  com.ehsbe.commons.gui.wizard.Task

All Implemented Interfaces:

ExecService

public class Task
extends Object
implements ExecService

The task which needs to be executed. It is usually associated with a single UI panel, which contains all GUI elements to gather required data. A task may consist of other tasks and if so, it actually represents a tree of tasks.

Per contract it is not allowed to manage or modify a task by two or more different controllers or assign it to different lists!

NOTE: Since structure operations like insert/replace/remove modify the parent of the sub tasks in question, a sub task can be seen always only once in a tree.

Wrt. to the Wizard itself, the meat is made of the getId() as well as getExecService().

The ID in relation to the PREFIX_* constants is used to get the translations for the task name, the title to display, its description, and related images - so more or less a description of the work, which needs to be done.

The ExecService is used to actually do the work described by the task.

Version:

$Revision: 501 $

Author:

Jens Elkner

See Also:

TranslatorAdapter

Field Summary

static String	PREFIX_BANNER_IMAGE The prefix which gets used per default to lookup the the resource path for the banner image this task in a resource bundle.
static String	PREFIX_BG_IMAGE The prefix which gets used per default to lookup the resource path for sidebar background image for this task.
static String	PREFIX_DESC The prefix which gets used per default to lookup the localized description for this task in a resource bundle.
static String	PREFIX_NAME The prefix which gets used per default to lookup the localized name of the task in a resource bundle.
static String	PREFIX_TITLE The prefix which gets used per default to lookup the localized task title in a resource bundle.
static String	PREFIX_TT The prefix which gets used per default to lookup the localized tooltip for this task in a resource bundle.

Constructor Summary

Task(String id, Translator translator)
Create a task, which has no sub tasks.

Task(String id, Translator translator, List<Task> tasks)
Create a task which has sub tasks, which need to be completed subsequently to get this task finished.

Task(String id, Translator translator, Task... tasks)
Create a task which has sub tasks, which need to be completed subsequently to get this task finished.

Method Summary

void	addTasks(int index, List<Task> newTasks) Insert the list of new sub tasks to the current list of tasks at the given position.
void	clear() Remove all sub tasks from this task
boolean	equals(Object task) Contract: Two tasks are equal, if their IDs are equal.
JComponent	execute(HashMap<Task,HashMap<? extends Object,? extends Object>> settings, TaskControl control, EnumSet<NavMode> initalMode) Create the UI aka wizard page, which should be displayed and do the work described by the task.
void	finish(HashMap<Task,HashMap<? extends Object,? extends Object>> settings, TaskControl control, NavMode mode) Calculate final results for this task, cleanup resources and notify the controller, when all work has been done.
String	getBackgroundImagePath() Get the path for the background image as URL which should be displayed, when this step gets executed.
String	getBannerImagePath() Get the path for the banner image as URL which should be displayed, when this step gets executed.
int	getCount() Get the number of sub tasks.
String	getDescription() Get a more detailed description about what to do in this task, which might be shown in a banner panel or popup window.
protected ExecService	getExecService() Get the execution service used for this task.
String	getId() The ID of this task.
Locale	getLocale() Get the locale to be used for l10n.
String	getName() Get the localized short name of this task, which gets usually displayed in the task overview on the wizards sidebar.
Task	getParent() Get task, which owns this sub task.
Task	getSubTask(int index) Get the sub task at the specified index.
List<Task>	getSubTasks() Get the sub tasks, which need to be executed to finish this task.
String	getTitle() Get the title for this step, which gets usually displayed in the wizard's banner panel.
String	getTooltip() Get the tooltip for this task, which might be shown in a popup window or tooltip widget.
Translator	getTranslator() Get the translator for task related strings.
static Task	getUndeterminedTask(Locale locale) Create a default undetermined task.
int	hashCode()
boolean	hasHelp() Check, whether this task may provide any help UI.
int	indexOf(Task task) Get the index of the given sub task.
boolean	isUndetermined() Signals, that it is not yet determined, whether or which other tasks need to be executed, to finish the task previous task.
void	prepare(HashMap<Task,HashMap<? extends Object,? extends Object>> settings, TaskControl control) Prepare all data required to setup the UI aka wizard page for a task.
void	remove(int index) Remove the sub task at the given position.
int	remove(Task task) Remove the given sub task.
void	removeFromParent() Remove this sub task from the owners list of sub task.
void	replace(int fromIndex, int toIndex, List<Task> newTasks) Replace a range of sub tasks with the given list of new subtasks.
void	set(List<Task> newTasks) Replaces the currently sub tasks set with the given one.
void	setExecService(ExecService svc) Set the execution service to be used for this task.
void	setLocale(Locale locale) Set the locale to be used for l10n.
void	setParent(Task task) Set the task, which owns this sub task.
void	setTranslator(Translator xlate) Set the translator for task related strings.
void	showHelp(HashMap<Task,HashMap<? extends Object,? extends Object>> settings, TaskControl control, JComponent parent) Show the help for this task.
protected String	xlate(String prefix, String name) Get the translation wrt. the given prefix and name.

Methods inherited from class java.lang.Object

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

Field Detail

PREFIX_NAME

public static final String PREFIX_NAME

The prefix which gets used per default to lookup the localized name of the task in a resource bundle.

See Also:

Constant Field Values

PREFIX_TITLE

public static final String PREFIX_TITLE

The prefix which gets used per default to lookup the localized task title in a resource bundle.

See Also:

Constant Field Values

PREFIX_DESC

public static final String PREFIX_DESC

The prefix which gets used per default to lookup the localized description for this task in a resource bundle.

See Also:

Constant Field Values

PREFIX_TT

public static final String PREFIX_TT

The prefix which gets used per default to lookup the localized tooltip for this task in a resource bundle.

See Also:

Constant Field Values

PREFIX_BG_IMAGE

public static final String PREFIX_BG_IMAGE

The prefix which gets used per default to lookup the resource path for sidebar background image for this task.

See Also:

Constant Field Values

PREFIX_BANNER_IMAGE

public static final String PREFIX_BANNER_IMAGE

The prefix which gets used per default to lookup the the resource path for the banner image this task in a resource bundle.

See Also:

Constant Field Values

Constructor Detail

Task

public Task(String id,
            Translator translator)

Create a task, which has no sub tasks.

Parameters:

id - ID of the task

translator - translator to use for l10n. Might be null.

Throws:

IllegalArgumentException - if ID is null.

Task

public Task(String id,
            Translator translator,
            Task... tasks)

Create a task which has sub tasks, which need to be completed subsequently to get this task finished.

Parameters:

id - ID of the task

translator - translator to use for l10n. Might be null.

tasks - tasks, which need to be completed subsequently. Ignored if null.

Throws:

IllegalArgumentException - if ID is null.

Task

public Task(String id,
            Translator translator,
            List<Task> tasks)

Create a task which has sub tasks, which need to be completed subsequently to get this task finished.

Parameters:

id - ID of the task

translator - translator to use for l10n. Might be null.

tasks - tasks, which need to be completed subsequently. Ignored if null.

Throws:

IllegalArgumentException - if ID is null.

Method Detail

isUndetermined

public boolean isUndetermined()

Signals, that it is not yet determined, whether or which other tasks need to be executed, to finish the task previous task.

Returns:

true if consecutive steps need to be determined later. The default is false.

getUndeterminedTask

public static Task getUndeterminedTask(Locale locale)

Create a default undetermined task. Its ID is an empty String.

Parameters:

locale - locale to use for l10n

Returns:

a shared instance of a "undetermined" task.

getId

public String getId()

The ID of this task. Should be very short, not localized and unique within a wizard. Furthermore it must be compliant with the rules defined in Properties.load(java.io.Reader) to be able to form valid resource bundle keys. The empty String ("") is reserved and should not be used.

Returns:

the id of this task but not null.

equals

public boolean equals(Object task)

Contract: Two tasks are equal, if their IDs are equal.

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

setExecService

public void setExecService(ExecService svc)

Set the execution service to be used for this task.

Parameters:

svc - execution service to set. Might be null.

getExecService

protected ExecService getExecService()

Get the execution service used for this task.

Returns:

the execution service in charge. Might be null.

prepare

public void prepare(HashMap<Task,HashMap<? extends Object,? extends Object>> settings,
                    TaskControl control)

Prepare all data required to setup the UI aka wizard page for a task. One should not perform any UI setup/modifications here, since it gets usually not invoked from the EDT!

The controller makes sure, that this method gets always called before ExecService.execute(HashMap, TaskControl, EnumSet).

Setting navigation modes here has usually no effect and gets ignored, since per default all navigation buttons are disabled until ExecService.execute(HashMap, TaskControl, EnumSet) returns.

Specified by:

prepare in interface ExecService

Parameters:

settings - all settings and collected data so far.

control - the controller, which is in charge aka manages this task and needs to be notified on completion/business

execute

public JComponent execute(HashMap<Task,HashMap<? extends Object,? extends Object>> settings,
                          TaskControl control,
                          EnumSet<NavMode> initalMode)

Create the UI aka wizard page, which should be displayed and do the work described by the task. The controller makes sure, that this method gets always called within the EDT. So it should return relatively fast to avoid, that the wizard seems to be hanging.

Before this method gets called, the controller makes sure, that ExecService.prepare(HashMap, TaskControl) has been called before. Thats why all none-UI related preparations should be made there, so that this method is able to return fast.

Implementations should create the UI required for user input here, add required listeners to it and return the UI. After that, the controller notifies appropriate listeners, what usually results into adding the returned component to the wizard dialog and thus it gets visible.

When the controller decides to change the current task in action, the ExecService.finish(HashMap, TaskControl, NavMode) method gets called.

Specified by:

execute in interface ExecService

Parameters:

settings - all settings and collected data so far.

control - the controller, which is in charge aka manages this task and needs to be notified at least on completion/busyness.

initalMode - container, where to set initial navigation modes, when the UI for this wizard gets displayed.

Returns:

null if the task does not require an UI to be executed, the component, which is not visible, to display otherwise.

See Also:

Component.isVisible(), JComponent.setVisible(boolean), TaskControl.setBusy(Task, boolean), TaskControl.setLocale(Locale), TaskControl.setNavMode(Task, EnumSet)

finish

public void finish(HashMap<Task,HashMap<? extends Object,? extends Object>> settings,
                   TaskControl control,
                   NavMode mode)

Calculate final results for this task, cleanup resources and notify the controller, when all work has been done.

Invoked by the controller after ExecService.prepare(HashMap, TaskControl) or ExecService.execute(HashMap, TaskControl, EnumSet) to let the task cleanup its resources (e.g. populatated during the prepare and execute phase) and let it calculate its final results.

Usually this method gets invoked in a none-EDT in preparation to switch to the next or previous task or to finally finish the wizard. So if some UI modifications are done, one should invoke [and wait] appropriate work in the EDT.

The task is required to call its controller's TaskControl.finished(Task) method, to let it know, that it may [not] continue with the next step indicated by mode. To veto that the controller should not continue with the intended action, one should call its TaskControl.setNavMode(Task, EnumSet) before returning from this method to indicate, what is ok. However, the final decision about what to do next will be made by the controller.

So if this task denies the intended action, this method might be called several times.

Specified by:

finish in interface ExecService

Parameters:

settings - all settings and collected data so far.

control - the controller, which is in charge aka manages this task and needs to be notified at least on completion/busyness.

mode - what the controller intends to do next.

See Also:

EventQueue.isDispatchThread(), EventQueue.invokeAndWait(Runnable)

showHelp

public void showHelp(HashMap<Task,HashMap<? extends Object,? extends Object>> settings,
                     TaskControl control,
                     JComponent parent)

Show the help for this task.

This method gets usually called twice: First with parent set to null, i.e. none-UI work required for displaying help should be made. Per default, it gets called outside of the EDT.

When it gets called with a none-null parent, one may actually do all UI related work and show the help UI. The controller ensures, that this call gets made within the EDT.

Specified by:

showHelp in interface ExecService

Parameters:

settings - all settings and collected data so far.

control - the controller, which is in charge aka manages this task and needs to be notified at least on completion/busyness.

parent - where to anchor the help frame to show. null indicates, that none-UI preparations should be made - i.e. prepare help set, images etc.

hasHelp

public boolean hasHelp()

Check, whether this task may provide any help UI.

Specified by:

hasHelp in interface ExecService

Returns:

false if calling ExecService.showHelp(HashMap, TaskControl, JComponent) is useless, i.e. does nothing.

getTranslator

public Translator getTranslator()

Get the translator for task related strings.

Returns:

null if not set, the translator to use otherwise.

setTranslator

public void setTranslator(Translator xlate)

Set the translator for task related strings.

Parameters:

xlate - the translator to use. Might be null.

xlate

protected String xlate(String prefix,
                       String name)

Get the translation wrt. the given prefix and name. Per default it just delegates the call to the internal Translator.

Parameters:

prefix - prefix to use

name - name to use

Returns:

never null.

See Also:

getTranslator(), xlate(String, String)

getName

public String getName()

Get the localized short name of this task, which gets usually displayed in the task overview on the wizards sidebar.

Returns:

the localized name of this task, but never null.

See Also:

PREFIX_NAME, xlate(String, String)

getTitle

public String getTitle()

Get the title for this step, which gets usually displayed in the wizard's banner panel.

Returns:

the localized short title for this task, which might be an empty String but not null.

See Also:

PREFIX_TITLE, xlate(String, String)

getDescription

public String getDescription()

Get a more detailed description about what to do in this task, which might be shown in a banner panel or popup window. It should not contain line breaks or any other markup (like html).

Returns:

null if not available, the description otherwise.

See Also:

PREFIX_DESC, xlate(String, String)

getTooltip

public String getTooltip()

Get the tooltip for this task, which might be shown in a popup window or tooltip widget. It should not contain line breaks or other markup (like html).

Returns:

the localized tooltip for this task, which might be empty but not null.

See Also:

PREFIX_TT, xlate(String, String)

getBackgroundImagePath

public String getBackgroundImagePath()

Get the path for the background image as URL which should be displayed, when this step gets executed.

Returns:

null if there is no image availabe (i.e. use default), the image otherwise.

See Also:

PREFIX_BG_IMAGE, xlate(String, String)

getBannerImagePath

public String getBannerImagePath()

Get the path for the banner image as URL which should be displayed, when this step gets executed.

Returns:

null if there is no image availabe (i.e. use default), the image otherwise.

See Also:

PREFIX_BANNER_IMAGE, xlate(String, String)

getLocale

public Locale getLocale()

Get the locale to be used for l10n. Actually delegates to the current translator set.

Returns:

the locale used for l10n. Might be null.

See Also:

getTranslator()

setLocale

public void setLocale(Locale locale)

Set the locale to be used for l10n. Actually delegates to the current translator set. If the translator gets later replaced, it might use a different locale.

Parameters:

locale - locale to use. Might be null, i.e. the default one should be used.

See Also:

getLocale(), getTranslator()

setParent

public void setParent(Task task)

Set the task, which owns this sub task. However, it does not change the parents subtask list and thus for proper operation one needs to add the task to the parent's sub task list! Safer way is to use replace(int, int, List) for usual operations.

Parameters:

task - this task's owner. Might be null.

See Also:

getSubTasks(), replace(int, int, List)

getParent

public Task getParent()

Get task, which owns this sub task.

Returns:

null if this is not a sub task, the parent otherwise.

getSubTasks

public List<Task> getSubTasks()

Get the sub tasks, which need to be executed to finish this task.

Returns:

an unmodifiable and possible empty list, but never null.

getSubTask

public Task getSubTask(int index)

Get the sub task at the specified index.

Parameters:

index - the index of the sub task in question

Returns:

the task at the given index

Throws:

IndexOutOfBoundsException - if an index is out of range

indexOf

public int indexOf(Task task)

Get the index of the given sub task.

Parameters:

task - task to lookup.

Returns:

-1 if not found, the index of the sub task otherwise.

replace

public void replace(int fromIndex,
                    int toIndex,
                    List<Task> newTasks)

Replace a range of sub tasks with the given list of new subtasks. I.e. all subtasks between the specified fromIndex, inclusive, and toIndex, exclusive are removed (if fromIndex and toIndex are equal, nothing gets removed). After that, the given list of new sub tasks gets inserted at fromIndex.

The parent of removed tasks gets automatically set to null, the parent of inserted tasks gets automatically set to this task.

Parameters:

fromIndex - low endpoint (inclusive) of the subList

toIndex - high endpoint (exclusive) of the subList

newTasks - sub tasks to add. If null the given sub task gets simply removed from the current sub tasks list.

Throws:

IndexOutOfBoundsException - if an index is out of range (fromIndex > toIndex || fromIndex < 0 || toIndex < subTasks.size())

clear

public void clear()

Remove all sub tasks from this task

set

public void set(List<Task> newTasks)

Replaces the currently sub tasks set with the given one.

Parameters:

newTasks - sub tasks to set

addTasks

public void addTasks(int index,
                     List<Task> newTasks)

Insert the list of new sub tasks to the current list of tasks at the given position.

Parameters:

index - position in current sub task list where to insert the new sub tasks

newTasks - sub tasks to insert

Throws:

IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size())

remove

public int remove(Task task)

Remove the given sub task.

Parameters:

task - task to remove.

Returns:

the index of the removed task, -1 if not found.

remove

public void remove(int index)

Remove the sub task at the given position.

Parameters:

index - position of the sub task to remove.

removeFromParent

public void removeFromParent()

Remove this sub task from the owners list of sub task. Does nothing, if this task has no owner.

getCount

public int getCount()

Get the number of sub tasks.

Returns:

the number of sub tasks.