Package com.ibm.jsdt.checkpoints

A startup checkpoint class is a class that executes prior to the deployment wizard UI being displayed.

See:
          Description

Class Summary
StartupCheckpoint This is the abstract base class that implements the default behavior for all startup checkpoint classes.
 

Package com.ibm.jsdt.checkpoints Description

A startup checkpoint class is a class that executes prior to the deployment wizard UI being displayed. The intended use of this class is to enable Solution providers the capability to perform prerequiste checking prior to launching their solution in the deployment wizard. Since the startup checkpoint only runs on the local machine, use of the startup checkpoint is restricted to solutions that have the deploy only to localhost option set true in the Advanced Solution Configuration section of the General tab in the Solution Editor of the Software Assembly Toolkit Developer. Based on the results of the prerequiste checking, the startup checkpoint can determine the launch behavior of the deployment wizard.

This abstract base class implements the default behavior for all startup checkpoint classes. Each startup checkpoint must extend this base class and implement the execute() method. The startup checkpoint class is executed immediately before the deployment wizard UI is displayed.

Each startup checkpoint subclass can override methods to modify attributes of the progress dialog. This dialog displays while the startup checkpoint class is executing. The attributes that can be modified include the title, message, message details, percent complete and whether or not the cancel button is enabled. If you want to override defaults on the progress dialog you must override initializeProgressDialog(). The deployment wizard will invoke initializeProgressDialog() prior to invoking your execute() method to ensure that the initial progress dialog is populated with the desired values.

The execute method should exit with a return code that indicates how the deployment wizard should continue. Based upon this return code the deployment wizard will continue to launch, display a dialog to abort the launch or prompt the user to see if they want to abort or continue. The subclass can override the title and message text of these dialogs.

For example usage of a startup checkpoint class refer to one of the following examples:

A Simple Startup Checkpoint

Listed below is sample code for a very simple startup checkpoint. It shows that the only method a startup chackpoint is required to implement is the execute method. You are free to right any code you want within this method or other methods you deem necessary to check prerequisites, etc... You just need to make sure that your method executes with one of the predefined return codes that indicate how the deployment wizard should proceed.

package startupCheckpoint;

import com.ibm.jsdt.checkpoints.StartupCheckpoint;

public class SimpleStartupCheckpoint extends StartupCheckpoint
{

  /**
   * Each startup checkpoint subclass must implement this method.
   * It controls the flow of execution for your startup checkpoint class.
   *
   * The deployment wizard will invoke this class as the entry point into
   * your startup checkpoint class. This is executed immediately before the
   * deployment wizard interface is displayed. If you wish to override defaults for
   * the progress dialog, you should override the initializeProgressDialog method. 
   *
   * @param silentMode - Indicates whether or not this startup checkpoint is 
   * being executed silently or in interactive mode. If silentMode is true then 
   * your should not surface any graphical user interfaces.
   *
   * @return An integer indicating how the deployment wizard should proceed.
   * Appropriate return values are listed below. Any other return code will be 
   * interpreted as a failure and result in the deployment wizard not being launched. 
   *  
   *    LAUNCH_DEPLOYER  -      indicates success and the deployment wizard will be launched 
   *    ABORT_DEPLOYER   -      indicates an error occured. A dialog with a default error message will be displayed 
   *                        and the deployment wizard will not be launched. The dialog title and text can be overriden. 
   *    PROMPT_USER      -  indicates a warning occurred. A dialog with a default warning message will be displayed. 
   * The user is presented with the option to continue and launch the deployment wizard or cancel. 
   * The dialog title and text can be overriden. 
   *  
   */
  public int execute(boolean silentMode)
  {
    //Implement any code you want to check for prerequisites, etc.
    //As an example, the code below checks to see if the operating system is Windows 2003  
    int returnCode = StartupCheckpoint.ABORT_DEPLOYER;
    if (System.getProperty("os.name").equals("Windows") && System.getProperty("os.version").startsWith("5.2"))
    {
      //We have a Valid OS
      returnCode = StartupCheckpoint.LAUNCH_DEPLOYER;
    }
    //Return a code indicating how the deployment wizard should proceed
    return returnCode;
  }
}

A Startup Checkpoint with customizations

Listed below is sample code for a startup checkpoint that overrides various text on the progress dialog, and abort dialog, and controls progress updates.

package startupCheckpoint;

import com.ibm.jsdt.checkpoints.StartupCheckpoint;

public class CustomizedStartupCheckpoint extends StartupCheckpoint
{

