Package com.ibm.jsdt.facade

The facade package enables solution providers to perform dynamic solution configuration based on the environment of the systems they are targeting.

See:
          Description

Class Summary
SolutionConfiguration Provides an api to skip welcome panel
TaskConfiguration Provides a facade of apis to modify attributes of TaskGroup and Task objects.
VariableConfiguration This class provides a facade of apis to modify variable values.
 

Exception Summary
ApplicationObjectNotFoundException Purpose: Exception indicating that the specified application could not be foud.
DeployerNotRunningException Purpose: Exception indicating the deployment wizard is not running and that a task file deployment is not being performed.
InvalidHostnameException Purpose: Exception indicating that the specified hostname is invalid.
InvalidTaskOptionException Purpose: Exception indicating that you are attempting to specify an invalid option for a task or task group.
InvalidVariableFormatException Purpose: Exception indicating that the specified variable format is not valid.
InvalidVariableValueException Purpose: Exception indicating that the specified value is invalid for this variable.
TargetNotFoundException Purpose: Exception indicating that a selected task does not have a target specified.
TaskObjectNotFoundException Purpose: Exception indicating that the specified task group or task could not be foud.
VariableNotFoundException Purpose: Exception indicating that the specified variable could not be found in the solution.
 

Package com.ibm.jsdt.facade Description

The facade package enables solution providers to perform dynamic solution configuration based on the environment of the systems they are targeting. The facade package provides a set of apis that act as a facade to various solution objects. There are three main classes that you will operate on to modify a solutions configuration prior to it loading in the Deployment Wizard. These objects include the following

See the Java documentation for each object for details on the specific apis provided. These apis are designed to run within a StartupCheckpoint class. The StartupCheckpoint is launched prior to the solution loading in the Deployment Wizard. It provides the mechanism to call various apis to dynamically modify the solution based on the targetted environment. Note that the StartupCheckpoint executes on the local machine and does not provdide any remote capability. If applications contained in your solution will be targeted to remote machines, your Startup Checkpoint is responsible for gathering information from the remote system to determine what solution modifications to make.

If an api attempts to make an invalid change, the facade object will throw an exception. The exception should be caught and inspected to retrieve the pertinent error information. Before your StartupCheckpoint class exits you should call the validateSolution method to ensure that ths solution is valid based on all apis that were called. This gives you an opportunity to proactively catch any errors and take any needed corrective action. Otherwise the errors will be caught when the solution is loaded and api modifications you made may be undone. See the validateSolution method for more information.

For example usage of a startup checkpoint class that utilizes facade objects to dynamically modify a solution see below.

package startupCheckpoint;

import com.ibm.jsdt.checkpoints.StartupCheckpoint;
import com.ibm.jsdt.facade.TaskConfiguration;
import com.ibm.jsdt.facade.VariableConfiguration;

public class MyStartupCheckpoint 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 or modify variable values or task selection*******
      try
      {
        VariableConfiguration vc = new VariableConfiguration();
        vc.setVariableValue("task id", "app id", "variableName", "value");
        vc.skipAllConfigurationPanels(true);
        TaskConfiguration tc = new TaskConfiguration();
        tc.setAllTasksSelectedByDefault(true, true);
        tc.addTargetInfoForTask("task id", "hostname", "userId", "password", tc.WINDOWS, true);
        tc.skipAllTaskSelectionPanels(true);
        tc.skipAllTargetPanels(true);
        tc.validateSolution();
      }
      catch (Exception e)
      {
        //Catch the appropriate exception object
        //Inspect the objects fields for pertinent error information and 
        //determine what how you want to proceed
      }

      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(3);

    // 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);
  }
}