Wizard API - Summary of problems and plan for changes

$Revision: 1.2 $ 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

• October 16, 2003: Preliminary plan was attached. Also this document was split to this summary, document Requirements on changes and Solution design documents design the changes.
  

September 24, 2003: The conclusion if Fix or redesign Wizard API? was proposed.

September 15, 2003: The supported use cases was added.

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
  

• Problems and the suspect places in current implementation
  
• Strong asked requirements
  
• Holes in current Wizard API
  
• Fix or redesign Wizard API?
  

Design of changes

• Preliminary Plan
  
• Requirements
  

• General basics and constraints
  
• The supported use cases
  
• Extend new API with aspects from Templates wizard (TBD)
  
• How to handles templates with new datasystems? (TBD)
  

Solution design

• Principles of new API
  
• Declarative registration (TBD)
  

See also:

Java Look and Feel Design Guidelines
UI Guidelines for NetBeans Wizards
Wizard API (javadoc)
Templates wizard (javadoc)
Wizard's issues

Goals

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.

Problems and the suspect places in current implementation

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.

Strong asked requirements

• 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

Holes in current Wizard API

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.

Fix or redesign Wizard API?

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.