  /**
   * Each startup checkpoint subclass must implement this method.
   * It controls the flow of execution for your startup checkpoint class.
   *
   * The deployment wizard will invoke this class as the entry point into
   * your startup checkpoint class. This is executed immediately before the
   * deployment wizard interface is displayed. If you wish to override defaults for
   * the progress dialog, you should override the initializeProgressDialog method. 
   *
   * @param silentMode - Indicates whether or not this startup checkpoint is 
   * being executed silently or in interactive mode. If silentMode is true then 
   * your should not surface any graphical user interfaces.
   *
   * @return An integer indicating how the deployment wizard should proceed.
   * Appropriate return values are listed below. Any other return code will be 
   * interpreted as a failure and result in the deployment wizard not being launched. 
   *  
   *    LAUNCH_DEPLOYER  -      indicates success and the deployment wizard will be launched 
   *    ABORT_DEPLOYER   -      indicates an error occured. A dialog with a default error message will be displayed 
   *                        and the deployment wizard will not be launched. The dialog title and text can be overriden. 
   *    PROMPT_USER      -  indicates a warning occurred. A dialog with a default warning message will be displayed. 
   * The user is presented with the option to continue and launch the deployment wizard or cancel. 
   * The dialog title and text can be overriden. 
   *  
   */
  public int execute(boolean silentMode)
  {
    // Implement any code you want to check for prerequisites, etc.

    // As an example, the code below checks to see if the operating system is Windows 2003
    int returnCode = StartupCheckpoint.ABORT_DEPLOYER;
    if (System.getProperty("os.name").equals("Windows") && System.getProperty("os.version").startsWith("5.2"))
    {
      // We have a Valid OS
      
      //Since the progress mode was set to Manual this class controls updating the 
      //percent complete on the progress bar. Updating progress is optional. 
      //The default progress mode is Automatic which enables the framework to control progress on your behalf.
      setPercentComplete(10);
      // Do more prereq checking
      setPercentComplete(80);
      // Finish prereq checking
      setPercentComplete(100);
      returnCode = StartupCheckpoint.LAUNCH_DEPLOYER;
    }
    else
    {
      // Override the message that displays in the dialog informing the user that the
      // deployment wizard will not launch. The dialog title could also be overwritten. 
      // If your product is translated you should include your bundles as loose class files
      // in one of the application projects or as an external jar in one of the application 
      // projects reference by your solution.
      setAbortDialogMessage("Windows 2003 is not a supported platform. The only supported platform is Windows XP");
    }
    // Return a code indicating how the deployment wizard should proceed
    return returnCode;
  }

  /**
   * Initialzes the progress dialog with the desired values.
   * 
   * This method will be invoked by the deployment wizard to initialize the
   * progress dialog with it's default values before invoking your
   * execute(boolean) method. If you wish to override a value you should
   * invoke the appropriate setter from within this method. The values that
   * can be overriden for the progress dialog are listed below. If you do not
   * wish to override any default values on the progress dialog you may leave
   * this method blank.
   * 
   *     executionTime - invoke setExecutionTime(int)
   *     enableCancel - invoke enableCancelOnProgressDialog(boolean)
   *     title - invoke setProgressDialogTitle(String)
   *     message - invoke setProgressDialogMessage(String)
   *     details - invoke setProgressDialogDetails(String)
   *     progress mode - invoke setProgressMode(String)
   * 
   */
  public void initializeProgressDialog()
  {
    // Override the defaults used by the Progress Dialog that displays while
    // this startup checkpoint executes

    // Indicate the estimated time in minutes that it takes this class to
    // execute. The default time is 2 minutes.  
    setExecutionTime(1); 

    // Override the default progress dialog strings
    setProgressDialogTitle("Checking System for Prerequisites");
    setProgressDialogMessage("Checking for a supported OS");
    setProgressDialogDetails("Checking for Windows 2003");
    // Disable the cancel button so the user can not cancel execution of this startup checkpoint
    enableCancelOnProgressDialog(false);
    // Indicate that this class will control progress updates versus allowing
    // the framework to handle progress updates based on the amount of time that has elapsed.
    setProgressMode(StartupCheckpoint.MANUAL);
  }
}

A Simple Startup Checkpoint that uses the Support Framework

The support framework provides an easy way to perform functions commonly needed during installation. Some examples of the functional capabilities it provides are listed below. For more information on these apis as well as others, refer to the Support Framework Java Documentation Your startup checkpoint class should only use support framework apis that are not reliant upon a deployment being in progress. To utilize support framework apis in your startup checkpoint you must instantiate a DeploymentHelper and one of their subclasses. Then call the desired method with the required paramaters.

package startupCheckpoint;

import com.ibm.jsdt.checkpoints.StartupCheckpoint;
import com.ibm.jsdt.support.deploymenthelper.WindowsDeploymentHelper;

public class SimpleStartupCheckpointUsingSupportFramework extends StartupCheckpoint
{
  /**
   * Each startup checkpoint subclass must implement this method.
   * It controls the flow of execution for your startup checkpoint class.
   *
   * The deployment wizard will invoke this class as the entry point into
   * your startup checkpoint class. This is executed immediately before the
   * deployment wizard interface is displayed. If you wish to override defaults for
   * the progress dialog, you should override the initializeProgressDialog method. 
   *
   * @param silentMode - Indicates whether or not this startup checkpoint is 
   * being executed silently or in interactive mode. If silentMode is true then 
   * your should not surface any graphical user interfaces.
   *
   * @return An integer indicating how the deployment wizard should proceed.
   * Appropriate return values are listed below. Any other return code will be 
   * interpreted as a failure and result in the deployment wizard not being launched. 
   *  
   *    LAUNCH_DEPLOYER  -      indicates success and the deployment wizard will be launched 
   *    ABORT_DEPLOYER   -      indicates an error occured. A dialog with a default error message will be displayed 
   *                        and the deployment wizard will not be launched. The dialog title and text can be overriden. 
   *    PROMPT_USER      -  indicates a warning occurred. A dialog with a default warning message will be displayed. 
   * The user is presented with the option to continue and launch the deployment wizard or cancel. 
   * The dialog title and text can be overriden. 
   *  
   */
  public int execute(boolean silentMode)
  {
    //Implement any code you want to check for prerequisites, etc.
    //As an example, the code below checks to see if the operating system is Windows 2003  
    int returnCode = StartupCheckpoint.ABORT_DEPLOYER;
    if (WindowsDeploymentHelper.isWin2003())
    {
      //We have a Valid OS
      returnCode = StartupCheckpoint.LAUNCH_DEPLOYER;
    }
    //Return a code indicating how the deployment wizard should proceed
    return returnCode;
  }
}