com.sun.javatest
Class TestResultTable

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

public class TestResultTable
extends java.lang.Object

Collected results from a test suite. The data is represented as TestResult objects, although the test itself may not have been run, but just "found" so far. TestResultTable is populated by using a TestFinder, and is subsequently updated as tests are run by the harness.


Nested Class Summary
static class TestResultTable.Fault
          Exception class to communicate any special conditions which may occur while using this class.
static interface TestResultTable.Observer
          Observer to monitor changes to a TestResultTable.
 class TestResultTable.PathRecord
          Keeps track of the path to a specific node in the TestResultTable tree.
static interface TestResultTable.TreeEventObserver
          Extension to TreeObserver to receive notifications related to events happened on tree nodes.
static interface TestResultTable.TreeIterator
          Defines an iterator/enumerator interface for retrieving tests out of the tree.
static interface TestResultTable.TreeNode
          Interface to a node which contitutes the skeleton of the test result tree.
static interface TestResultTable.TreeNodeObserver
          Observer interface to watch a single tree node.
static interface TestResultTable.TreeObserver
          Tree-aware observer of the TRT.
 
Constructor Summary
TestResultTable()
          Deprecated. This method will become private. XXX make this method private
TestResultTable(WorkDirectory wd)
          Create a table for the tests in a work directory and its associated test suite and test finder.
TestResultTable(WorkDirectory wd, TestFinder tf)
          Create a table for the tests in a work directory and its associated test suite, overriding the test suite's default test finder.
 
Method Summary
 void addObserver(TestResultTable.Observer o)
          Add a general purpose observer.
 void addObserver(TestResultTable.TreeObserver obs)
          Add a tree-aware observer.
 void dispose()
           
static java.lang.String[] distillUrls(java.lang.String[] urls)
          Removes from sorted array all overlapping entries.
 java.util.Enumeration elements()
          List all the tests in the tree.
 java.util.Enumeration elements(java.io.File[] tests, TestFilter[] filters)
          Same as getIterator() with the same args.
 java.util.Enumeration elements(java.lang.String[] urls, TestFilter[] filters)
          This method is the same as getIterator() with the same params.
 java.util.Enumeration elements(java.lang.String url, TestFilter[] filters)
          Get an enumerator capable of producing a filtered view of the test suite.
 java.util.Enumeration elements(TestFilter[] filters)
          Same description as getIterator() method with same args.
static java.util.Enumeration elements(TestResultTable.TreeNode node)
          List all the tests under this node.
static java.util.Enumeration elements(TestResultTable.TreeNode node, TestFilter filter)
          Same description as getIterator() method with same args.
static java.util.Enumeration elements(TestResultTable.TreeNode node, TestFilter[] filters)
          Same description as getIterator() method with same args.
protected  void finalize()
           
static TestResultTable.TreeNode findNode(TestResultTable.TreeNode node, java.lang.String path)
          Used to find a branch node somewhere in the tree based on a path.
 TestResult getCachedResult(TestDescription td)
          This method returns TestResult from map of test results, collected by TestResultCache worker.
 int getCurrentTestCount()
          How many tests have been found so far.
 TestResultTable.TreeIterator getIterator()
          List all the tests in the tree.
 TestResultTable.TreeIterator getIterator(java.io.File[] tests, TestFilter[] filters)
          Get an iterator capable of producing a filtered view of the test suite.
 TestResultTable.TreeIterator getIterator(java.lang.String[] paths, TestFilter[] filters)
          Get an iterator capable of producing a filtered view of the test suite.
 TestResultTable.TreeIterator getIterator(TestFilter[] filters)
          List all the tests in the tree subject to the given filters.
static TestResultTable.TreeIterator getIterator(TestResultTable.TreeNode node)
          List all the tests under this node.
static TestResultTable.TreeIterator getIterator(TestResultTable.TreeNode node, TestFilter filter)
          Get an iterator capable of producing a filtered view of the test suite.
