Package com.ibm.jsdt.support

The support framework provides an easy way to perform functions commonly needed during installation.

See:
          Description

Class Summary
SupportAixBase Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportAixHelper Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportBase Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportHelper Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportHPUXBase Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportHPUXHelper Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportLinuxBase Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportLinuxHelper Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportOS400Base Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportOS400Helper Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportSolarisBase Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportSolarisHelper Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportWindowsBase Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
SupportWindowsHelper Deprecated. Due to new package com.ibm.jsdt.support.deploymenthelper
 

Package com.ibm.jsdt.support Description

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 utilize this functionality in your own programs.

This package contains two main groups of classes:

Base Functionality

The SupportBase classes are the basis of the support framework, and they must be extended to utilize it. By extending the SupportBase corresponding to the system you will install to (for example, in a Linux based program you would extend the SupportLinuxBase) you may use the support framework to access frequently needed 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 the default values specified in the application and solution wrappers, because those values are stored in the solution file. Any subsequent configuration changes made by the user are also held in memory. When the install takes place, all of the configuration information for each application in the solution, as well as staging server configuration info is written to <agent install path>/IIA/logs/ibmnsi.properties. It is from this file that you may retrieve these variables, using the API provided by the support framework. For an example, see the section on retrieving a variable value.

Helper Functionality

The SupportHelper classes provide the methods used to ease interaction with the computer system. Any class extending one of the SupportBase classes has a getHelper function (such as getLinuxHelper), which returns an object used to help access the system. By calling methods of that helper object, common interactions with the computer system are simplified. A simple example of this can be found here.

Examples

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

Assigning user privileges / access rights

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

import com.ibm.jsdt.support.SupportWindowsBase;
import com.ibm.jsdt.support.SupportWindowsHelper;

// First, extend the appropriate SupportBase class. 
public class ExampleEntryProgram extends SupportWindowsBase
// In this example, we extended the SupportWindowsBase because this program
// was intended for 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 SupportBase object.    
    ExampleEntryProgram base = new ExampleEntryProgram();

    // Third, call the SupportBase methods as specified by the API  
    // of the SupportHelper functions that you will use.
    // 
    // In this method we call setUserName and addPrivilegeRequest (performs
    // the same action as setPrivileges, without having to create a list first)
    // to prepare for SupportWindowsHelper.grantPrivilegesToUser.
    base.setUserName("JoeUser"); 
    base.addPrivilegeRequest(SERVICE_LOGON_RIGHT);
    base.addPrivilegeRequest(CREATE_A_TOKEN_OBJECT);
    base.addPrivilegeRequest(INCREASE_QUOTA);
    base.addPrivilegeRequest(REPLACE_A_PROCESS_LEVEL_TOKEN);
    base.addPrivilegeRequest(ACT_AS_PART_OF_THE_OPERATING_SYSTEM);

    // Finally, call the desired SupportHelper function and pass it the 
    // SupportBase object which was prepared in the previous steps.
    base.getWindowsHelper().grantPrivilegesToUser(base);

    .
    .
    .

  }
}

Verifying registry keys

Checking the existance of registry keys on Windows can be done using the method doesRegKeyExist found in the SupportWindowsHelper class:

import com.ibm.jsdt.support.SupportWindowsBase;
import com.ibm.jsdt.support.SupportWindowsHelper;

// First, extend the appropriate SupportBase class. 
public class ExampleEntryProgram extends SupportWindowsBase  
{
  public static final int HKEY_LOCAL_MACHINE   =  1;
  public static final int HKEY_CLASSES_ROOT    =  2;
  public static final int HKEY_USERS           =  3;
  public static final int HKEY_CURRENT_USER    =  4;
  public static final int HKEY_CURRENT_CONFIG  =  5;
  
  public ExampleEntryProgram(){}
  
  public static void main(String args[])
  {
    .
    .
    .

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

    // Third, call the SupportBase methods as specified by the API  
    // of the SupportHelper functions that you will use.
    // 
    // In this method we call setRegistryKey and setRegistrySubKey 
    // to prepare for SupportWindowsHelper.doesRegKeyExist.
    base.setRegistryKey(HKEY_LOCAL_MACHINE); 
    base.setRegistrySubKey("SOFTWARE\\IBM\\DB2\\DB2 Universal Database Workgroup Edition\\CurrentVersion");

    // Finally, call the desired SupportHelper function and pass it the 
    // SupportBase object which was prepared in the previous steps.
    boolean doesKeyExist = base.getWindowsHelper().doesRegKeyExist(base);

    .
    .
    .

  }
}

