com.sun.faban.harness
Class RunContext

java.lang.Object
  extended by 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 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

exec

public static CommandHandle exec(Command c)
                          throws IOException,
                                 InterruptedException
Executes a command on the local system. This is one of the two 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