com.sun.javatest
Class Script

java.lang.Object
  extended by com.sun.javatest.Script
Direct Known Subclasses:
APIScript, KeywordScript, ReportScript, StdTestScript

public abstract class Script
extends java.lang.Object

Script is the abstract base class providing the ability to control how a test is to be compiled and executed. In addition to the primary method, run, it has many methods that can be used by subtype classes to assist them in performing a test.


Nested Class Summary
static interface Script.TimeoutProvider
          Interface for extended testTimeout control.
 
Field Summary
protected static Timer alarmTimer
          A timer that may be used to set up timeouts.
protected  BackupPolicy backupPolicy
          A backup policy object that specifies how files should be backed up, if a file is found to exist when a new one of the same name is to be written.
protected  java.lang.String cmdOut1Name
          The default name for the TestResult section used to save the data written to the out1 stream for a command.
protected  java.lang.String cmdOut2Name
          The default name for the TestResult section used to save the data written to the out2 stream for a command.
protected  TestEnvironment env
          The test environment for the test being performed.
protected static Status error_badExecuteArgs
          A status that may be used to indicate problems in the executeArgs field of a test description.
protected static Status error_badTestClassDir
          A status that may be used to indicate a problem with a test's class directory.
protected static Status error_compFailUnexp
          A status that may be used to indicate that a compilation failed unexpectedly.
protected static Status error_noActionSpecified
          A status that may be used to indicate that no action was specified.
protected static Status error_noExecuteClass
          A status that may be used to indicate that no execute class was specified in a test description.
protected static Status error_noExtnInSource
          A status that may be used to indicate that no extension was found in a source file.
protected static Status error_noRMIClasses
          A status that may be used to indicate that no rmi classes were specified in a test description.
protected static Status error_noSource
          A status that may be used to indicate that no sources were specified in a test description.
protected  java.lang.String[] excludedTestCases
          The set of test cases to be excluded for this test.
protected static Status fail_compFailUnexp
          A status that may be used to indicate the a compilation failed unexpectedly.
protected static Status fail_compSuccUnexp
          A status that may be used to indicate that a compilation did not fail as was expected.
protected static Status fail_execSuccUnexp
          A status that may be used to indicate that a test execution step did not fail as wqas expected.
protected  java.lang.ClassLoader loader
          The class loader to be used to load additional user-specified classes as required in the execution of the script.
protected static Status noExtnInSource
          A status that may be used to indicate that no extension was found in a source file.
protected static Status noSource
          A status that may be used to indicate that no source files were found in the test description.
protected  Harness.Observer notifier
          Notifier of starting/finishing tests.
protected static Status pass_compFailExp
          A status that may be used to indicate that a compilation failed as expected.
protected static Status pass_compSuccExp
          A status that may be used to indicate that a compilation succeeded as expected.
protected static Status pass_execFailExp
          A status that may be used to indicate that an execution step failed, as was expected.
protected  java.lang.String[] scriptArgs
          The initialization args for the script.
protected  TestDescription td
          The test description for the test being performed.
protected  java.io.PrintWriter trOut
          The reporting channel for the test being performed.
protected  WorkDirectory workDir
          The work directory for the test run.
 
Constructor Summary
Script()
           
 
Method Summary
protected  Status compileIfNecessary(java.io.File[] srcs, java.lang.String classDir)
          Compile those source files for which the corresponding class file appears to be out of date.
protected  Status compileIfNecessary(java.lang.String[] srcs, java.lang.String classDir)
          Compile those source files for which the corresponding class file appears to be out of date.
protected  Status compileIfNecessary(java.lang.String command, java.io.File[] srcs, java.lang.String classDir)
          Compile those source files for which the corresponding class file appears to be out of date.
protected  Status compileIfNecessary(java.lang.String command, java.lang.String[] srcs, java.lang.String classDir)
          Compile those source files for which the corresponding class file appears to be out of date.
protected  Status compileIndividually(java.io.File[] srcs)
          Compile the given source files individually.
