The support framework provides an easy way to perform functions commonly needed during installation. Some examples of the functional capabilities it provides are the ability to easily: Refer to the Examples section below for ways to use this functionality in your own programs.

This package contains two main groups of classes:

Base Functionality

The DeploymentHelper class provides the foundation of the support framework and it provides various utility methods that can be useful when deploying applications, running programs and other commands through user programs. Operating system helper classes are provided as a companion to the DeploymentHelper class. These classes extend the DeploymentHelper and provide utility methods that are specific to an operating system. The support framework provides access to essential system information and methods which might otherwise be time consuming or tedious to discover on your own. See Assigning user privileges / access rights for an illustration.

Another useful part of the support framework is the ibmnsi.properties file. When the staging server is launched it has access to all of default values specified in the application and solution deployment accelerators, because those values are stored in the solution file. Any subsequent configuration changes made by the user are also held in memory. When the installation takes place, all of the configuration information for the staging server and for each application in the solution is written to the <agent install path>/IIA/logs/ibmnsi.properties file. Using the API provided by the support framework, you can retrieve the variables from the ibmnsi.properties file. For an example, see the section on retrieving a variable value.

Examples

The following examples demonstrate how to utilize the support framework functionality in your own programs:

Assigning user privileges / access rights

On versions of Windows that support assigning Windows privileges, assigning user privileges can be done using the method grantPrivilegesToUser found in the WindowsDeploymentHelper class. In the example below we have defined several useful constants for user rights. You can define additional constants for user rights in your own programs:

import java.awt.List;
import com.ibm.jsdt.support.deploymenthelper.WindowsDeploymentHelper;

// Define the ExampleEntryProgram class. 
public class ExampleEntryProgram
// In this example, we intended to use WindowsDeploymentHelper class because this program
// is run on Windows systems.
{
  public static final String SERVICE_LOGON_RIGHT = "SeServiceLogonRight";
  public static final String CREATE_A_TOKEN_OBJECT = "SeCreateTokenPrivilege";
  public static final String INCREASE_QUOTA = "SeIncreaseQuotaPrivilege";
  public static final String REPLACE_A_PROCESS_LEVEL_TOKEN = "SeAssignPrimaryTokenPrivilege";
  public static final String ACT_AS_PART_OF_THE_OPERATING_SYSTEM = "SeTcbPrivilege";

  public ExampleEntryProgram(){}

  public static void main(String args[])
  {
    .
    .
    .

    // Second, create an instance of a ExampleEntryProgram object.    
    ExampleEntryProgram exampleEntry = new ExampleEntryProgram();

    // In this method, create userName and a list of requestedPrivileges 
    // to prepare for WindowsDeploymentHelper.grantPrivilegesToUser.
    String userName = "JoeUser";
    List requestedPrivileges = new List(); 
    requestedPrivileges.add(SERVICE_LOGON_RIGHT);
    requestedPrivileges.add(CREATE_A_TOKEN_OBJECT);
    requestedPrivileges.add(INCREASE_QUOTA);
    requestedPrivileges.add(REPLACE_A_PROCESS_LEVEL_TOKEN);
    requestedPrivileges.add(ACT_AS_PART_OF_THE_OPERATING_SYSTEM);

    // Finally, call the desired WindowsDeploymentHelper function.
    WindowsDeploymentHelper.grantPrivilegesToUser(userName, requestedPrivileges);

    .
    .
    .

  }
}

Verifying registry keys

You can check for the existence of registry keys on Windows using the method doesRegKeyExist found in the WindowsDeploymenHelper class as demonstrated in the following example:

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

// Define the ExampleEntryProgram class. 
public class ExampleEntryProgram  
{
  // A set of integer HKEY variables are the global constants from WindowsDeploymentHelper
  // HKEY_LOCAL_MACHINE   =  1;
  // HKEY_CLASSES_ROOT    =  2;
  // HKEY_USERS           =  3;
  // HKEY_CURRENT_USER    =  4;
  // HKEY_CURRENT_CONFIG  =  5;
  
