com.sun.javatest
Class Harness

java.lang.Object
  extended by com.sun.javatest.Harness

public class Harness
extends java.lang.Object

The object responsible for coordinating the execution of a test run.


Nested Class Summary
static class Harness.Fault
          This exception is used to report problems while executing a test run.
static interface Harness.Observer
          This interface provides a means for Harness to report on events that might be of interest as it executes.
 
Constructor Summary
Harness()
          Instantiate a harness.
Harness(java.io.File classDir)
          Deprecated. Use Harness() instead
 
Method Summary
 void addObserver(Harness.Observer o)
          Add an observer to be notified during the execution of a test run.
 boolean batch(Parameters params)
          Run the tests defined by a new set of parameters.
 int getAutostopThreshold(int n)
           
 BackupPolicy getBackupPolicy()
          Get the backup policy object used by this harness, used to determine the policy for backing up files before overwriting them.
static java.io.File getClassDir()
          Get the class directory or jar file containing JT Harness.
 long getElapsedTime()
          Find time since the start of the current or last run.
 TestEnvironment getEnv()
          Get the current test environment being used by the harness.
 long getEstimatedTime()
          Find out the estimated time required to complete the remaining tests.
 long getFinishTime()
          Get the time at which the last run finished.
 Parameters getParameters()
          Get the current parameters of the harness.
 TestResultTable getResultTable()
          Get the current set of results.
 long getStartTime()
          Get the time at which the last run start.
 int getTestsFoundCount()
          Find out how many tests to run have been located so far.
 ReadAheadIterator getTestsIterator(TestResultTable.TreeIterator iter)
           
 boolean isAllTestsFound()
          Indicates whether the harness has located all the tests it will execute.
 boolean isBatchRun()
          Was the harness invoked in batch mode? If it is not in batch mode, this typically implies that the user is using an interactive GUI interface.
 boolean isRunning()
          Check if the harness is currently executing a test suite or not.
 boolean isTracingRequired()
          Check if a trace file should be generated while performing a test run.
 void removeObserver(Harness.Observer o)
          Remove a previously registered observer so that it will no longer be notified during the execution of a test run.
 void setAutostopThreshold(int n)
          Set the threshold for automatic halting of a test run.
 void setBackupPolicy(BackupPolicy bp)
          Set the backup policy object to be used by this harness, used to determine the policy for backing up files before overwriting them.
static void setClassDir(java.io.File classDir)
          Specify the class directory or jar file containing JT Harness.
 void setTracingRequired(boolean b)
          Set whether a trace file should be generated while performing a test run.
 void start(Parameters p)
          Start running all the tests defined by a new set of parameters.
 void stop()
          Stop the harness executing any tests.
 void waitUntilDone()
          Wait until the harness completes the current task.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Harness

public Harness(java.io.File classDir)
Deprecated. Use Harness() instead

Instantiate a harness.

Parameters:
classDir - The class dir to put in the environment for otherJVM tests
See Also:
Harness(), setClassDir(java.io.File)

Harness

public Harness()
Instantiate a harness.

Method Detail

getBackupPolicy

public BackupPolicy getBackupPolicy()
Get the backup policy object used by this harness, used to determine the policy for backing up files before overwriting them.

Returns:
the backup policy object used by this harness
See Also:
setBackupPolicy(com.sun.javatest.util.BackupPolicy)

setBackupPolicy

public void setBackupPolicy(BackupPolicy bp)
Set the backup policy object to be used by this harness, used to determine the policy for backing up files before overwriting them.

Parameters:
bp - the backup policy object used by this harness
See Also:
getBackupPolicy()

isTracingRequired

public boolean isTracingRequired()
Check if a trace file should be generated while performing a test run.

Returns:
true if and only if a trace file should be generated
See Also:
setTracingRequired(boolean)

setTracingRequired

public void setTracingRequired(boolean b)
Set whether a trace file should be generated while performing a test run.

Parameters:
b - whether or not a trace file should be generated
See Also:
isTracingRequired()

getClassDir

public static java.io.File getClassDir()
Get the class directory or jar file containing JT Harness.

Returns:
the class directory or jar file containing JT Harness
See Also:
setClassDir(java.io.File)

setClassDir

public static void setClassDir(java.io.File classDir)
Specify the class directory or jar file containing JT Harness.

Parameters:
classDir - the class directory or jar file containing JT Harness
See Also:
getClassDir()

getParameters

public Parameters getParameters()
Get the current parameters of the harness.

Returns:
null if the parameters have not been set.

getEnv

public TestEnvironment getEnv()
Get the current test environment being used by the harness. This is similar to getParameters().getEnv(), except that the environment returned here has some standard additional fields set by the harness itself.

Returns:
null if the environment has not been set.

getResultTable

public TestResultTable getResultTable()
Get the current set of results. This will either be the set of results from which are currently running, or the results from the last run.

Returns:
null if no results are currently available. This will be the case if the Harness has not been run, or the parameters have been changed without doing a new run.

addObserver

