com.sun.faban.harness
Class RunContext

java.lang.Object
  com.sun.faban.harness.RunContext

public class RunContext
extends Object

The RunContext provides callbacks into the harness and the run environment. All methods are static and it is suitable for static imports making calls much shorter and easier. RunContext calls are available during a run on the master. With exception to two methods, calling RunContext methods from tools or inside RemoteCallable.call() will result in a NullPointerException. The two methods callable from the agent are the local versions of RunContext.exec() and RunContext.java(). These are the signatures without a host name.

Author:

Akara Sucharitakul

Constructor Summary

RunContext()

Method Summary

static boolean	deleteFile(String hostName, String fileName) Deletes a file on a remote host.
static boolean	deleteFiles(String hostName, String dir, FileFilter filter) Deletes files on a target remote host.
static CommandHandle	exec(Command c) Executes a command on the local system.
static CommandHandle[]	exec(String[] hosts, Command c) Executes a command on a set of remote hosts.
static <V extends Serializable> List<V>	exec(String[] hosts, RemoteCallable<V> callable) Execute a code block defined as a RemoteCallable on a set of remote hosts.
static CommandHandle	exec(String host, Command c) Executes a command on a remote host.
static <V extends Serializable> V	exec(String host, RemoteCallable<V> callable) Execute a code block defined as a RemoteCallable on a remote host.
static boolean	exists(String hostName, String fileName) Checks whether the given remote file exists.
static String	getBenchmarkDir() Obtains the benchmark deployment directory.
static boolean	getFile(String hostName, String fileName, String localFileName) Gets/copies a file from a remote host.
static String	getHostName(String host) Obtains the actual host name of a host.
static String	getMaster() Obtains the name of the master machine.
static String	getMasterIP() Returns the ip address of the master.
static String	getMasterIP(String agentHost) Returns the ip address of the master's interface best used for communicating with the target host.
static String	getOutDir() Obtains the output directory for this run.
static String	getParamFile() Obtains the parameter/config file path for this run.
static ParamRepository	getParamRepository() Obtains the param repository for this run.
static String	getRunId() Obtains the full name of the run in the form benchmark.id.
static String	getRunSeq() Obtains the sequence part of the run id.
static String	getTmpDir(String host) Obtains the tmp directory used by Faban on the target host.
static boolean	isDirectory(String hostName, String fileName) Checks whether the given remote file exists and is a directory.
static boolean	isFile(String hostName, String fileName) Checks whether the given remote file exists and is a normal file.
static CommandHandle	java(Command java) Executes a java command on the local system.
static CommandHandle[]	java(String[] hosts, Command java) Executes a java command on a set of remote hosts.
static CommandHandle	java(String host, Command java) Executes a java command on a remote host.
static boolean	pushFile(String fileName, String destHost, String destFile) Pushes a local file on the Faban master to the remote host.
static boolean	truncateFile(String hostName, String fileName) Truncates a file on a remote host.
static String	which(String c) Returns the location of this command on the local system.
static String[]	which(String[] hosts, String c) Returns the location of this command on the target systems.
static String	which(String host, String c) Returns the location of this command on the target system.
static boolean	writeFileToStream(String hostName, String fileName, OutputStream stream) Reads a file from a remote host and writes the contents to a given output stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

RunContext

public RunContext()

Method Detail

getBenchmarkDir

public static String getBenchmarkDir()

Obtains the benchmark deployment directory.

Returns:

The benchmark deployment directory

getRunSeq

public static String getRunSeq()

Obtains the sequence part of the run id.

Returns:

The run sequence

getRunId

public static String getRunId()

Obtains the full name of the run in the form benchmark.id.

Returns:

The run name

getOutDir

public static String getOutDir()

Obtains the output directory for this run.

Returns:

The run output directory

getTmpDir

public static String getTmpDir(String host)

Obtains the tmp directory used by Faban on the target host. This may not be the same as the local one. Each OS is different and the tmpdir for the web container is also different.

Parameters:

host - The host to obtain the tmp dir, or null for local JVM