protected  Status compileIndividually(java.lang.String[] srcs)
          Compile the given source files individually.
protected  Status compileIndividually(java.lang.String command, java.io.File[] srcs)
          Compile the given source files individually.
protected  Status compileIndividually(java.lang.String command, java.lang.String[] srcs)
          Compile the given source files individually.
protected  Status compileOne(java.io.File src)
          Compiles the given source file.
protected  Status compileOne(java.lang.String src)
          Compile the given source file.
protected  Status compileOne(java.lang.String command, java.io.File src)
          Compiles the given source file.
protected  Status compileOne(java.lang.String command, java.lang.String src)
          Compile the given source file.
protected  Status compileTogether(java.io.File[] srcs)
          Compile the given source files together.
protected  Status compileTogether(java.lang.String[] srcs)
          Compile the given source files together.
protected  Status compileTogether(java.lang.String command, java.io.File[] srcs)
          Compile the given source files together.
protected  Status compileTogether(java.lang.String command, java.lang.String[] srcs)
          Compile the given source files together.
protected  java.lang.String[] exclude(java.lang.String[] args, java.lang.String[] testCases)
          Modify the args for a test to be executed, according to a set of test cases to be excluded.
protected  Status execute(java.lang.String executeClass, java.lang.String executeArgs)
          Execute the given class with the given arguments, which need to be passed to the environment for $ substitution and for splitting into separate strings.
protected  Status execute(java.lang.String executeClass, java.lang.String[] executeArgs)
          Execute the given class with the given arguments.
protected  Status execute(java.lang.String command, java.lang.String executeClass, java.lang.String executeArgs)
          Execute the given class with the given arguments, which need to be passed to the environment for $ substitution and for splitting into separate strings.
protected  Status execute(java.lang.String command, java.lang.String executeClass, java.lang.String[] executeArgs)
          Execute the given class with the given arguments.
protected static java.lang.String[] filesToStrings(java.io.File[] files)
          Utility routine to convert an array of filenames to a corresponding array of strings.
 boolean getJTRIfPassed()
          Get the flag that indicates whether a result (.jtr) file should be written even if the test has passed.
 TestDescription getTestDescription()
          Get the test description for the test which this script will run.
 TestResult getTestResult()
          Get the test result object to be used for the results of the test run.
protected  int getTestTimeout()
          Get the timeout to be used for a test.
 Script.TimeoutProvider getTimeoutProvider()
          Getter for TimeoutProvider.
 void initArgs(java.lang.String[] args)
          Initialize any custom args for the script.
 void initBackupPolicy(BackupPolicy backupPolicy)
          Initialize the backup policy to be used when creating a test result file in which to store the results of running this test.
 void initClassLoader(java.lang.ClassLoader loader)
          Initialize the class loader for any commands to be loaded.
protected  void initDelegate(Script s, java.lang.String[] scriptArgs)
          Initialize a delegate script object.
 void initExcludedTestCases(java.lang.String[] excludedTestCases)
          Initialize the list of test cases to be excluded from the test.
 void initTestDescription(TestDescription td)
          Initialize the test description to be run by the script.
 void initTestEnvironment(TestEnvironment env)
          Initialize the environment to be used when running the test.
protected  void initTestResult(TestResult tr)
          Initialize the test result for the result of the script execution.
 void initWorkDir(WorkDirectory workDir)
          Initialize the work directory to be used to store the results obtained when running the test, and to store any temporary files that may be required by the test.
protected  Status invokeCommand(java.lang.String key)
          Invoke a command in the environment identified by a given key.
protected  Status rmiCompile(java.lang.String[] classes)
          RMI Compile the given class files.
protected  Status rmiCompile(java.lang.String command, java.lang.String[] classes)
          RMI Compile the given class files.
 void run()
          Run the script, to fill out the test results for the test description given to init.
abstract  Status run(java.lang.String[] args, TestDescription td, TestEnvironment env)
          The primary method to be provided by Scripts.
protected  void setAlarm(int timeout)
          Set an alarm that will interrupt the calling thread after a specified delay (in milliseconds), and repeatedly thereafter until cancelled.
protected  void setAlarm(int timeout, java.lang.Thread threadToInterrupt)
          Set an alarm that will interrupt a given thread after a specified delay (in milliseconds), and repeatedly thereafter until cancelled.
protected  void setDefaultCommandStreamNames(java.lang.String out1Name, java.lang.String out2Name)
          Set the default names of the two default output streams used when executing a command.
 void setJTRIfPassed(boolean b)
          Set the flag that indicates whether a result (.jtr) file should be written even if the test has passed.
 void setNotifier(Harness.Observer notifier)
          Sets notifier to be used to inform listeners of events of a test starting/finishing.
 void setTimeoutProvider(Script.TimeoutProvider provider)
          Set TimeoutProvider used to control test timeouts.
 boolean useNotifier()
          Returns true if the Script uses own way of notifying the Harness of starting/finishing test, false otherwise (by default).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

td

protected TestDescription td
The test description for the test being performed.


excludedTestCases

protected java.lang.String[] excludedTestCases
The set of test cases to be excluded for this test.


env

protected TestEnvironment env
The test environment for the test being performed.


scriptArgs

protected java.lang.String[] scriptArgs
The initialization args for the script.


workDir

protected WorkDirectory workDir
The work directory for the test run.


cmdOut1Name

protected java.lang.String cmdOut1Name
The default name for the TestResult section used to save the data written to the out1 stream for a command.

See Also:
Command.run(java.lang.String[], java.io.PrintWriter, java.io.PrintWriter)

cmdOut2Name

protected java.lang.String cmdOut2Name
The default name for the TestResult section used to save the data written to the out2 stream for a command.

See Also:
Command.run(java.lang.String[], java.io.PrintWriter, java.io.PrintWriter)

backupPolicy

protected BackupPolicy backupPolicy
A backup policy object that specifies how files should be backed up, if a file is found to exist when a new one of the same name is to be written.


loader

protected java.lang.ClassLoader loader
The class loader to be used to load additional user-specified classes as required in the execution of the script.


trOut

protected java.io.PrintWriter trOut
The reporting channel for the test being performed.


error_badExecuteArgs

protected static final Status error_badExecuteArgs
A status that may be used to indicate problems in the executeArgs field of a test description.


error_badTestClassDir

protected static final Status error_badTestClassDir
A status that may be used to indicate a problem with a test's class directory.


error_compFailUnexp

protected static final Status error_compFailUnexp
A status that may be used to indicate that a compilation failed unexpectedly.


error_noActionSpecified

protected static final Status error_noActionSpecified
A status that may be used to indicate that no action was specified.


error_noExecuteClass

protected static final Status error_noExecuteClass
A status that may be used to indicate that no execute class was specified in a test description.


error_noExtnInSource

protected static final Status error_noExtnInSource
A status that may be used to indicate that no extension was found in a source file.


error_noRMIClasses

protected static final Status error_noRMIClasses
A status that may be used to indicate that no rmi classes were specified in a test description.


error_noSource

protected static final Status error_noSource
A status that may be used to indicate that no sources were specified in a test description.


fail_compFailUnexp

protected static final Status fail_compFailUnexp
A status that may be used to indicate the a compilation failed unexpectedly.


fail_compSuccUnexp

protected static final Status fail_compSuccUnexp
A status that may be used to indicate that a compilation did not fail as was expected.


fail_execSuccUnexp

protected static final Status fail_execSuccUnexp
A status that may be used to indicate that a test execution step did not fail as wqas expected.


pass_compFailExp

protected static final Status pass_compFailExp
A status that may be used to indicate that a compilation failed as expected.


pass_compSuccExp

protected static final Status pass_compSuccExp
A status that may be used to indicate that a compilation succeeded as expected.


pass_execFailExp

protected static final Status pass_execFailExp
A status that may be used to indicate that an execution step failed, as was expected.


noSource

protected static final Status noSource
A status that may be used to indicate that no source files were found in the test description.


noExtnInSource

protected static final Status noExtnInSource
A status that may be used to indicate that no extension was found in a source file.


alarmTimer

protected static Timer alarmTimer
A timer that may be used to set up timeouts.


notifier

protected Harness.Observer notifier
Notifier of starting/finishing tests. Initialized only when useNotifer() returns true.

Since:
4.2.1
See Also:
useNotifier(), setNotifier(com.sun.javatest.Harness.Observer)
Constructor Detail

Script

public Script()
Method Detail

initArgs

public void initArgs(java.lang.String[] args)
Initialize any custom args for the script.

Parameters:
args - custom args for the script

initTestDescription

public void initTestDescription(TestDescription td)
Initialize the test description to be run by the script. In addition, a mutable test result is set up, in which the results of running the test can be recorded by the script.

Parameters:
td - the test description for the test to be run

initExcludedTestCases

public void initExcludedTestCases(java.lang.String[] excludedTestCases)
Initialize the list of test cases to be excluded from the test. The script is responsible for determining how to instruct the test not to run these test cases. A recommended convention is to pass the list of test cases to the test using a -exclude option.

Parameters:
excludedTestCases - a list of test cases within the test that should not be run

initTestEnvironment

public void initTestEnvironment(TestEnvironment env)
Initialize the environment to be used when running the test.

Parameters:
env - the environment to be used when running the test

initWorkDir

public void initWorkDir(WorkDirectory workDir)
Initialize the work directory to be used to store the results obtained when running the test, and to store any temporary files that may be required by the test.

Parameters:
workDir - the work directory to be used to store the test's results.

initBackupPolicy

public void initBackupPolicy(BackupPolicy backupPolicy)
Initialize the backup policy to be used when creating a test result file in which to store the results of running this test.

Parameters:
backupPolicy - A backup policy object to be used when creating test result files.

initClassLoader

public void initClassLoader(java.lang.ClassLoader loader)
Initialize the class loader for any commands to be loaded.

Parameters:
loader - a class loader to be used to load any commands or other user-specified classes that may be required.

initDelegate

protected void initDelegate(Script s,
                            java.lang.String[] scriptArgs)
Initialize a delegate script object. This should only be used in exceptional circumstances, and is mostly provided for historical purposes.

Parameters:
s - The delegate to be initialized
scriptArgs - the arguments to be passed to the delegate object

initTestResult

protected void initTestResult(TestResult tr)
Initialize the test result for the result of the script execution. Normally, a test result is initialized as a side effect of calling initTestDescription. This method should only be called is special circumstances, and is mostly provided for historical purposes.

Parameters:
tr - The test result to set as the result of the script's execution.
Throws:
java.lang.IllegalStateException - if the test result has already been set.
See Also:
initTestDescription(com.sun.javatest.TestDescription)

run

public void run()
Run the script, to fill out the test results for the test description given to init. Most implementations will use the default implementation of this method, which delegates to a simpler (abstract) method @link(run(String[],TestDescription, TestEnvironment))


run

public abstract Status run(java.lang.String[] args,
                           TestDescription td,
                           TestEnvironment env)
The primary method to be provided by Scripts. It is responsible for compiling and executing the test appropiately. Normally, a script should call `init' and then decode any script-specific options it is given in `args'. It should then examine the test description it is given so that it can compile and execute the test as appropriate. Various convenience routines are provided to simplify the task of running the compiler, an interpreter or any other commands, which can be specified in a flexible manner by properties in the TestEnvironment.

Parameters:
args - Any script-specific options specified in the script property
td - The test description for the test to be performed
env - The test environment giving the details of how to run the test
Returns:
The result of running the script
See Also:
compileIndividually(java.lang.String[]), compileTogether(java.lang.String[]), execute(java.lang.String, java.lang.String), invokeCommand(java.lang.String)

getTestDescription