  public ExampleEntryProgram(){}
  
  public static void main(String args[])
  {
    .
    .
    .

    // Second, create an instance of an exampleEntryProgram object.    
    ExampleEntryProgram exampleEntry = new ExampleEntryProgram();

    // Set registryKey and registrySubKey for WindowsDeploymentHelper.doesRegKeyExist
    int registryKey = WindowsDeploymentHelper.HKEY_LOCAL_MACHINE; 
    String registrySubKey = "SOFTWARE\\IBM\\DB2\\DB2 Universal Database Workgroup Edition\\CurrentVersion";

    boolean doesKeyExist = WindowsDeploymentHelper.doesRegKeyExist(registryKey, registrySubKey);

    .
    .
    .

  }
}

Updating a String in an XML file

You can update a String in an XML file using a combination of calls to functions provided by the support framework. For example, if you haved a file named plugin.xml containing the element <TagX hostname="localhost"> and you want to update the hostname in the tag to specify "my.hostname", you could implement something similar to the following example:

import com.ibm.jsdt.support.deploymenthelper.DeploymentHelper;
import java.io.StringWriter;
import java.io.PrintWriter;

//Define the ExampleEntryProgram class.
public class ExampleEntryProgram  
{
  public ExampleEntryProgram(){}

  public static void main(String args[])
  {
    .
    .
    .

    // Second, create an instance of a ExampleEntryProgram object.    
    ExampleEntryProgram exampleEntry = new ExampleEntryProgram();
    
    String path = "C:\\Program Files\\ProgramX\\";
    // If you are exposing the install directory as a variable then you can 
    // retrieve that value here instead.
    // Example Variable Retrieval: 
    //   path = exampleEntry.getInstallDir("product_install_dir");
    //   where "product_install_dir" is the name of the exposed variable.
    //   See getInstallDir method below for an implementation.
    String fileName = "plugin.xml";
    String oldElement = "<TagX hostname=\"localhost\">";
    String newElement = "<TagX hostname=\"my.hostname\">";
    
    exampleEntry.updateXMLString(path, fileName, oldElement, newElement);

    .
    .
    .

  }

  public void updateXMLString(String path, String filename, 
                                String oldSubstring, String newSubstring)
  {
    // In this method we create filePathName to prepare for DeploymentHelper.readFile.
    // We create targetString to prepare for DeploymentHelper.replaceSubstring.
    // Finally, we create message to prepare for DeploymentHelper.writeFile.
    String filePathName = path + filename;
    String targetString = ""; 
    try                 
    { 
      targetString = DeploymentHelper.readFile(filePathName)
    }
    catch (IOException e)
    {
      StringWriter sw = new StringWriter();
      e.printStackTrace(new PrintWriter(sw));
      logMessage(sw.toString());  // See method below
    }
    
    String updatedConfigFileContents = DeploymentHelper.replaceSubstring(targetString, oldSubstring, newSubstring);
    String message = updatedConfigFileContents;
    boolean append = false; //overwrite versus append
    DeploymentHelper.writeFile(filePathName, message, append);
  }

  public void logMessage(String message)
  {
    // Here we use the message logging functionality provided by the support framework.
    // The usage is explained in the message logging example.
    
    String logFileName = "ExampleEntryProgram.log";    
    DeploymentHelper.log(message, logFileName); 
  }

  public String getInstallDir(String varName)
  {
    return DeploymentHelper.getIbmNsiPropValue(varName);
  }
}

Updating a response file value

You can update a response file value using the method setResponseFileValue found in the DeploymentHelper class. For example, if you have a response file named plugin.iss containing the element providerId = "Default", and you want to update the value specified by providerId to "MyCompany", you could implement something similar to the following example:

import com.ibm.jsdt.support.DeploymentHelper;

// Define ExampleEntryProgram class. 
public class ExampleEntryProgram  
{
  public ExampleEntryProgram(){}