static TestResultTable.TreeIterator getIterator(TestResultTable.TreeNode node, TestFilter[] filters)
          Get an iterator capable of producing a filtered view of the test suite.
 java.util.concurrent.locks.ReentrantLock getLock()
           
static TestResultTable.TreeNode[] getObjectPath(TestResult target)
          Find the specified test, recording the path from the root.
static TestResultTable.TreeNode[] getObjectPath(TestResultTable.TreeNode target)
          Find the specified test, recording the path from the root.
 TestResultTable.TreeNode getRoot()
          Get the root TreeNode of this result table.
static java.lang.String getRootRelativePath(TestResultTable.TreeNode node)
          Get the path to this node, relative to the root of the testsuite.
 TestFinder getTestFinder()
          Get the finder that TRT is using to read the test suite.
 java.io.File getTestSuiteRoot()
          Get the root URL of the test suite.
 WorkDirectory getWorkDir()
          Deprecated. Use getWorkDirectory
 WorkDirectory getWorkDirectory()
          Get the work directory associated with this object.
 boolean isReady()
          Determine the update status of the table.
 TestResult lookup(java.lang.String jtrPath)
          Find a specific instance of a test result.
 TestResult lookup(TestDescription td)
          Find a specific instance of a test result.
 boolean prune()
           
 boolean prune(TestResultTable.TreeNode node)
           
 boolean refreshIfNeeded(java.lang.String test)
          Refresh a test if the files on disk have been modified since the test was read.
 boolean refreshIfNeeded(TestResultTable.TreeNode node)
          Refresh a folder if the files on disk have been modified since the folder was read.
 void removeObserver(TestResultTable.Observer o)
          Remove a general purpose observer.
 void removeObserver(TestResultTable.TreeObserver obs)
          Remove a tree-aware observer.
 TestResult resetTest(java.lang.String testName)
          This method purges the given test, including attempting to delete the associated JTR file, then replaces it with a basic NOT_RUN test of the same name.
 TestResult resetTest(TestResult tr)
          This method purges the given test, including attempting to delete the associated JTR file, then replaces it with a basic NOT_RUN test of the same name.
 java.lang.Object resolveUrl(java.lang.String url)
          Take a URL and find the node in the current test tree to which it refers to.
 void setTestFinder(TestFinder tf)
          Set the test finder for this object.
 void setWorkDirectory(WorkDirectory wd)
          Set the work directory associated with this object.
 int size()
          Find out the size of the entire tree.
 void update(TestResult tr)
          Update the information in the table with a new test result.
 void update(TestResult tr, boolean suppressScan)
          Update the information in the table with a new test result.
 boolean validatePath(java.lang.String path)
          Validate that a path is valid in this TestResultTable according to the rules for initial URLs.
 boolean waitUntilReady()
          This method blocks until the work directory data has been completely synchronized.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TestResultTable

public TestResultTable()
Deprecated. This method will become private. XXX make this method private

Create a table ready to be occupied.


TestResultTable

public TestResultTable(WorkDirectory wd)
Create a table for the tests in a work directory and its associated test suite and test finder.

Parameters:
wd - The work directory to associate with this table.
Since:
3.0

TestResultTable

public TestResultTable(WorkDirectory wd,
                       TestFinder tf)
Create a table for the tests in a work directory and its associated test suite, overriding the test suite's default test finder.

Parameters:
wd - The work directory to associate with this table.
tf - The finder to use. Do not use this constructor unless necessary.
Since:
3.0
See Also:
TestResultTable(WorkDirectory)
Method Detail

dispose

public void dispose()

setTestFinder

public void setTestFinder(TestFinder tf)
Set the test finder for this object. It is illegal to call this method once the test finder for a instance has been set. Rather than use this method, it is probably better to supply the finder at construction time.

Parameters:
tf - The finder to use.
Throws:
java.lang.IllegalStateException - Thrown if the finder for this object is already set.
Since:
3.0
See Also:
getTestFinder()

getWorkDir

public WorkDirectory getWorkDir()
Deprecated. Use getWorkDirectory

Get the workdir associated with this object.

Returns:
The workdir. Null if not available.

getWorkDirectory

public WorkDirectory getWorkDirectory()
Get the work directory associated with this object.

Returns:
The work directory, or null if none set.
See Also:
setWorkDirectory(com.sun.javatest.WorkDirectory)

setWorkDirectory

public void setWorkDirectory(WorkDirectory wd)
Set the work directory associated with this object. Once set, it cannot be changed.

Parameters:
wd - The work directory, or null if none set.
See Also:
getWorkDirectory()

getCurrentTestCount

public int getCurrentTestCount()
How many tests have been found so far.

Returns:
A number greater than or equal to zero.
Since:
3.0

update

public void update(TestResult tr)
Update the information in the table with a new test result. The supplied TestResult may exist in the table already, it can replace an existing test or it can be completely new. Doing this operation will trigger appropriate observer messages.

Parameters:
tr - The test to insert or update.
Throws:
JavaTestError - Throws if the result cache throws an error.

update

public void update(TestResult tr,
                   boolean suppressScan)
Update the information in the table with a new test result. The supplied TestResult may exist in the table already, it can replace an existing test or it can be completely new. Doing this operation will trigger appropriate observer messages.

Parameters:
tr - The test to insert or update.
suppressScan - Request that test finder activity be suppressed if possible
Throws:
JavaTestError - Throws if the result cache throws an error.

waitUntilReady

public boolean waitUntilReady()
This method blocks until the work directory data has been completely synchronized. It is recommended that you use this before creating and using an iterator to ensure that you get consistent and up to date data. It would also be advisable to do this before forcing the VM to exit.

Returns:
Always true. Reserved for later use.
Since:
3.0.1

isReady

public boolean isReady()
Determine the update status of the table.

Returns:
True if the table is in a consistent state.
See Also:
waitUntilReady()

lookup

public TestResult lookup(TestDescription td)
Find a specific instance of a test result.

Parameters:
td - The test description which corresponds to the target result.
Returns:
The requested test result object, null if not found.

lookup

public TestResult lookup(java.lang.String jtrPath)
Find a specific instance of a test result. If you only have the test URL, use TestResult.getWorkRelativePath() to get the jtrPath parameter for this method.

Parameters:
jtrPath - The work relative path of the test result file. Output from TestResult.getWorkRelativePath() is the best source of this info.
Returns:
The requested test result object, null if not found.

resolveUrl

public java.lang.Object resolveUrl(java.lang.String url)
Take a URL and find the node in the current test tree to which it refers to. The resulting node may be:

Parameters:
url - A forward-slash separated path referring to node names along a path originating at the root node.
Returns:
The nodes that the given URL refers to. Null if no match.
Since:
3.2

validatePath

public boolean validatePath(java.lang.String path)
Validate that a path is valid in this TestResultTable according to the rules for initial URLs.

Parameters:
path - The path to validate. Should be internal URL format (forward slashes, relative to test root, ...) Null is acceptable but will immediately result in null being returned.
Returns:
True if the given path is valid in this instance, false otherwise.
Since:
3.0.2

getObjectPath

public static TestResultTable.TreeNode[] getObjectPath(TestResult target)
Find the specified test, recording the path from the root.

Parameters:
target - The test to generate the path for.
Returns:
The path to the root of the enclosing TRT. Null if the operation could not be completed. The target node is not included in the returned array. Index 0 will be the TRT root.
Since:
3.0

getObjectPath

public static TestResultTable.TreeNode[] getObjectPath(TestResultTable.TreeNode target)
Find the specified test, recording the path from the root.

Parameters:
target - The node to generate the path for.
Returns:
The path to the root of the enclosing TRT. Null if the operation could not be completed. The target node is included in the returned array as the last element, index 0 will be the TRT root.
Since:
3.0

getIterator

public TestResultTable.TreeIterator getIterator()
List all the tests in the tree.

Returns:
An iterator which returns all tests in the tree.
Since:
3.0

