Wizard API - Summary of problems and plan for changes
$Revision: 1.11 $
Jiri Rechtacek
Abstract:
The document describes known issues, known requirements, plans, future
directions of wizard's framework. Also describes typically use-cases wizard's
framework and general principles of redesigned API. The standard API architecture
review is tracked by
issue 36584.
What's new
Names convention
In order to provide a good comprehension and clarity of this document,
user
means end-user works with wizard,
client means a developer who builds on the
top
Wizard API.
Page means one sheet (or dialog) in sequence
of wizard's dialogs. User's forward/backward from one page to another is
Step.
Content:
- Goals
- Current implementation
- Design of changes
See also:
Wizard API should be easy and useful framework provides creating and
handling dialogs which leads a user step-to-step through task. We want to bring
a response on requirements to the clients to make the API easy-to-use and easy-to-build on it. First
goal is make the summary of the requirements, next, to propose the changes and also
to document the supported use-cases.
We can split the reported issues against openide/wizards subcomponent
on three areas:
- general problem of wizard's framework (the main area of interest
of this document)
- problems of template wizard's implementation (although template
wizard is only one extension of
Wizard API is a key use-case, very close of wizards
framework, it's also matter this document)
- issues of the concrete wizards provided by core module, e.g.
Mount wizard (these problems partly depend on general wizard's problem,
partly are specific in concrete implementation). These won't be a point of
interest this document.
The code of current wizard framework doesn't provide an easy
survey, behavior is hard determined. Massive bugfixing makes the code
less and less maintainable, too regression prone. There are
several areas of reported defects:
- UI (focus, fontsize problem, A11Y problems)
- step management
- performance (memory leak)
- branding
The
Wizard API doesn't provide a asked control of movement across
wizard's panels, more control the enabling/disabling of the buttons and
make more possible cooperation several modules on a shared wizard.
- enable/disable buttons
The Next and Finish are controlled by
WizardDescriptor.Panel.isValid(), it cannot be enabled
or disabled independently. Moreover, Finish button can enabled only on
panel which implements FinishPanel, it's static and prohibitive of react to filled
values.
Enhancement requires extension of Wizard API with suitable methods. It's tracked
by issue
7706.
- enable veto processing Next/Finish buttons and keep user on
current panel
During enter values in a wizard's panel, framework does validation on all
changes. If the panel is valid, user can forward to next panel or finish wizard.
If the panel is not valid that user cannot forward. There are a several
problems: user doesn't know what's wrong why a panel is not valid, the
validation on all changes must be lightweight for performance reasons and there is not
place for heavy validation e.g. deploy a remote object on application server
which can pass or fail. Next problem appears if a wizard finished
unsuccessfully, user cannot change some value and finish wizard again. Here will
be vetoable processing Next/Finish buttons very useful.
For reach this functionality, current Wizard API should be
enlarged for "off-line" validation, called in right time. Corresponding issue is feature
23116.
- postpone irreversible changes (e.g. create a folder) during walk
around the panels
During walk around the panels might create new objects e.g. new folder in
filesystem or deployed remote object on server. These object can persist
although the wizard is canceled. The changes could be postponed till
Finish action is performed if possible. It also depends on a support of reversible
creating object on a target system (e.g. filesystems).
Wizard framework should allow postpone creating new objects if possible
and also allow cleanup these objects when the wizard is canceled. The current
API could do that with the minor problems. Strengthen support depends on
support of reversible changes in target system.
- add a compound iterator to support sharing a wizard between
modules
Because wizard can be shared between several modules then Wizard
API should support the compound iterator which reflects this fact. The panels
involved in a wizard could be branched by infilled values. The step management
in current API doesn't support it, especially TemplateWizard breaks it. This is
one of key requirements, tracked by issue 35787.
The concept, how to handle this, hasn't been known yet.
A depending requirement asks a possibility of declarative registration of panels.
- add support for long-term processing a forward step (mainly the
finish step)
Processing Next or Finish buttons can take long-term,
the current wizards don't provide feedback to user (i.e. wizard is closed and some
task runs). Feedback should use a progress bar and provide a Summary page at the
end of panel which will inform about upcoming actions. "off-line"
validation (described above) could help too. See issues 27512 and 30216.
- separate Template wizard from openide/loaders and don't depend on old
datasystems
Most used wizard, Template Wizard is based on openide/datasystems which
are currently deprecated thus there are the required actions: Separate
TemplateWizard from openide/loaders package and don't depend of old
datasystems, research how to handle creating templates on the top of new
datasystems. This will be discussed in Templates
section. A other requirement is how to enlarge Wizard API with
useful methods from TemplateWizard.
TemplateWizard.instantiate() is called when the wizard is
finished and performs instantiation of new objects. Method like this should be
added in Wizard API as central point for creating new object. It's
tracked by issue 34043
Wizard API forces developers to use
JComponent.putClientProperty()
to communicate to the wizard infrastructure. API is not well-documented,
not specify definite contract about a calling sequence. Some desired methods are
missing.
The implementation of
WizardDescriptor mixes the control
functionality and UI presentation, some UI aspects are hardcoded.
The requirements on current API and the found API's holes (described above) lead
to decision if fixes the current state or redesign a new API based of known
use-cases.
The fixes of current API has following pros and cons:
Fixes pros:
- Minimalize changes of client's side.
- Allows incremental delivery.
Fixes cons:
- The massive changes in API implementation could break the undocumented
contracts.
- The API will remarkable enlarged with new concepts (new methods and
new interfaces, the possibility to declare the panels), it makes the API less
well-arranged and more inconsistent.
The redesign has following pros and cons:
Redesign pros:
- The asked requirements will be cleanly covered in new API and its
implementation
- Get rid of using
JComponent.putClientProperty().
- Split the
Wizard APIs on one execute/data part and UI part.
Redesign cons:
- Guided the clients with new API.
- Changes of client's side if s/he will used use API.
- Some (wanted) features of current implementation will not be
supported.
Submitter's proposal: In the light in
Fixes cons and
Redesign pros I propose make new API based
on supported use-cases. To avoid force the changes on the client side then the
current API and its implementation won't be changed but will be deprecated. The
new API will be separated to own package contained API, SPI and the whole wizard's framework.
This intention was submitted to Architecture Review, tracked by
issue 36584.
Reviewer's proposal: In the light in
Fixes cons and
Redesign pros I propose make new API based
on supported use-cases. To avoid big bang effect and to
pick up as much of low hanging fruits as possible while minimazing the impact on
the existing implementation we propose to start with incremental implementation
of small changes (get rid of
putClientProperty, better control of
next/finish buttons, composition of iterators, etc.) in a
alternative
(e.g. provide special handling of some interfaces, while leaving the handling of
original interfaces untouched as much as possible). The ultimate goal is of
course clean and powerful API, but in our current state that seems like a holy
grail and we can improve the user and API user experience by a small
compatible improvements than big bang rewrite. The complete rewrite could be a
solution, but only if the implementation team provided some guarantees that a
the new implementation will be
better
(support those good things currently
supported, will be more stable, more performant, the API flow will be cleared, etc.).
But as
current comments
to the
Architecture Review
show, there is not too much opinions that would support such expectation.