  public static void main(String args[])
  {
    .
    .
    .

    // Second, create an instance of a DeploymentHelper object.    
    ExampleEntryProgram exampleEntry = new ExampleEntryProgram();
    
    // Typically, you can prepend the response file name with the return value from 
    // getLogsDir() which is an absolute path to the IIA/logs directory.
    String fileName = DeploymentHelper.getLogsDir() + "plugin.iss";
    String key = "providerId ";
    String keyValue = " \"MyCompany\"";
    boolean createKey = false;  // Create key if it doesn't exist.

    exampleEntry.updateResponseFileValue(fileName, key, keyValue, createKey)
    
    .
    .
    .

  }

  public boolean updateResponseFileValue(String filename, String key, String keyValue, boolean createKey)
  { 
    // Finally, call the desired DeploymentHelper function to update the response file value by specified key
    return DeploymentHelper.setResponseFileValue(filename, key, keyValue, createKey);
  }
}

Retrieving a variable value for any product within a solution

The following example demonstrates how to retrieve variables of the currently installing product and variables of other related products within the solution:

Note: This excerpt is taken from the deployment accelerator for WebSphere Application Server v4.02. Note the variable name and keyword. The keyword will be used to access the desired information (the variable WAS402win_prod_path which is the target directory of the installation) via using the support framework API on the target:
<variables>
 <stringVariables>
  <stringVariable
    name="WAS402win_prod_path"   // Formal identifier of the variable being stored 
    minimumLength="4">           // This identifier is NOT used for variable retrieval.
    <defaultData>C:\Websphere\AppServer</defaultData> 
    <labelText translatedKey="pathLabel"/>
    <helpText translatedKey="pathHelp"/>
   <issFileAssociations>
    <issFileAssociation
      responseFileName="WASsetup.iss"
      section="SelectTargetDir"
      keyword="szDir"/>      // This variable name is stored in the ibmnsiproperties file as
                             // "szDir = <value>", where <value> is the installation path.
The following example demonstrates how you can use this information to retrieve the variable in your own code:

import com.ibm.jsdt.support.DeploymentHelper;

// Define ExampleEntryProgram class. 
public class ExampleEntryProgram  
{
  public ExampleEntryProgram(){}

  public static void main(String args[])
  {
    .
    .
    .

    // Second, create an instance of a DeploymentHelper object.    
    ExampleEntryProgram exampleEntry = new ExampleEntryProgram();

    // Here we set the jarFileName as the currently installing product Id.
    // Note that jarfilename is actually the product id.
    //
    // If you wanted to get a variable from a product not currently installing
    // you would simply specify that product's wrapper Id here instead.
    String variable = "szDir";  // notice that you use the keyword, 
                                // NOT the variable name ("WAS402win_prod_path" in this case).
                                // szDir is the name of the variable found in the response file.
 
    String value = exampleEntry.getProductVariable(variable);

    .
    .
    .

  }

  public String getProductVariable(String variable)
  {    
    // To retrieve an ISMP variable, you will also need to set propertyKeyType 
    // to "product", "wizard" or "global". Then invoke the DeploymentHelper.getIbmMsiISMPPropValue
    String propertyKeyType = "product";
    return DeploymentHelper.getIbmNsiISMPPropValue(variable, propertyKeyType);
  }
}

Checking free space in a path

You can check the amount of free disk space in a path using the checkFreeSpaceAvailable method found in the DeploymentHelper class. The following example demonstrates the use of the checkFreeSpace method:

import com.ibm.jsdt.support.WindowsDeploymentHelper;

// Define ExampleEntryProgram class. 
public class ExampleEntryProgram  
{
  public ExampleEntryProgram(){}
  
  public static void main(String args[])
  {
    .
    .
    .

    // Second, create an instance of a ExampleEntryProgram object.    
    ExampleEntryProgram exampleEntry = new ExampleEntryProgram();

    // In this method we create path in order to 
    // prepare for DeploymentHelper.checkFreeSpaceAvailable.
    String path = "C:\\myDir\\"; 

    // On Linux/Unix systems, it would look something like:  
    // String path = "/opt/";
    // Be sure to give the full path in either case.
    long freeSpace = DeploymentHelper.checkFreeSpaceAvailable(path);

    .
    .
    .

  }
}