Returns:

The tmp directory

getParamRepository

public static ParamRepository getParamRepository()

Obtains the param repository for this run.

Returns:

The param repository

getParamFile

public static String getParamFile()

Obtains the parameter/config file path for this run.

Returns:

The parameter file path

which

public static String which(String c)
                    throws IOException

Returns the location of this command on the local system. This is one of the few methods callable from tools and RemoteCallable.call(). Similar to the which shell command, 'which' returns the actual path to the given command. If it maps to a series of commands, they will be returned as a single string separated by spaces. Note that 'which' does not actually try to check the underlying system for commands in the search path. It only checks the Faban infrastructure for existence of such a command.

Parameters:

c - The command to search for

Returns:

The actual command to execute, or null if not found.

Throws:

IOException - If there is a communication error to the remote agent

which

public static String which(String host,
                           String c)
                    throws IOException

Returns the location of this command on the target system. Similar to the which shell command, 'which' returns the actual path to the given command. If it maps to a series of commands, they will be returned as a single string separated by spaces. Note that 'which' does not actually try to check the underlying system for commands in the search path. It only checks the Faban infrastructure for existence of such a command.

Parameters:

host - The host to search

c - The command to search for

Returns:

The actual command to execute, or null if not found.

Throws:

IOException - If there is a communication error to the remote agent

which

public static String[] which(String[] hosts,
                             String c)

Returns the location of this command on the target systems. Similar to the which shell command, 'which' returns the actual path to the given command. If it maps to a series of commands, they will be returned as a single string separated by spaces. Note that 'which' does not actually try to check the underlying system for commands in the search path. It only checks the Faban infrastructure for existence of such a command.

Parameters:

hosts - The hosts to search

c - The command to search for

Returns:

The actual command paths to execute, or null elements if not found.

exec

public static CommandHandle exec(Command c)
                          throws IOException,
                                 InterruptedException

Executes a command on the local system. This is one of the few methods callable from tools and RemoteCallable.call().

Parameters:

c - The command to be executed

Returns:

A handle to the command

Throws:

IOException - Error communicating with resulting process

InterruptedException - Thread got interrupted waiting

exec

public static CommandHandle exec(String host,
                                 Command c)
                          throws IOException,
                                 InterruptedException

Executes a command on a remote host.

Parameters:

host - The target machine to execute the command

c - The command to be executed

Returns:

A handle to the command

Throws:

IOException - Error communicating with resulting process

InterruptedException - Thread got interrupted waiting

exec

public static CommandHandle[] exec(String[] hosts,
                                   Command c)
                            throws IOException,
                                   InterruptedException

Executes a command on a set of remote hosts.

Parameters:

hosts - The target machines to execute the command

c - The command to be executed

Returns:

Handles to the command on each of the target machines

Throws:

IOException - Error communicating with resulting process

InterruptedException - Thread got interrupted waiting

java

public static CommandHandle java(Command java)
                          throws IOException,
                                 InterruptedException

Executes a java command on the local system. This is one of the two methods callable from tools and RemoteCallable.call().

Parameters:

java - The command to be executed

Returns:

A handle to the command

Throws:

IOException - Error communicating with resulting process

InterruptedException - Thread got interrupted waiting

java

public static CommandHandle java(String host,
                                 Command java)
                          throws IOException,
                                 InterruptedException

Executes a java command on a remote host.

Parameters:

host - The target machine to execute the command

java - The command to be executed

Returns:

A handle to the command

Throws:

IOException - Error communicating with resulting process

InterruptedException - Thread got interrupted waiting

java

public static CommandHandle[] java(String[] hosts,
                                   Command java)
                            throws IOException,
                                   InterruptedException

Executes a java command on a set of remote hosts.

Parameters:

hosts - The target machines to execute the command

java - The command to be executed

Returns:

Handles to the command on each of the target machines

Throws:

IOException - Error communicating with resulting process

InterruptedException - Thread got interrupted waiting

exec

