PROTOTYPE
Not reviewed yet: use at your own risk!

satin.remotelauncher
Class RemoteLauncher

java.lang.Object
  |
  +--satin.aro.AROremoteServer
        |
        +--satin.remotelauncher.RemoteLauncher

public class RemoteLauncher
extends AROremoteServer

Provides facilities for performing operations on remote systems, by communicating with the Server program.

An object of class RemoteLauncher provides an API to a Server running on a remote system. The server, which must be started independently of this API, provides facilities for launching applications and manipulating files on the remote system.

Author:

Ed Stauff

Fields inherited from class satin.aro.AROremoteServer

aroLog, debugStream, defaultAROlog, defaultTimeout, server, uiLog

Constructor Summary

RemoteLauncher(java.lang.String hostName, int port)
Constructs a remote launcher and establishes communication with a Remote Launcher server.

Method Summary

RemoteTestbedParamSet	_getParams() Returns a bag of parameters from the remote system.
static RemoteLauncher	connect(java.lang.String hostName, int port) Constructs a remote launcher and establishes communication with a Remote Launcher server.
static RemoteLauncher	connect(TestbedParamSet paramSet) Constructs a remote launcher and establishes communication with a Remote Launcher server.
void	debug(boolean on) Enables or disables debugging output in the RemoteLauncher server.
RemoteProcess	exec(java.lang.String command) Executes the given command on the remote system.
RemoteProcess	exec(java.lang.String command, java.lang.String[] envVars, java.lang.String workingDir) Executes the given command on the remote system.
int	exec(java.lang.String command, java.lang.String[] envVars, java.lang.String workingDir, java.lang.StringBuffer stdOut, java.lang.StringBuffer stdErr) Executes the given command on the remote system and waits for it to complete.
int	exec(java.lang.String command, java.lang.StringBuffer stdOut, java.lang.StringBuffer stdErr) Executes the given command on the remote system and waits for it to complete.

Methods inherited from class satin.aro.AROremoteServer

close, exists, finalize, getClassName, getClassNames, getCumReqTime, getGlobalSubroutineNames, getMethodNames, getServerID, makeRequest, makeRequestAndThrow, makeRequestAndThrow, sleep

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RemoteLauncher

public RemoteLauncher(java.lang.String hostName,
                      int port)
               throws java.io.IOException,
                      AROexception

Constructs a remote launcher and establishes communication with a Remote Launcher server. Use this constructor when you have a host name and port handy. You can also use connect to construct a remote launcher object.

Parameters:

hostName

name of the host on which the Remote Launcher Server is running.

port

the port on which the Remote Launcher Server is listening.

Method Detail

connect

public static RemoteLauncher connect(java.lang.String hostName,
                                     int port)
                              throws java.io.IOException,
                                     AROexception

Constructs a remote launcher and establishes communication with a Remote Launcher server. Returns null if it could not establish communication with the server.

connect

public static RemoteLauncher connect(TestbedParamSet paramSet)
                              throws java.io.IOException,
                                     AROexception,
                                     ParamError

Constructs a remote launcher and establishes communication with a Remote Launcher server. Use this method instead of the constructor when you are getting your host name and port from a testbed parameter set. The testbed parameter set must contain an application called "REMOTE_LAUNCHER", which must contain a string parameter named "MACHINE_NAME" and an integer parameter named "PORT".

Parameters:

paramSet

parameter set for the testbed on which the Remote Launcher Server is running.

exec

public RemoteProcess exec(java.lang.String command)
                   throws java.io.IOException,
                          AROexception

Executes the given command on the remote system. This method is implemented in the RemoteLauncher server by Runtime.exec. Note that the command is not automatically executed within a shell, so that features like i/o redirection (using angle brackets) will not work unless you issue a command that explicitly invokes a shell.

Parameters:

command

the command to execute on the remote system.

Returns:

an object representing the process on the remote system.

exec

public RemoteProcess exec(java.lang.String command,
                          java.lang.String[] envVars,
                          java.lang.String workingDir)
                   throws java.io.IOException,
                          AROexception

Executes the given command on the remote system. This method is implemented in the RemoteLauncher server by Runtime.exec. Note that the command is not automatically executed within a shell, so that features like i/o redirection (using angle brackets) will not work unless you issue a command that explicitly invokes a shell.

Parameters:

command

the command to execute on the remote system.

Returns:

an object representing the process on the remote system.

exec

public int exec(java.lang.String command,
                java.lang.StringBuffer stdOut,
                java.lang.StringBuffer stdErr)
         throws java.io.IOException,
                AROexception

Executes the given command on the remote system and waits for it to complete. This method is implemented in the RemoteLauncher server by SystemUtils.exec. Note that the command is not automatically executed within a shell, so that features like i/o redirection (using angle brackets) will not work unless you issue a command that explicitly invokes a shell.

Example

 RemoteLauncher rl; // initialization omitted for brevity 
 StringBuffer dirContents = new StringBuffer();
 StringBuffer error = new StringBuffer();
 if (0 != SystemUtils.exec("ls -l c:/temp", dirContents, error))
     throw new Error("ls failed: " + error);
 // dirContents now contains a directory listing of c:/temp
 

Parameters:

command

the command to execute on the remote system.

stdOut

if this parameter is not null, the standard output of the command will be appended to this string buffer.

stdErr

if this parameter is not null, the standard error output of the command will be appended to this string buffer.

Returns:

the exit code from the process (normally 0 on success).

exec

public int exec(java.lang.String command,
                java.lang.String[] envVars,
                java.lang.String workingDir,
                java.lang.StringBuffer stdOut,
                java.lang.StringBuffer stdErr)
         throws java.io.IOException,
                AROexception

Executes the given command on the remote system and waits for it to complete. This method is implemented in the RemoteLauncher server by SystemUtils.exec. Note that the command is not automatically executed within a shell, so that features like i/o redirection (using angle brackets) will not work unless you issue a command that explicitly invokes a shell.

Example

 RemoteLauncher rl; // initialization omitted for brevity 
 StringBuffer dirContents = new StringBuffer();
 StringBuffer error = new StringBuffer();
 if (0 != SystemUtils.exec("ls -l c:/temp", dirContents, error))
     throw new Error("ls failed: " + error);
 // dirContents now contains a directory listing of c:/temp
 

Parameters:

command

the command to execute on the remote system.

envVars

an array of strings, each of which contains an environment variable setting of the form name=value. If this parameter is null, the subprocess (command) inherits its environment from the caller.

workingDir

the name of the working directory for the command. If this parameter is null, the subprocess (command) inherits its working directory from the caller.

stdOut

if this parameter is not null, the standard output of the command will be appended to this string buffer.

stdErr

if this parameter is not null, the standard error output of the command will be appended to this string buffer.

Returns:

the exit code from the process (normally 0 on success).

_getParams

public RemoteTestbedParamSet _getParams()
                                 throws java.io.IOException,
                                        AROexception

Returns a bag of parameters from the remote system. This is intended only for use by the Parameters package.

Returns:

the parameters object, or null if there are no parameters.

debug

public void debug(boolean on)
           throws java.io.IOException,
                  AROexception

Enables or disables debugging output in the RemoteLauncher server.

Parameters:

on

true to turn debugging on, false to turn it off.

Revision History

7/25/01 Ed Stauff - added connect(String, int).

6/19/01 Ed Stauff - made changes per API review.

4/17/01 Ed Stauff - file created.