Logging a message

You can log messages using the log method found in the DeploymentHelper class. The following example demonstrates the use of of these methods:

import com.ibm.jsdt.support.deploymenthelper.DeploymentHelper;

// Define ExampleEntryProgram class. 
public class ExampleEntryProgram  
{
  public ExampleEntryProgram(){}

  public static void main(String args[])
  { 
    .
    .
    .

    // Second, create an instance of a ExampleEntryProgram object.    
    ExampleEntryProgram exampleEntry = new ExampleEntryProgram();
 
    // In this method we create message, logFileName to prepare for DeploymentHelper.log.
    String message = "ExampleEntryProgram active."; 
    String logFileName = "logger.log";

    DeploymentHelper.log(message, logFileName);       // One way to log a message.
    DeploymentHelper.log(message);       // Anotherway, to log a message to the default logFileName.
    .
    .
    .

  }
}

Run a command

Any system or application command is managed by DeploymentHelper.executeCommand method. The result of this method is a ProgramOutput object that contains the stdOutput, stdError, returnCode and executed command string.

Notes: For the OS400 platform QSH command, you can use OS400DeploymentHelper.executeCommandNoConvertToASCII that calls DeploymentHelper.executeCommand internally to process the command. If you want to execute a command and have the option to convert the output to ASCII format, the execute command method OS400DeploymentHelper.executeCommandAndConvertToASCII can be used with the boolean convertFromEBCDIC option(true/false). In addition, for the CL command of OS400 system, the OS400DeploymentHelper.runCLCommand is used.

The following example demonstrates the use of the DeploymentHelper.execute command method:

import com.ibm.jsdt.support.deploymenthelper.DeploymentHelper;
import com.ibm.jsdt.support.deploymenthelper.WindowsDeploymentHelper;
import com.ibm.jsdt.support.deploymenthelper.OS400DeploymentHelper;
import com.ibm.jsdt.support.deploymenthelper.ProgramOutput;

// Define ExampleEntryProgram class. 
public class ExampleEntryProgram  
{
  public ExampleEntryProgram(){}

  public static void main(String args[])
  { 
    .
    .
    .

    // Second, create an instance of a ExampleEntryProgram object.    
    ExampleEntryProgram exampleEntry = new ExampleEntryProgram();
 
    // In this method we can get the version information of the installed product.
    String result = exampleEntry.getVersionInfo();       // Get version information of installed product

    // Process the "result"
    .
    .
    .

  }

  public String getVersionInfo()
  {
    String installLocation = "/usr/IBM/HTTPServer";
    String command = null;
    String commandResult = "";
    ProgramOutput output = new ProgramOutput();
    if (isWindows())
    {
      installLocation = WindowsDeploymentHelper.getWindowsShortPath(installLocation).replace('\\', '/');
    }

    if (isLinux())
    {
      // command to run
      command = installLocation + DeploymentHelper.SLASH + "bin" + DeploymentHelper.SLASH + "versionInfo.sh";
    }
    else
    {
      // command to run
      command = installLocation + DeploymentHelper.SLASH + "bin" + DeploymentHelper.SLASH + "versionInfo";
    }

    // invokeCommand and logs command for OS400 
    // OS400DeploymentHelper.executeCommandNoConvertToASCII will call DeploymentHelper.executeCommand method internally 
    // to process the execution.
    if (isOS400())
    {
      output = OS400DeploymentHelper.executeCommandNoConvertToASCII(command,command);
      commandResult = output.getStdOut();
    }
    else
    {
      output = DeploymentHelper.executeCommand(installLocation, null, false, true, null, command);
      commandResult = output.getStdOut();
      
   
    }
    return commandResult;
  }

}
@since JDK1.3.1