public static <V extends Serializable> V exec(String host,
                                              RemoteCallable<V> callable)
                                   throws Exception

Execute a code block defined as a RemoteCallable on a remote host. The only RunContext methods available to the code block are the local exec and java calls. All other calls to RunContext will result in a NullPointerException.

Parameters:

host - The remote host

callable - The callable defining the code block

Returns:

The result of the callable

Throws:

Exception - An error occurred making the call

exec

public static <V extends Serializable> List<V> exec(String[] hosts,
                                                    RemoteCallable<V> callable)
                                         throws Exception

Execute a code block defined as a RemoteCallable on a set of remote hosts. The only RunContext methods available to the code block are the local exec and java calls. All other calls to RunContext will result in a NullPointerException.

Parameters:

hosts - The remote hosts

callable - The callable defining the code block

Returns:

The result of the callable

Throws:

Exception - An error occurred making the call

getMaster

public static String getMaster()

Obtains the name of the master machine.

Returns:

The name of the master machine

getMasterIP

public static String getMasterIP()

Returns the ip address of the master.

Returns:

The ip address of the master

getMasterIP

public static String getMasterIP(String agentHost)

Returns the ip address of the master's interface best used for communicating with the target host.

Parameters:

agentHost - The target host

Returns:

The ip address of the master

getHostName

public static String getHostName(String host)

Obtains the actual host name of a host. In most cases, the configuration refers to a host with the interface name. If the host has multiple interfaces, the interface name is not the same as the host name. This method tries to detect the true hostname given a host or interface name.

Parameters:

host - The known host name

Returns:

The true host name

pushFile

public static boolean pushFile(String fileName,
                               String destHost,
                               String destFile)

Pushes a local file on the Faban master to the remote host. If a relative path is given for the filename (local file), it is looked up in the run directory.

Parameters:

fileName - The source file name

destHost - The destination machine

destFile - The destination file name

Returns:

true if successful, false otherwise

deleteFile

public static boolean deleteFile(String hostName,
                                 String fileName)

Deletes a file on a remote host.

Parameters:

hostName - The remote host name

fileName - The file name

Returns:

true if successful, false otherwise

deleteFiles

public static boolean deleteFiles(String hostName,
                                  String dir,
                                  FileFilter filter)

Deletes files on a target remote host.

Parameters:

hostName - The remote host name

dir - The file name

filter - The file name filter

Returns:

true if successful, false otherwise

truncateFile

public static boolean truncateFile(String hostName,
                                   String fileName)

Truncates a file on a remote host.

Parameters:

hostName - The remote host name

fileName - The file name

Returns:

true if successful, false otherwise

getFile

public static boolean getFile(String hostName,
                              String fileName,
                              String localFileName)

Gets/copies a file from a remote host. If a relative path is given for localFileName, the file will be placed in the current run output directory.

Parameters:

hostName - The remote host name

fileName - The file name on the remote host

localFileName - The target file name on the local host

Returns:

true if successful, false otherwise

exists

public static boolean exists(String hostName,
                             String fileName)

Checks whether the given remote file exists.

Parameters:

hostName - The host name to check.

fileName - The file name to test.

Returns:

true if exists, false otherwise.

isFile

public static boolean isFile(String hostName,
                             String fileName)

Checks whether the given remote file exists and is a normal file.

Parameters:

hostName - The host name to check.

fileName - The file name to test.

Returns:

true if file is a normal file, false otherwise.

isDirectory

public static boolean isDirectory(String hostName,
                                  String fileName)

Checks whether the given remote file exists and is a directory.

Parameters:

hostName - The host name to check.

fileName - The file name to test.

Returns:

true if file is a directory, false otherwise.

writeFileToStream

public static boolean writeFileToStream(String hostName,
                                        String fileName,
                                        OutputStream stream)

Reads a file from a remote host and writes the contents to a given output stream. This method is useful for filtering the content of a remote file through a filtering stream.

Parameters:

hostName - The remote host name

fileName - The file name on the remote host

stream - The stream to output the data to

Returns:

true if successful, false otherwise