Updating a String in an XML file

Updating a String in an XML file can be done using a combination of calls to functions provided by the support framework. For example, suppose that you had a file named plugin.xml containing the element <TagX hostname="localhost">. If you wanted to update the hostname in the tag to specify "my.hostname", you could implement something similar to the following:

import com.ibm.jsdt.support.SupportBase;
import com.ibm.jsdt.support.SupportHelper;
import java.io.StringWriter;
import java.io.PrintWriter;

// First, extend the appropriate SupportBase class. 
public class ExampleEntryProgram extends SupportBase  
{
  public ExampleEntryProgram(){}

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

    // Second, create an instance of a SupportBase object.    
    ExampleEntryProgram base = 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 = base.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\">";
    
    base.updateXMLString(path, fileName, oldElement, newElement);

    .
    .
    .

  }

  public void updateXMLString(String path, String filename, 
                                String oldSubstring, String newSubstring)
  {
    // Third, call the SupportBase methods as specified by the API  
    // of the SupportHelper functions that you will use, and then call
    // the SupportHelper functions.
    // 
    // In this method we call setFileName to prepare for SupportHelper.readFile.
    // We call setTargetString, setOldSubstring, and setNewSubstring to prepare
    // for SupportHelper.replaceSubstring.
    // Finally, we call setMessage and setAppend to prepare for SupportHelper.writeFile.
    setFileName(path + filename); 
    try                 
    { 
      setTargetString(getHelper().readFile(this))
    }
    catch (IOException e)
    {
      StringWriter sw = new StringWriter();
      e.printStackTrace(new PrintWriter(sw));
      logMessage(sw.toString());  // See method below
    }
    setOldSubstring(oldSubstring); //String to replace
    setNewSubstring(newSubstring);
    String updatedConfigFileContents = getHelper().replaceSubstring(this);
    setMessage(updatedConfigFileContents);
    setAppend(false); //overwrite versus append
    try
    { 
      getHelper().writeFile(this);
    }
    catch (IOException e)
    {
      StringWriter sw = new StringWriter();
      e.printStackTrace(new PrintWriter(sw));
      logMessage(sw.toString());  // See method below
    }
  }

  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.
    setMessage(message);
    setLogFileName("ExampleEntryProgram.log");
    setLogsDir(getHelper().getLogsDir(this));

    getHelper().log(this); 
  }

  public String getInstallDir(String varName)
  {
    setJarFile(getHelper().getProductInstallingId(this))
    setVariableName(varName);

    return getHelper().getIbmNsiPropValue(this);
  }
}

Updating a response file value

Updating a response file value can be done using the method setResponseFileValue found in the SupportHelper class. For example, suppose that you had a response file named plugin.iss containing the element providerId = "Default". If you wanted to update the value specified by providerId to be "MyCompany", you could implement something similar to the following:

import com.ibm.jsdt.support.SupportBase;
import com.ibm.jsdt.support.SupportHelper;

// First, extend the appropriate SupportBase class. 
public class ExampleEntryProgram extends SupportBase  
{
  public ExampleEntryProgram(){}

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

    // Second, create an instance of a SupportBase object.    
    ExampleEntryProgram base = 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 = base.getHelper().getLogsDir(base) + "plugin.iss";
    String key = "providerId ";
    String keyValue = " \"MyCompany\"";

    if(base.updateResponseFileValue(fileName, key, keyValue))
      return 0;  // update was successful
    else
      return 1;

