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:
-
A base class "DeploymentHelper" that provides functionality to aid user programs in the deployment of applications.
-
Operating specific classes that extend DeploymentHelper to provide utility methods deploying applications on a specific operating system.
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