public TestDescription getTestDescription()
Get the test description for the test which this script will run.

Returns:
the test description for the test which this script will run.

getTestResult

public TestResult getTestResult()
Get the test result object to be used for the results of the test run.

Returns:
the test result object to be used for the results of the test run.

getJTRIfPassed

public boolean getJTRIfPassed()
Get the flag that indicates whether a result (.jtr) file should be written even if the test has passed. By default, this is true.

Returns:
the flag that indicates whether a result (.jtr) file should be written even if the test has passed.
See Also:
setJTRIfPassed(boolean)

setJTRIfPassed

public void setJTRIfPassed(boolean b)
Set the flag that indicates whether a result (.jtr) file should be written even if the test has passed. By default, this is true.

Parameters:
b - the flag that indicates whether a result (.jtr) file should be written even if the test has passed.
See Also:
getJTRIfPassed()

setAlarm

protected void setAlarm(int timeout)
Set an alarm that will interrupt the calling thread after a specified delay (in milliseconds), and repeatedly thereafter until cancelled. Typical usage:
 try {
     setAlarm(delay);
     ...
 }
 finally {
     setAlarm(0);
 }
 

Parameters:
timeout - the interval (in milliseconds) after which the calling thread will be interrupted, if not cancelled in the meantime.

setAlarm

protected void setAlarm(int timeout,
                        java.lang.Thread threadToInterrupt)
Set an alarm that will interrupt a given thread after a specified delay (in milliseconds), and repeatedly thereafter until cancelled. Typical usage:
 try {
     setAlarm(delay);
     ...
 }
 finally {
     setAlarm(0);
 }
 

Parameters:
timeout - the interval (in milliseconds) after which the calling thread will be interrupted, if not cancelled in the meantime.
threadToInterrupt - which thread to interrupt

setTimeoutProvider

public void setTimeoutProvider(Script.TimeoutProvider provider)
Set TimeoutProvider used to control test timeouts.

Parameters:
provider - null to use default test timeout value (10 sec).
See Also:
Script.TimeoutProvider, getTestTimeout(), getTimeoutProvider()

getTimeoutProvider

public Script.TimeoutProvider getTimeoutProvider()
Getter for TimeoutProvider. Generates default (10*factor) provider in case no provider is set

Returns:
TimeoutProvider set to Script. Returns default TimeoutProvider in case no TimeoutProvider is set (or it is set to null). The default implementation is 10 minutes scaled by a value found in the environment ("javatestTimeoutFactor").
See Also:
setTimeoutProvider(com.sun.javatest.Script.TimeoutProvider), getTestTimeout(), Script.TimeoutProvider

getTestTimeout

protected int getTestTimeout()
Get the timeout to be used for a test. Uses TimeoutProvider to get test timeout value. The default implementation of TimeoutProvider is 10 minutes scaled by a value found in the environment ("javatestTimeoutFactor"). This method can be overriden to provide different behaviors. A value of zero means no timeout.

Returns:
the number of seconds in which the test is expected to complete its execution.
See Also:
getTimeoutProvider(), setTimeoutProvider(com.sun.javatest.Script.TimeoutProvider), Script.TimeoutProvider

compileIndividually

protected Status compileIndividually(java.lang.String[] srcs)
Compile the given source files individually. One at a time, each source file is passed to compileTogether, until they have all been successfully compiled, or until one fails to compile.

Parameters:
srcs - The names of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

compileIndividually

protected Status compileIndividually(java.lang.String command,
                                     java.lang.String[] srcs)
Compile the given source files individually. One at a time, each source file is passed to compileTogether, until they have all been successfully compiled, or until one fails to compile.

Parameters:
command - the base name of the command entry in the environment to be used to compile any necessary sources. The complete entry name will be command.command.extn
srcs - The names of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

compileIndividually

protected Status compileIndividually(java.io.File[] srcs)
Compile the given source files individually. One at a time, each source file is passed to compileTogether, until they have all been successfully compiled, or until one fails to compile.