    .
    .
    .

  }

  public boolean updateResponseFileValue(String filename, String key, String keyValue)
  {
    // Third, call the SupportBase methods as specified by the API  
    // of the SupportHelper functions that you will use.
    // 
    // In this method we call setResponseFileName, setKey, and setKeyValue 
    // to prepare for SupportHelper.setResponseFileValue.
    setResponseFileName(filename); 
    setKey(key);
    setKeyValue(keyValue);
    
    // Finally, call the desired SupportHelper function and pass it the 
    // SupportBase object which was prepared in the previous steps.
    return getHelper().setResponseFileValue(this);
  }
}

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 taken from the wrapper for WebSphere Application Server v4.02. Note the variable name and keyword. The keyword will be used to access the desired info (the variable WAS402win_prod_path which is the target directory of the installation) via 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.
Now take a look at how you can use this information to retrieve the variable in your code:

import com.ibm.jsdt.support.SupportBase;
import com.ibm.jsdt.support.SupportHelper;

// First, extend the appropriate SupportBase class. 
public class ExampleEntryProgram extends SupportBase  
{
  public ExampleEntryProgram(){}

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

    // Second, create an instance of a SupportBase object.    
    ExampleEntryProgram base = 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 jarFileName = base.getHelper().getProductInstallingId(base);
    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 = base.getProductVariable(jarFileName, variable);

    .
    .
    .

  }

  public String getProductVariable(String jarFileName, String variable)
  {
    // Third, call the SupportBase methods as specified by the API  
    // of the SupportHelper functions that you will use, and then call
    // the SupportHelper functions.
    // 
    // In this method we call setJarFile and setVariableName to prepare 
    // for SupportHelper.getIbmNsiPropValue.
    setJarFile(jarFileName); 
    setVariableName(variable);

    // Finally, call the desired SupportHelper function and pass it the 
    // SupportBase object which was prepared in the previous steps.
    return getHelper().getIbmNsiPropValue(this);
    
    // To retrieve an ISMP variable, apart from calling the setJarFile and setVariableName,
    // you will also need to call setPropertyKeyType to set the appropriate property type 
    // to "product", "wizard" or "global". Then invoke the SupportHelper.getIbmMsiISMPPropValue
    // passing it the SupportBase object. 
    setPropertyKeyType(propertyType);
    return getHelper().getIbmNsiISMPPropValue(this);
  }
}

Checking free space in a path

Checking the amount of free disk space in a path can be done using the method checkFreeSpace found in the SupportHelper class:

import com.ibm.jsdt.support.SupportWindowsBase;
import com.ibm.jsdt.support.SupportWindowsHelper;

// First, extend the appropriate SupportBase class. 
public class ExampleEntryProgram extends SupportWindowsBase  
{
  public ExampleEntryProgram(){}
  
  public static void main(String args[])
  {
    .
    .
    .

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

    // Third, call the SupportBase methods as specified by the API  
    // of the SupportHelper functions that you will use.
    // 
    // In this method we call setPath in order to 
    // prepare for SupportHelper.checkFreeSpace.
    base.setPath("C:\\myDir\\"); 

    // On Linux/Unix systems, it would look something like:  
    //    base.setPath("/opt/");
    // Be sure to give the full path in either case.

    // Finally, call the desired SupportHelper function and pass it the 
    // SupportBase object which was prepared in the previous steps.
    int freeSpace = base.getHelper().checkFreeSpace(base);

    .
    .
    .

  }
}

Logging a message

Logging messages can be done using the methods log and logStatus found in the SupportHelper class:

import com.ibm.jsdt.support.SupportBase;
import com.ibm.jsdt.support.SupportHelper;

// First, extend the appropriate SupportBase class. 
public class ExampleEntryProgram extends SupportBase  
{
  public ExampleEntryProgram(){}

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

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

    // Third, call the SupportBase methods as specified by the API  
    // of the SupportHelper functions that you will use.
    // 
    // In this method we call setMessage, setLogFileName, and setLogsDir 
    // to prepare for SupportHelper.log.
    base.setMessage("ExampleEntryProgram active."); 
    base.setLogFileName("logger.log");
    base.setLogsDir(base.getHelper().getLogsDir(base));

    // Finally, call the desired SupportHelper function and pass it the 
    // SupportBase object which was prepared in the previous steps.
    base.getHelper().log(base);       // One way to log a message.
    base.getHelper().logStatus(base); // Another way to log a message.

    .
    .
    .

  }
}

Since:
JDK1.3.1