elements

public java.util.Enumeration elements()
List all the tests in the tree.

Returns:
An enumerator which returns all tests in the tree.
Since:
3.0
See Also:
getIterator()

getIterator

public TestResultTable.TreeIterator getIterator(TestFilter[] filters)
List all the tests in the tree subject to the given filters.

Parameters:
filters - The Filters to run tests through before "selecting" them for iteration. May be null.
Returns:
An iterator which returns all tests in the tree after removing those filtered out by the filters.
Since:
3.0

elements

public java.util.Enumeration elements(TestFilter[] filters)
Same description as getIterator() method with same args.

Parameters:
filters - The Filters to run tests through before "selecting" them for iteration. May be null.
Returns:
An enumerator which returns all tests in the tree after removing those filtered out by the filters.
Since:
3.0
See Also:
getIterator()

getIterator

public static TestResultTable.TreeIterator getIterator(TestResultTable.TreeNode node)
List all the tests under this node.

Parameters:
node - The tree node to being the iteration at.
Returns:
An iterator which return all the tests below the given node.
Since:
3.0

elements

public static java.util.Enumeration elements(TestResultTable.TreeNode node)
List all the tests under this node.

Parameters:
node - The tree node to being the iteration at.
Returns:
An enumerator which return all the tests below the given node.
Since:
3.0
See Also:
getIterator()

getIterator

public static TestResultTable.TreeIterator getIterator(TestResultTable.TreeNode node,
                                                       TestFilter filter)
Get an iterator capable of producing a filtered view of the test suite. If the node parameter is null, an iterator with no items will be returned. An empty or null set of filters is acceptable and will result in unfiltered iteration.

Parameters:
node - The tree node to being the iteration at. May be null.
filter - The filter to run tests through before "selecting" them for iteration.
Returns:
An iterator which returns test below the given node after removing any tests which the filter rejects.
Since:
3.0

elements

public static java.util.Enumeration elements(TestResultTable.TreeNode node,
                                             TestFilter filter)
Same description as getIterator() method with same args.

Parameters:
node - The tree node to being the enumeration at. May be null.
filter - The filter to run tests through before "selecting" them for enumeration. May be null.
Returns:
An enumerator which returns test below the given node after removing any tests which the filter rejects.
Since:
3.0
See Also:
getIterator()

getIterator

public static TestResultTable.TreeIterator getIterator(TestResultTable.TreeNode node,
                                                       TestFilter[] filters)
Get an iterator capable of producing a filtered view of the test suite. If the node parameter is null, an iterator with no items will be returned. An empty or null set of filters is acceptable and will result in unfiltered iteration.

Parameters:
node - The tree node to begin enumerating at. May be null.
filters - The test filters to apply to any tests found.
Returns:
An iterator which returns test below the given node after removing any tests which the filters reject.
Since:
3.0

elements

public static java.util.Enumeration elements(TestResultTable.TreeNode node,
                                             TestFilter[] filters)
Same description as getIterator() method with same args.

Parameters:
node - The tree node to begin enumerating at. May be null.
filters - The test filters to apply to any tests found.
Returns:
An enumerator which returns test below the given node after removing any tests which the filters reject.
Since:
3.0
See Also:
getIterator()

elements

public java.util.Enumeration elements(java.lang.String url,
                                      TestFilter[] filters)
Get an enumerator capable of producing a filtered view of the test suite. This can be used to obtain a view of the test suite based on an initial URL selection. The URL can specify a folder/directory, a specific test, or a file which contains one or more tests. If the given URL parameter is null, an iterator with no elements will be returned. An empty or null set of filters is acceptable and will result in unfiltered iteration.

Parameters:
url - The test URL to scan. This value should have already be normalized to a '/' file separator. May be null.
filters - The test filters to apply to any tests found. May be null.
Returns:
An enumerator which returns test below the given location after removing any tests which the filters reject.
Since:
3.0
See Also:
getIterator()

getIterator

