com.ehsbe.commons.gui.wizard
Class TaskControl

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

public class TaskControl
extends Object

The controller which manages the tasks, which need to be executed.

A task which gets executed, may change/influence the order of execution as well as vizualization by using one of the TaskControl.Callback annotated methods.

Version:

$Revision: 502 $

Author:

Jens Elkner

Nested Class Summary

static interface

TaskControl.Callback Marks methods for primary use by the task being controlled by this instance.

Field Summary

protected EventListenerList

listenerList listener list

Constructor Summary

TaskControl(Task root)
Create a new controller which manages the given task.

Method Summary

void	addPageListener(TaskControlListener listener) Register the given listener so that it gets notified, if the state of a page or its controller changes.
void	allUniqueIDs() Check the complete task tree starting at this instance' origin for duplicated IDs.
void	dispose() Cleanup all resources.
void	finished(Task task) Callback for the task being executed in response to its Task.finish(HashMap, TaskControl, NavMode) to indicate, that it is ready and switching to the next action indicated by the user is ok.
void	finishTask(HashMap<Task,HashMap<? extends Object,? extends Object>> settings, NavMode nextMode) Usually called by the wizard to indicate, that it intents to switch to another state.
protected void	fireStateChange(TaskControlEvent.Type what, EnumSet<NavMode> mode) Fires a TaskControlEvent.
Task	get() Get the current step excecuted.
int	getDepth() Get the path length for the current task in action.
static int	getDepth(Task task, Task origin) Get the path lenght to the given task wrt. to its origin.
Locale	getLocale() Get the locale, which should be used by all tasks.
Task	getOrigin() Get the origin of all tasks, controlled by this instance.
JComponent	getPage(HashMap<Task,HashMap<? extends Object,? extends Object>> settings, EnumSet<NavMode> initalMode) Create the wizard page, which needs to be shown for the current task in action.
List<Task>	getPath() Get the path from the root task aka origin down to the current active task.
List<Task>	getPath(Task task) Get the path from the root task aka origin down to the given task.
boolean	isBusy() Get the busy state of the task currently being executed.
Task	next(boolean forward) Get the next task, which needs to be executed.
static Task	next(Task task, Task stop) Get the next task which needs to be executed wrt. the given task.
void	prepare(HashMap<Task,HashMap<? extends Object,? extends Object>> settings) Prepare the task, so that it has all information required to create the UI for information gathering and execution.
Task	previous(boolean backward) Get the task, which has been executed before this task.
void	removePageListener(TaskControlListener listener) Unregisters listener so that it will no longer receive PageEvents.
void	setBusy(Task task, boolean busy) Callback for the task being executed to indicate its busyness.
void	setLocale(Locale locale) Set the locale, which should be used by all panels.
void	setNavMode(Task task, EnumSet<NavMode> mode) Calback for the currently executing task to inform about state changes, which caused a change in currently allowed navigation modes.
void	showHelp(HashMap<Task,HashMap<? extends Object,? extends Object>> settings, JComponent parent) Shows the help for the current task in action, if its Task.hasHelp() returns true.
void	taskListChanged(Task task) Facility to let the task in action notify interested parties, that the task list to whom it belongs to, was modified.

Methods inherited from class java.lang.Object

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

Field Detail

listenerList

protected EventListenerList listenerList

listener list

Constructor Detail

TaskControl

public TaskControl(Task root)

Create a new controller which manages the given task.

Parameters:

root - the mother of all tasks, which need to be executed.

Method Detail

getOrigin

public Task getOrigin()

Get the origin of all tasks, controlled by this instance.

NOTE: The returned task may still have a none-null parent!

Returns:

null if no tasks are controlled, the root of all tasks otherwise.

get

public Task get()

Get the current step excecuted.

Returns:

null if no step is beeing executed, the current step otherwise.

next

public Task next(boolean forward)

Get the next task, which needs to be executed. Invoking this with true is the only way to advance to the next task. However, for obvious reasons this should be done by the Wizard Controller, only!

Parameters:

forward - if true, advance the internal cursor to the task being returned, if the current one is not null.

Returns:

null if there are no more task to be executed, the next task otherwise.

previous

public Task previous(boolean backward)

Get the task, which has been executed before this task. Invoking this with true is the only way to go back to the previous task. However, for obvious reasons this should be done by the Wizard Controller, only!

Parameters:

backward - if true, set the internal cursor to the task being returned, execept if there is no previous task.

Returns:

the previously executed task, which might be null.

next

public static Task next(Task task,
                        Task stop)

Get the next task which needs to be executed wrt. the given task.

Parameters:

task - target for which to get the next task

stop - an ascent, where to stop searching for the next task. If null the tree gets traversed up to the task, which has no parent if necessary.

Returns:

the next task or null if all task are finished.

getDepth

public int getDepth()

Get the path length for the current task in action.

Returns:

0 if the current task in action has no further parent, -1 if no task has been set, the path length from its origin otherwise.

getDepth

public static int getDepth(Task task,
                           Task origin)

Get the path lenght to the given task wrt. to its origin. Or in other words, the number of Task.getParent() calls required to reach the origin OR root node of the given task.

Parameters:

task - target for which to get the path length

origin - an ascent, where to stop searching for the next task. If null the tree gets traversed up to the task, which has no parent if necessary.

Returns:

the path length to the given node, which is 0 for the mother of all tasks (aka root nodes), -1 if the given task is null.

setBusy

public void setBusy(Task task,
                    boolean busy)

Callback for the task being executed to indicate its busyness.

Controller will notify all listeners about this state change, which in turn may visualize the busyness in an appropriate way.

Parameters:

task - the notifying task

busy - If true, the task does some background work in a none-EDT thread. If false, the task has finished its work in the none-EDT thread.

isBusy

public boolean isBusy()

Get the busy state of the task currently being executed.

Returns:

true if busy with none-EDT thread(s).

finished

public void finished(Task task)

Callback for the task being executed in response to its Task.finish(HashMap, TaskControl, NavMode) to indicate, that it is ready and switching to the next action indicated by the user is ok.

Parameters:

task - the notifying task.

finishTask

public void finishTask(HashMap<Task,HashMap<? extends Object,? extends Object>> settings,
                       NavMode nextMode)

Usually called by the wizard to indicate, that it intents to switch to another state.

Parameters:

settings - all settings and collected data so far.

nextMode - what to do next

setNavMode

public void setNavMode(Task task,
                       EnumSet<NavMode> mode)

Calback for the currently executing task to inform about state changes, which caused a change in currently allowed navigation modes.

Parameters:

task - the notifying task

mode - new navigation mode, which should be propagated to all interested parties.

prepare

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

Prepare the task, so that it has all information required to create the UI for information gathering and execution. This method might be called outside the EDT, so don't do any UI stuff here!

It returns immediately and sends an appropriate state notification, when the task has been prepared.

Parameters:

settings - all settings and collected data so far.

See Also:

#fireStateChange(Type, EnumSet)

setLocale

public void setLocale(Locale locale)

Set the locale, which should be used by all panels.

Parameters:

locale - locale to use.

getLocale

public Locale getLocale()

Get the locale, which should be used by all tasks.

Returns:

null if not set, the locale to use otherwise.

getPage

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

Create the wizard page, which needs to be shown for the current task in action.

Should be called by the controlling wizard, only.

It makes sure, that component gets created within the EDT.

Parameters:

settings - all settings and collected data so far.

initalMode - the set of navigation buttons, which should initially be enabled. All others should be disabled.

Returns:

null if the current task needs no extra page aka user interaction, the not yet visible wizard page otherwise.

showHelp

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

Shows the help for the current task in action, if its Task.hasHelp() returns true.

Parameters:

settings - all settings and collected data so far.

parent - where to anchor the help UI.

Throws:

IllegalArgumentException - if the given parent is null.

taskListChanged

public void taskListChanged(Task task)

Facility to let the task in action notify interested parties, that the task list to whom it belongs to, was modified.

Per contract, as soon as a task or one of its ascents gets assigned to a task controller, it has to notify the controller about structure changes. Furthermore it is only allowed to change the structure of not yet executed tasks.

Parameters:

task - the notifying task.

addPageListener

public void addPageListener(TaskControlListener listener)

Register the given listener so that it gets notified, if the state of a page or its controller changes.

Parameters:

listener - listener to register. Ignored if null.

removePageListener

public void removePageListener(TaskControlListener listener)

Unregisters listener so that it will no longer receive PageEvents.

Parameters:

listener - listener to unregister. Ignored if null.

getPath

public List<Task> getPath()

Get the path from the root task aka origin down to the current active task.

Returns:

a possible empty list.

See Also:

getPath(Task)

getPath

public List<Task> getPath(Task task)

Get the path from the root task aka origin down to the given task.

Parameters:

task - where to start going up.

Returns:

a possible empty list.

allUniqueIDs

public final void allUniqueIDs()
                        throws javax.ejb.DuplicateKeyException

Check the complete task tree starting at this instance' origin for duplicated IDs. Since it is more or less resource consuming, this method gets per default not used by this controller. A developer should know, when it is wise and appropriate to apply this check ...

Throws:

javax.ejb.DuplicateKeyException - for the first duplicated ID found

fireStateChange

protected void fireStateChange(TaskControlEvent.Type what,
                               EnumSet<NavMode> mode)

Fires a TaskControlEvent. Since it gets usually called in response to a task callback, listener notification happens in a separate none-EDT thread to prevent task blocking.

Parameters:

what - the state change occured.

mode - navigation mode to proagate.

dispose

public void dispose()

Cleanup all resources. After calling this method this controller should not be used anymore.