Parameters:
srcs - The names of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

compileIndividually

protected Status compileIndividually(java.lang.String command,
                                     java.io.File[] srcs)
Compile the given source files individually. One at a time, each source file is passed to compileTogether, until they have all been successfully compiled, or until one fails to compile.

Parameters:
command - the base name of the command entry in the environment to be used to compile any necessary sources. The complete entry name will be command.command.extn
srcs - The names of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

compileOne

protected Status compileOne(java.lang.String src)
Compile the given source file.

Parameters:
src - The name of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

compileOne

protected Status compileOne(java.lang.String command,
                            java.lang.String src)
Compile the given source file. The file is treated as a singleton group and passed to compileTogether.

Parameters:
command - the base name of the command entry in the environment to be used to compile any necessary sources. The complete entry name will be command.command.extn
src - The name of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

compileOne

protected Status compileOne(java.io.File src)
Compiles the given source file.

Parameters:
src - The name of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

compileOne

protected Status compileOne(java.lang.String command,
                            java.io.File src)
Compiles the given source file.

Parameters:
command - the base name of the command entry in the environment to be used to compile any necessary sources. The complete entry name will be command.command.extn
src - The name of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

compileTogether

protected Status compileTogether(java.lang.String[] srcs)
Compile the given source files together. The compiler and arguments to be used are identified by the `env.env.compile.extn.*' properties in the script's environment, where env is the name of the environment specified to the GUI, and extn is the extension of the first source file. The names of the files to be compiled are added to the end of the arguments retrieved from the environment.

Parameters:
srcs - The names of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
invokeCommand(java.lang.String)

compileTogether

protected Status compileTogether(java.lang.String command,
                                 java.lang.String[] srcs)
Compile the given source files together. The compiler and arguments to be used are identified by the `env.env.command.command.extn.*' properties in the script's environment, where env is the name of the environment specified to the GUI, and extn is the extension of the first source file. The names of the files to be compiled are added to the end of the arguments retrieved from the environment.

Parameters:
command - the base name of the command entry in the environment to be used to compile any necessary sources. The complete entry name will be command.command.extn
srcs - The names of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
invokeCommand(java.lang.String)

compileTogether

protected Status compileTogether(java.io.File[] srcs)
Compile the given source files together. The compiler and arguments to be used are identified by the `env.env.command.compile.extn.*' properties in the script's environment, where env is the name of the environment specified to the GUI, and extn is the extension of the first source file. The names of the files to be compiled are added to the end of the arguments retrieved from the environment.

Parameters:
srcs - The names of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
invokeCommand(java.lang.String)

compileTogether

protected Status compileTogether(java.lang.String command,
                                 java.io.File[] srcs)
Compile the given source files together. The compiler and arguments to be used are identified by the `env.env.command.command.extn.*' properties in the script's environment, where env is the name of the environment specified to the GUI, and extn is the extension of the first source file. The names of the files to be compiled are added to the end of the arguments retrieved from the environment.

Parameters:
command - the base name of the command entry in the environment to be used to compile any necessary sources. The complete entry name will be command.command.extn
srcs - The names of the file to be compiled.
Returns:
The status of the compilation: passed or failed.
See Also:
invokeCommand(java.lang.String)

compileIfNecessary

protected Status compileIfNecessary(java.lang.String[] srcs,
                                    java.lang.String classDir)
Compile those source files for which the corresponding class file appears to be out of date. Each source file is scanned to find a package statement to help determine the main class defined in the source file -- the corresponding class file in the given class directory is then checked, and if the source file is newer, it is put on a list to be recompiled. After checking all the source files, if any need to be recompiled, they will be compiled together, using the default compile command ("command.compile.extn") entry in the the environment.

Parameters:
srcs - The names of the source files to be compiled if necessary
classDir - The class directory in which the corresponding class files (if any) will be found.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

compileIfNecessary

protected Status compileIfNecessary(java.lang.String command,
                                    java.lang.String[] srcs,
                                    java.lang.String classDir)
