Class Script

java.lang.Object
com.sun.javatest.Script
Direct Known Subclasses:
APIScript, KeywordScript, ReportScript, StdTestScript
public abstract class Script extends 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.

  • Field Details

    • alarmTimer

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

    • 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.

    • 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.

    • pass_execFailExp

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

    • td

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

    • excludedTestCases

      protected 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 String[] scriptArgs
      The initialization args for the script.

    • workDir

      protected WorkDirectory workDir
      The work directory for the test run.

    • cmdOut1Name

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

    • cmdOut2Name

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

    • 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 ClassLoader loader
      The class loader to be used to load additional user-specified classes as required in the execution of the script.

    • trOut

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

    • notifier

      protected Harness.Observer notifier
      Notifier of starting/finishing tests. Initialized only when useNotifier() returns true.
      Since:
      4.2.1
      See Also:

  • Constructor Details

    • Script

      public Script()

  • Method Details

    • filesToStrings

      protected static String[] filesToStrings(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

    • initArgs

      public void initArgs(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(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(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, 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:
      IllegalStateException - if the test result has already been set.
      See Also:

    • 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)). If you override this method, be aware that this method does insert many of the standard result properties into the TestResult object - harness info, start stop times, etc.

    • run

      public abstract Status run(String[] args, TestDescription td, TestEnvironment env)
      The primary method to be provided by Scripts. It is responsible for compiling and executing the test appropriately. 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:

    • 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

      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:

    • 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, 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

    • 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

      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:

    • 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:

    • compileIndividually

      protected Status compileIndividually(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:

    • compileIndividually

      protected Status compileIndividually(String command, 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:

    • compileIndividually

      protected Status compileIndividually(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:

    • compileIndividually

      protected Status compileIndividually(String command, 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:

    • compileOne

      protected Status compileOne(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:

    • compileOne

      protected Status compileOne(String command, 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:

    • compileOne

      protected Status compileOne(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:

    • compileOne

      protected Status compileOne(String command, 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

      protected Status compileTogether(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:

    • compileTogether

      protected Status compileTogether(String command, 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:

    • compileTogether

      protected Status compileTogether(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:

    • compileTogether

      protected Status compileTogether(String command, 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:

    • compileIfNecessary

      protected Status compileIfNecessary(String[] srcs, 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:

    • compileIfNecessary

      protected Status compileIfNecessary(String command, String[] srcs, 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:

    • compileIfNecessary

      protected Status compileIfNecessary(File[] srcs, 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:

    • compileIfNecessary

      protected Status compileIfNecessary(String command, File[] srcs, 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:

    • execute

      protected Status execute(String executeClass, 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

      protected Status execute(String command, String executeClass, 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(String executeClass, 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

      protected Status execute(String command, String executeClass, 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:

    • rmiCompile

      protected Status rmiCompile(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:

    • rmiCompile

      protected Status rmiCompile(String command, 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

      protected Status invokeCommand(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' supersedes 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:

    • setDefaultCommandStreamNames

      protected void setDefaultCommandStreamNames(String out1Name, 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 String[] exclude(String[] args, 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

    • 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: