WebStart Wizard SDK User Guide

CONTENTS

  1. What is a wizard?

  2. What can wizards be used for?

  3. WebStart wizards

  4. Creating a wizard with the WebStart Wizard SDK

  5. WebStart Wizards and Install

  6. Wizard Architecture

  7. Install Wizard Architecture

  8. Webstart Wizards API Documentation

1. What is a wizard?

Table of Contents
A wizard is a graphical user interface model that is suited to task based software. Task based software is software that implements an algorithm with two or more steps that must be done in sequential order. Examples of task based software are software installation and configuration.

A wizard consists of graphical panels that are designed to guide the user through the task. The user navigates through the set of panels with two buttons, back and next.

The back button visits the previously displayed panel. The next button visits the following panel. Through the use of these two buttons, the user is able to visit each panel in the wizard and configure each of the panels.

The panels are used to configure the wizard to perform the task exactly as the user desires.

2. What can wizards be used for?

Table of Contents
Because the wizard guides the user through the steps required to perform a task, wizards are a good user interface choice for software installation and configuration.

Software installation often requires many steps to be carried out in order for the software product to work correctly and also to register the software in the product registry so the product can be tracked, and later removed. The instructions that describe all of these steps would be difficult to write in such a way that they would work correctly on all of the platforms that are supported by the product. There is a strong possibility that the user would get confused and install the software incorrectly.

Wizards aid in software installation, because they guide the user through steps to perform the installation. The wizard presents panels that enable the user to configure the installation (for example, specify the directory where the product should be installed). Installation wizards increase the likelihood that the product will get installed correctly and that the user will not get confused. This reduces support calls related to software installation. This also enables web deployment of software. The user should be able to download one file (the install wizard) and install the software. With conventional README files, the user has to download multiple files and then use the documentation to follow the steps manually. The wizard facilitates ease of use for both the download and the installation.

Software configuration also benefits from the wizard model. Because configuration is often performed long after the software was installed, the documentation may have been misplaced or be unavailable to the user at the time they want to configure or reconfigure the software.

Because wizards guide the user through the configuration process, he can configure the software without necessarily having to use the documentation.

3. Web Start wizards

Table of Contents
WebStart wizards are created using the WebStart Wizard Software Developer's Kit (SDK). Java was used to create the SDK in order to support multiple platforms with a common look and feel.

Wizard Archive
WebStart wizards are written into a self-extracting archive. This makes the wizards easy to use by not requiring the user to be a Java expert.

If a JAR file were used for the wizard container, the user would have to set the classpath to include the JAR file, and specify on the command line which class within the JAR file to execute. This generally requires that the user has read a README file, or worse - that the user had to look at the JAR file's table of contents and try each class until one worked.

The WebStart wizards are packaged in a single class file. This class file has a class attribute that contains all of the supporting classes required by the wizard. This enables the wizard to run with the default classpath. Upon execution, the wizard classes are read from the archive and made available (via a ClassLoader) to the wizard. You can also include initialization data, images, audio, and other data in the wizard archive.