Compile those source files for which the corresponding class file appears to be out of date. Each source file is scanned to find a package statement to help determine the main class defined in the source file -- the corresponding class file in the given class directory is then checked, and if the source file is newer, it is put on a list to be recompiled. After checking all the source files, if any need to be recompiled, they will be compiled together, using the specified compile command entry in the the environment.

Parameters:
command - the base name of the command entry in the environment to be used to compile any necessary sources. The complete entry name will be command.command.extn
srcs - The names of the source files to be compiled if necessary
classDir - The class directory in which the corresponding class files (if any) will be found.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

compileIfNecessary

protected Status compileIfNecessary(java.io.File[] srcs,
                                    java.lang.String classDir)
Compile those source files for which the corresponding class file appears to be out of date. Each source file is scanned to find a package statement to help determine the main class defined in the source file -- the corresponding class file in the given class directory is then checked, and if the source file is newer, it is put on a list to be recompiled. After checking all the source files, if any need to be recompiled, they will be compiled together, using the default compile command ("command.compile.extn") entry in the the environment.

Parameters:
srcs - The names of the source files to be compiled if necessary
classDir - The class directory in which the corresponding class files (if any) will be found.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

compileIfNecessary

protected Status compileIfNecessary(java.lang.String command,
                                    java.io.File[] srcs,
                                    java.lang.String classDir)
Compile those source files for which the corresponding class file appears to be out of date. Each source file is scanned to find a package statement to help determine the main class defined in the source file -- the corresponding class file in the given class directory is then checked, and if the source file is newer, it is put on a list to be recompiled. After checking all the source files, if any need to be recompiled, they will be compiled together, using the specified compile command entry in the the environment.

Parameters:
command - the base name of the command entry in the environment to be used to compile any necessary sources. The complete entry name will be command.command.extn
srcs - The names of the source files to be compiled if necessary
classDir - The class directory in which the corresponding class files (if any) will be found.
Returns:
The status of the compilation: passed or failed.
See Also:
compileTogether(java.lang.String[])

execute

protected Status execute(java.lang.String executeClass,
                         java.lang.String executeArgs)
Execute the given class with the given arguments, which need to be passed to the environment for $ substitution and for splitting into separate strings.

Parameters:
executeClass - The name of the class to be executed
executeArgs - The arguments to be evaluated before passing to the class to be executed
Returns:
The status of the execution
See Also:
execute(java.lang.String, java.lang.String, java.lang.String)

execute

protected Status execute(java.lang.String command,
                         java.lang.String executeClass,
                         java.lang.String executeArgs)
Execute the given class with the given arguments, which need to be passed to the environment for $ substitution and for splitting into separate strings.

Parameters:
command - The name of the command containing the template to be executed
executeClass - The name of the class to be executed
executeArgs - The arguments to be evaluated before passing to the class to be executed
Returns:
The status of the execution

execute

protected Status execute(java.lang.String executeClass,
                         java.lang.String[] executeArgs)
Execute the given class with the given arguments. The interpreter to be used and its arguments are identified by the `env.env.execute.*' properties in the script's environment, where env is the name of the environment specified to the GUI. The class to be executed and its arguments are added to the end of the arguments retrieved from the environment.

Parameters:
executeClass - The name of the class to be executed.
executeArgs - Any arguments to be passed to the class to be executed.
Returns:
The status of the execution
See Also:
execute(java.lang.String, java.lang.String, java.lang.String[])

execute

protected Status execute(java.lang.String command,
                         java.lang.String executeClass,
                         java.lang.String[] executeArgs)
Execute the given class with the given arguments. The interpreter to be used and its arguments are identified by the `env.env.command.*' properties in the script's environment, where env is the name of the environment specified to the GUI. The class to be executed and its arguments are added to the end of the arguments retrieved from the environment.

Parameters:
command - The name of the command containing the template to be executed
executeClass - The name of the class to be executed.
executeArgs - Any arguments to be passed to the class to be executed.
Returns:
The status of the execution
See Also:
invokeCommand(java.lang.String)

rmiCompile

protected Status rmiCompile(java.lang.String[] classes)
RMI Compile the given class files. The compiler and arguments to be used is identified by the `env.env.command.rmic' property in the script's environment, where env is the name of the environment specified to the GUI. The name of the classes to be compiled by rmic is obtained from the test description.

Parameters:
classes - The names of the classes to be compiled by rmic.
Returns:
The status of the compilation: passed or failed.
See Also:
invokeCommand(java.lang.String)

rmiCompile

protected Status rmiCompile(java.lang.String command,
                            java.lang.String[] classes)
RMI Compile the given class files. The compiler and arguments to be used is identified by the `env.env.command.command' property in the script's environment, where env is the name of the environment specified to the GUI. The name of the classes to be compiled by rmic is obtained from the test description.

Parameters:
command - The name of the command containing the template to be compiled
classes - The names of the classes to be compiled by rmic.
Returns:
The status of the compilation: passed or failed.
See Also:
invokeCommand(java.lang.String)

invokeCommand

protected Status invokeCommand(java.lang.String key)
Invoke a command in the environment identified by a given key. The command is identified by looking up `command.key' property in the environment. The first word of this property identifies the name of a class that should be an implementation of Command, and the subsequent words are the arguments to be passed to a fresh instance of that class, via its run method. Standard library implementations of Command are available, such as:
com.sun.javatest.lib.ProcessCommand
Execute a command in a separate process
com.sun.javatest.lib.ExecStdTestSameJVMCmd
Execute a standard test in the same JVM as JT Harness
com.sun.javatest.agent.PassiveAgentCommand
Execute a command on a remote machine
For full details, the documentation for the various appropriate classes.

The use of `command.key' supercedes an earlier mechanism involving multiple properties. For backwards compatibility, if the `command.key' property is not found, the properties for the earlier mechanism are checked as well.

Parameters:
key - The tag for the command to be executed
Returns:
A status giving the outcome of the command
See Also:
Command

setDefaultCommandStreamNames

protected void setDefaultCommandStreamNames(java.lang.String out1Name,
                                            java.lang.String out2Name)
Set the default names of the two default output streams used when executing a command. In many cases these may correspond to the UNIX-style standard-out and standard-error streams. This API does not define what they are used for though, and architects are encouraged to give descriptive names if possible.

Parameters:
out1Name - Name of the first stream.
out2Name - Name of the second stream.

exclude

protected java.lang.String[] exclude(java.lang.String[] args,
                                     java.lang.String[] testCases)
Modify the args for a test to be executed, according to a set of test cases to be excluded. If there are no test cases to be excluded, the result will be the original args unchanged; otherwise, the result will be the original args prefixed by "-exclude" and a comma-separated list of exclude test cases.

Parameters:
args - The basic list of args for the test
testCases - the set of test cases to be excluded, or null if none
Returns:
The original list of args, possibly prefixed by "-exclude" and a comma-separated list of test cases that should not be executed by the test

filesToStrings

protected static java.lang.String[] filesToStrings(java.io.File[] files)
Utility routine to convert an array of filenames to a corresponding array of strings.

Parameters:
files - The filenames to be converted
Returns:
The corresponding strings

useNotifier

public boolean useNotifier()
Returns true if the Script uses own way of notifying the Harness of starting/finishing test, false otherwise (by default). Normally the Harness notifies all listeners of an event of starting a test when the method run() is invoked and an event of finishing the test when the method run() is completed. Those Scripts which need to take a control over notifying should override this method to return true. In this case the notifier field will be initialized and the Harness will no longer notify the listeners when a test starts/stops.

Since:
4.2.1

setNotifier

public void setNotifier(Harness.Observer notifier)
Sets notifier to be used to inform listeners of events of a test starting/finishing. Invoked by the Harness iff useNotifier() returns true.

Since:
4.2.1
See Also:
useNotifier()


Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.