public void addObserver(Harness.Observer o)
Add an observer to be notified during the execution of a test run. Observers are notified of events in the reverse order they were added -- the most recently added observer gets notified first.

Parameters:
o - the observer to be added
See Also:
removeObserver(com.sun.javatest.Harness.Observer)

removeObserver

public void removeObserver(Harness.Observer o)
Remove a previously registered observer so that it will no longer be notified during the execution of a test run. It is safe for observers to remove themselves during a notification; most obviously, an observer may remove itself during finishedTesting() or finishedTestRun().

Parameters:
o - the observer to be removed
See Also:
addObserver(com.sun.javatest.Harness.Observer)

start

public void start(Parameters p)
           throws Harness.Fault
Start running all the tests defined by a new set of parameters. The tests are run asynchronously, in a separate worker thread.

Parameters:
p - The parameters to be set when the tests are run. Any errors in the parameters are reported to any registered observers.
Throws:
Harness.Fault - if the harness is currently running tests and so cannot start running any more tests right now.
See Also:
isRunning(), stop(), waitUntilDone()

waitUntilDone

public void waitUntilDone()
                   throws java.lang.InterruptedException
Wait until the harness completes the current task.

Throws:
java.lang.InterruptedException - if the thread making the call is interrupted.

stop

public void stop()
Stop the harness executing any tests. If no tests are running, the method does nothing; otherwise it notifies any observers, and interrupts the thread doing the work. The worker may carry on for a short time after this method is called, while it waits for all the related tasks to complete.

See Also:
waitUntilDone()

batch

public boolean batch(Parameters params)
              throws Harness.Fault,
                     java.lang.InterruptedException
Run the tests defined by a new set of parameters.

Parameters:
params - The parameters to be used; they will be validated first.
Returns:
true if and only if all the selected tests were executed successfully, and all passed
Throws:
Harness.Fault - if the harness is currently running tests and cannot start running any more tests right now.
java.lang.InterruptedException - if the thread making the call is interrupted, perhaps because of an asynchronous call of stop().
See Also:
isRunning(), stop(), waitUntilDone()

isRunning

public boolean isRunning()
Check if the harness is currently executing a test suite or not.

Returns:
true if and only if the harness is currently executing a test suite.
See Also:
start(com.sun.javatest.Parameters), batch(com.sun.javatest.Parameters), stop(), waitUntilDone()

isBatchRun

public boolean isBatchRun()
                   throws java.lang.IllegalStateException
Was the harness invoked in batch mode? If it is not in batch mode, this typically implies that the user is using an interactive GUI interface.

Returns:
True if the harness is running and was invoked in batch mode.
Throws:
java.lang.IllegalStateException - If the harness is not running, care should be taken to handle this in case the run terminates.

isAllTestsFound

public boolean isAllTestsFound()
Indicates whether the harness has located all the tests it will execute. If true, then getTestsFoundCount() will return the number of test which will be executed during this test run; assuming the harness does not halt for special cases (errors, user request, etc...). If false, getTestsFoundCount() returns the number of tests located so far.

Returns:
True if all tests have been located. False if the harness is still looking for tests. Always false if the harness is not running.
See Also:
isRunning(), getTestsFoundCount()

getElapsedTime

public long getElapsedTime()
Find time since the start of the current or last run. If no run is in progress, this is the time it took to complete the last run.

Returns:
Zero if no run has ever been started yet. Elapsed time in milliseconds otherwise.

getStartTime

public long getStartTime()
Get the time at which the last run start.

Returns:
Time when the last run started in milliseconds. -1 if there is no previous run.
See Also:
getFinishTime()

getFinishTime

public long getFinishTime()
Get the time at which the last run finished. This is the time when the last test completed, and does not include post-run cleanup time.

Returns:
Time when the last run finished in milliseconds. -1 if there is no previous run or a run is in progress.
See Also:
getStartTime()

getEstimatedTime

public long getEstimatedTime()
Find out the estimated time required to complete the remaining tests.

Returns:
A time estimate in milliseconds. Zero if no run is in progress or no estimate is available.

getTestsFoundCount

public int getTestsFoundCount()
Find out how many tests to run have been located so far. Data will pertain to the previous run (if any) if isRunning() is false. The return will be zero if isRunning() is false and there is no previous run for this instance of the Harness.

Returns:
Number of tests which the harness will try to run. Greater than or equal to zero and less than or equal to the total number of tests in the testsuite.
See Also:
isRunning()

setAutostopThreshold

public void setAutostopThreshold(int n)
Set the threshold for automatic halting of a test run. The current algorithm is to begin at zero, add one for every failure, five for every error and subtract two for each pass. This value must be set before the run begins, do not change it during a run.

See Also:
getAutostopThreshold(int)

getAutostopThreshold

public int getAutostopThreshold(int n)
See Also:
setAutostopThreshold(int)

getTestsIterator

public ReadAheadIterator getTestsIterator(TestResultTable.TreeIterator iter)
                                   throws Harness.Fault
Throws:
Harness.Fault


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