public TestResultTable.TreeIterator getIterator(java.io.File[] tests,
                                                TestFilter[] filters)
                                         throws TestResultTable.Fault
Get an iterator capable of producing a filtered view of the test suite. This can be used to obtain a view of the test suite based on an initial URL selection. The URL can specify a folder/directory, a specific test, or a file which contains one or more tests. If the initial urls are null or zero length, a filtered iterator of the root will be returned. An empty or null set of filters is acceptable and will result in unfiltered iteration.

Parameters:
tests - The set of files base the iterator on. May be null. If this set is not empty, the contents should have already been validated using the validatePath() method.
filters - The test filters to apply to any tests found. May be null.
Returns:
An iterator which return the union of tests specified by the initial files but not removed by the filters.
Throws:
TestResultTable.Fault - Thrown if the given initialUrls are invalid.
Since:
3.0
See Also:
validatePath(java.lang.String)

elements

public java.util.Enumeration elements(java.io.File[] tests,
                                      TestFilter[] filters)
                               throws TestResultTable.Fault
Same as getIterator() with the same args.

Parameters:
tests - The set of files base the enumerator on. May be null.
filters - The test filters to apply to any tests found. May be null.
Returns:
An enumerator which return the union of tests specified by the initial files but not removed by the filters.
Throws:
TestResultTable.Fault - Thrown if the given initialUrls are invalid.
Since:
3.0
See Also:
getIterator()

getIterator

public TestResultTable.TreeIterator getIterator(java.lang.String[] paths,
                                                TestFilter[] filters)
Get an iterator capable of producing a filtered view of the test suite. This can be used to obtain a view of the test suite based on an initial URL selection. An empty or null set of filters is acceptable and will result in unfiltered iteration.

Parameters:
paths - The test URLs to scan. Values should have already be normalized to a '/' file separator. May not be null.
filters - The test filters to apply to any tests found. May be null.
Returns:
An iterator which return the union of tests specified by the URLs but not removed by the filters.
Since:
3.0

elements

public java.util.Enumeration elements(java.lang.String[] urls,
                                      TestFilter[] filters)
This method is the same as getIterator() with the same params.

Parameters:
urls - The test URLs to scan. Values should have already be normalized to a '/' file separator.
filters - The test filters to apply to any tests found.
Returns:
An enumerator which return the union of tests specified by the URLs but not removed by the filters.
Since:
3.0
See Also:
getIterator()

size

public int size()
Find out the size of the entire tree. This is a high overhead call, use with caution.

Returns:
The number of tests in the tree.

getRoot

public TestResultTable.TreeNode getRoot()
Get the root TreeNode of this result table.

Returns:
The root of the tree.

getTestSuiteRoot

public java.io.File getTestSuiteRoot()
Get the root URL of the test suite. This may not match that given by the environment if the environment's URL is partially invalid for some reason.

Returns:
A file representing the path to the root of the testsuite.

getTestFinder

public TestFinder getTestFinder()
Get the finder that TRT is using to read the test suite. Unless the TRT was constructed using a TestFinder, this value will most likely be null.

Returns:
The active test finder. Null if no finder is being used.
Since:
3.0
See Also:
setTestFinder(com.sun.javatest.TestFinder)

getRootRelativePath

public static java.lang.String getRootRelativePath(TestResultTable.TreeNode node)
Get the path to this node, relative to the root of the testsuite. The returned URL does not have a trailing slash, nor does it begin with one.

Parameters:
node - The node to find the path to.
Returns:
The URL to the given node, with '/' as the path separator. Zero length string if the node is a root.
Since:
3.0

findNode

public static TestResultTable.TreeNode findNode(TestResultTable.TreeNode node,
                                                java.lang.String path)
Used to find a branch node somewhere in the tree based on a path. If the path string is of zero length (the empty string), the node parameter is returned. This is desirable for proper operation because the path to the root is the empty path.