Wizard GUI
The WebStart wizard user interface is arranged in three sections:
  • Identifying image
  • Content panel
  • Navigation panel

    • Use the identifying image area to display an image that helps the user identify the purpose of the wizard. This is a display-only area, and is not meant to query or collect information from the user.

    Use the content panels to display information to the user and also to collect information from the user that configures the wizard. Only one content panel is displayed at a time. The content panels are traversed through the use of the navigation panel.

    The navigation panel appears at the bottom of the wizard's graphical user interface. This panel contains buttons used to navigate through the wizard's content panels. A Back button is provided to allow the user to visit the previous panel. A Next button is provided to allow the user to advance to the next panel. The navigation panel also contains an Exit button, which is used to exit the wizard.

    Cross Platform Wizards
    The WebStart wizard SDK is platform independent. For software installation, this means that the user can create a single install wizard that installs a Java application. If that application includes native methods, the shared library for the platform the wizard is executed on is installed in a location that is searched when java.lang.System.loadLibrary() is called. In this way, a simple HTML software deployment page could present customers with a single file to download, regardless of the target platform. When executed, the wizard determines what platform it is installing on, and install the correct files in locations that make sense on the target platform.

    4. Creating a wizard with the WebStart Wizard SDK

    Table of Contents
    Wizard Definitions
    The following definitions will make the wizard process clearer:

    Wizard Archive: A wizard archive is a single class file that contains a graphical user interface that guides the user through a set of wizard panels. This class archive is the wizard.

    Builder: A wizard builder is a Java application that writes the wizard archive. The builder is written using the WebStart SDK. The builder is a subclass of ArchiveWriter. It defines which wizard panels are displayed, and also what tasks the wizard performs.

    Panel: A wizard panel displays in the content panel area of the wizard. Wizard panels present information to the user and collect the user's preferences. Panels enable the user to configure the wizard. Wizard panels are subclassed from WizardLeaf.

    Client Tree A wizard client tree is a tree structure consisting of wizard panels and wizard nodes. The tree structure defines what panels the wizard can display and the order in which those panels are displayed. It also allows for multiple paths. The tree structure allows groups of panels to optionally be skipped during navigation. This enables you to create a wizard with a simple set of panels for a beginner to configure. It also provides more complex panels for the advanced users to exert more control over the wizard's configuration.

    Node: A node is an object within the client tree that groups panels together. A node can choose to have its panels skipped. You can use nodes to create a wizard hierarchy.

    Client Client refers to the classes that comprise the part of the wizard that executes on the client side. You can configure a wizard so that the tasks are performed on one machine (the remote machine) and the user interface is displayed on another machine (the local machine). All classes that are executed on the local machine are considered the client. These classes include:

  • WizardTreeManager
  • WizardComponent
  • WizardComposite
  • WizardLeaf
  • QueryDialog
  • com.sun.wizards.panels.*
  • com.sun.wizards.nodes.*

    • Server Server refers to all of the classes that comprise the part of the wizard that executes on the server side. A wizard can be configured such thhat the tasks are performed on one machine (the remote machine) and the user interface is displayed on another machine (the local machine). All classes that are executed on the remote machine are considered the server. These classes include:

  • WizardState
  • ArchiveReader
  • SequenceManager
  • Sequence
  • ServerObject
  • Task
  • com.sun.wizards.tasks.*

    • Task A task is an object that performs an operation on the server. Tasks are added to a Sequence object. A task is a single element of execution.

    Sequence A Sequence is an ordered group of tasks that performs some operation on the server. The purpose of a task is to perform an elemental step on the server, such as set data into the WizardState object. The purpose of a Sequence is to perform a logical operation, such as install a product.

    Wizard Creation Overview
    The creation of a wizard involves 2 steps:
    1. Write the wizard builder.
    2. Run the wizard builder to create the wizard archive.
    The wizard builder is responsible for creating the wizard archive. In practice, the wizard builder will create and initialize objects and then serialize those objects into a class attribute appended to a class file. This resulting class file (having the serialized classes and initialization data embeded in it) is the wizard archive.

    There are four key elements the wizard builder must set up in order to create a functional wizard archive:

    1. The client tree structure and contents.
    2. The initialization of the WizardState object.
    3. Server side objects including tasks and server objects.
    4. Add required resources (images, classfiles, supporting information, etc) to the wizard.
    Example Wizard Builder
    Following is source code for a simple wizard builder. This wizard builder will create a wizard archive that contains two panels. 
    import com.sun.wizards.core.WizardState;
import com.sun.wizards.builder.ArchiveWriter;
import com.sun.wizards.panels.*;

public class ExampleWizardBuilder extends ArchiveWriter
{
  public ExampleWizardBuilder()
  {
    super();

    /*
     * Set the name of the class archive to "exampleWizard.class"
     */
    this.archiveName = "exampleWizard";
  }

  protected void createClientTree()
  {
    super.createClientTree();
    WizardState wizardState = getWizardState();

    /*
     * Create the client panels.
     */
    TextImagePanel firstPanel = new TextImagePanel(wizardState, "First Panel");
    firstPanel.addText("This is the first panel in the example wizard.",
		       0, 25);
    TextImagePanel secondPanel = new TextImagePanel(wizardState, "Second Panel");
    secondPanel.addText("This is the second panel in the example wizard.",
			0, 25);

    /*
     * Add the panels to the wizard.
     */
    root.addChild(firstPanel);
    root.addChild(secondPanel);
  }

  public static void main(String[] args)
  {
    ExampleWizardBuilder exampleWizardBuilder = new ExampleWizardBuilder();
    exampleWizardBuilder.writeArchive();
  }
}
    Creating the wizard from this builder source code only involves compiling the builder source and executing the resulting ExampleWizardBuilder.class program. The result will be a classfile named "exampleWizard.class". This is the wizard archive.

    To execute the wizard, you must run the exampleWizard class with the 'java' or 'jre' command:

    java exampleWizard

    The wizard user interface will appear.

    The example wizard is a very simple one that does not actually perform a task.

    5. WebStart Wizards and Install

    Table of Contents
    The first application utilizing the WebStart Wizard API is install. The com.sun.install package contains panels, tasks, and other objects specific to installation and removal of software.

    An install wizard contains a Product Tree that describes the product to be installed in terms of its components, the technology that does the actual installation, and dependencies that determine which components or subcomponents of the product should be installed. The specific technologies currently supported are the SVR4 package (for Solaris), and simple files (for Microsoft Windows). SVR4 packages are installed or removed using the PkgUnit class. Simple files are supported via the FileUnit class.

    There are a number of install-specific panels that query the user for information required at install time. For example, there is a DirectorySelectionPanel which queries the user for the install location of the product. There is also a ComponentPanel which allows the user to select which components of the product the user wishes to install.

    Last modified: Mon Nov 23 14:20:30 PST 1998