com.ehsbe.commons.gui.wizard
Interface ExecService

All Known Implementing Classes:

ExecServiceAdapter, Task

public interface ExecService

A Service, which actually does the work described by a tasks.

Version:

$Revision: 502 $

Author:

Jens Elkner

Method Summary

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.
boolean	hasHelp() Check, whether this task may provide any help UI.
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	showHelp(HashMap<Task,HashMap<? extends Object,? extends Object>> settings, TaskControl control, JComponent parent) Show the help for this task.

Method Detail

prepare

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 execute(HashMap, TaskControl, EnumSet).

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

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

Throws:

NullPointerException - if an argument is null

execute

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 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 finish(HashMap, TaskControl, NavMode) method gets called.

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.

Throws:

NullPointerException - if an argument is null

See Also:

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

finish

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 prepare(HashMap, TaskControl) or 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.

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.

Throws:

NullPointerException - if an argument is null

See Also:

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

showHelp

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.

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.

Throws:

NullPointerException - if settings or control is null

hasHelp

boolean hasHelp()

Check, whether this task may provide any help UI.

Returns:

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