Parameters:
node - Where to start the search
path - The work relative position of the JTR (TestResult.getWorkRelativePath())
Returns:
The node with the given path relative to the given node. Null if not found.
Throws:
java.lang.IllegalArgumentException - If the starting node or path is null.
Since:
3.0

addObserver

public void addObserver(TestResultTable.Observer o)
Add a general purpose observer.

Parameters:
o - The observer to attach. Must never be null.

removeObserver

public void removeObserver(TestResultTable.Observer o)
Remove a general purpose observer. Removing an observer which is not attached has no effect.

Parameters:
o - The observer to remove.

addObserver

public void addObserver(TestResultTable.TreeObserver obs)
Add a tree-aware observer.

Parameters:
obs - The observer to attach. Must never be null.

removeObserver

public void removeObserver(TestResultTable.TreeObserver obs)
Remove a tree-aware observer. Removing an observer which is not attached has no effect.

Parameters:
obs - The observer to remove.

resetTest

public TestResult resetTest(TestResult tr)
This method purges the given test, including attempting to delete the associated JTR file, then replaces it with a basic NOT_RUN test of the same name. This operation has no effect if the given test is not in the tree.

Matching objects for removal is done only by reference. The operation may fail (return null) if the test exists, but is not the same object. If you really want to remove a test by name, you can use resetTest(String).

NOTE: This method will cause waitUntilReady() to block.

Parameters:
tr - The test to find, purge and replace.
Returns:
The new NOT_RUN test. Null if the operation fails because the test could not be found.
Since:
3.0
See Also:
resetTest(String)

resetTest

public TestResult resetTest(java.lang.String testName)
This method purges the given test, including attempting to delete the associated JTR file, then replaces it with a basic NOT_RUN test of the same name. This operation has no effect if the given test is not in the tree. The resetTest(TestResult) method is more efficient than this one, use it if you already have the object.

NOTE: This method may cause waitUntilReady() to block.

Parameters:
testName - The test to find, purge and replace. This is of the form given by TestResult.getTestName().
Returns:
The new NOT_RUN test. Null if the given test name could not be found.
Since:
3.0
See Also:
TestResult.getTestName()

refreshIfNeeded

public boolean refreshIfNeeded(java.lang.String test)
                        throws TestResultTable.Fault
Refresh a test if the files on disk have been modified since the test was read.

Parameters:
test - The path for the test to be refreshed
Returns:
true if a refresh was needed, false otherwise.
Throws:
TestResultTable.Fault - if the test indicated cannot be located for refreshing.

refreshIfNeeded

public boolean refreshIfNeeded(TestResultTable.TreeNode node)
                        throws TestResultTable.Fault
Refresh a folder if the files on disk have been modified since the folder was read. Notifies observers of the refresh happened.

Parameters:
node - the node representing the folder to be refreshed
Returns:
true if any refreshing was needed, false otherwise.
Throws:
TestResultTable.Fault - if the node indicated cannot be located for refreshing.

prune

public boolean prune()
              throws TestResultTable.Fault
Throws:
TestResultTable.Fault

prune

public boolean prune(TestResultTable.TreeNode node)
              throws TestResultTable.Fault
Returns:
True if some nodes were pruned, false otherwise.
Throws:
TestResultTable.Fault

distillUrls

public static java.lang.String[] distillUrls(java.lang.String[] urls)
Removes from sorted array all overlapping entries. E.g. {"root/a/b.html", "root/a/b.html#a", "root/a/b.htmls", "root/c", "root/c/d"} would be {"root/a/b.html", "root/a/b.htmls", "root/c"} complexity: n complexity including quicksort: n*n*ln(n)

Parameters:
urls - A sorted list of test urls

finalize

protected void finalize()
                 throws java.lang.Throwable
Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable

getCachedResult

public TestResult getCachedResult(TestDescription td)
This method returns TestResult from map of test results, collected by TestResultCache worker. If worker didn't finished his work yet, method returns null and adds TestDescription of requested result to a special set. TestResults from this set will be updated after cache worker finishes its work.


getLock

public java.util.concurrent.locks.ReentrantLock getLock()


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