Package com.sun.javatest
Class TestResultTable
java.lang.Object
com.sun.javatest.TestResultTable
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
Nested ClassesModifier and TypeClassDescriptionstatic class
Exception class to communicate any special conditions which may occur while using this class.static interface
Observer to monitor changes to a TestResultTable.static class
Keeps track of the path to a specific node in the TestResultTable tree.static interface
Extension to TreeObserver to receive notifications related to events happened on tree nodes.static interface
Defines an iterator/enumerator interface for retrieving tests out of the tree.static interface
Interface to a node which contitutes the skeleton of the test result tree.static interface
Observer interface to watch a single tree node.static interface
Tree-aware observer of the TRT. -
Constructor Summary
ConstructorsConstructorDescriptionCreate a table ready to be occupied.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
Modifier and TypeMethodDescriptionvoid
Add a general purpose observer.void
Add a tree-aware observer.void
dispose()
static String[]
distillUrls
(String... urls) Removes from sorted array all overlapping entries.elements()
List all the tests in the tree.elements
(TestFilter... filters) Same description as getIterator() method with same args.static Enumeration
<TestResult> List all the tests under this node.static Enumeration
<TestResult> elements
(TestResultTable.TreeNode node, TestFilter filter) Same description as getIterator() method with same args.static Enumeration
<TestResult> elements
(TestResultTable.TreeNode node, TestFilter... filters) Same description as getIterator() method with same args.elements
(File[] tests, TestFilter... filters) Same as getIterator() with the same args.elements
(String[] urls, TestFilter... filters) This method is the same as getIterator() with the same params.elements
(String url, TestFilter... filters) Get an enumerator capable of producing a filtered view of the test suite.protected void
finalize()
static TestResultTable.TreeNode
findNode
(TestResultTable.TreeNode node, String path) Used to find a branch node somewhere in the tree based on a path.This method returns TestResult from map of test results, collected by TestResultCache worker.int
How many tests have been found so far.List all the tests in the tree.getIterator
(TestFilter... filters) List all the tests in the tree subject to the given filters.static TestResultTable.TreeIterator
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.getIterator
(File[] tests, TestFilter... filters) Get an iterator capable of producing a filtered view of the test suite.getIterator
(String[] paths, TestFilter... filters) Get an iterator capable of producing a filtered view of the test suite.getLock()
static TestResultTable.TreeNode[]
getObjectPath
(TestResult target) Find the specified test, recording the path from the root.static TestResultTable.TreeNode[]
Find the specified test, recording the path from the root.getRoot()
Get the root TreeNode of this result table.static String
Get the path to this node, relative to the root of the testsuite.Get the finder that TRT is using to read the test suite.Get the root URL of the test suite.Deprecated.Use getWorkDirectoryGet the work directory associated with this object.boolean
isReady()
Determine the update status of the table.Find a specific instance of a test result.Find a specific instance of a test result.boolean
prune()
boolean
Removes empty nodes (things with no tests below them).boolean
Refresh a folder if the files on disk have been modified since the folder was read.boolean
refreshIfNeeded
(String test) Refresh a test if the files on disk have been modified since the test was read.void
Remove a general purpose observer.void
Remove a tree-aware observer.resetTest
(TestResult tr) This method purges the given test, including attempting to delete the associated JTR file, then replaces it with a basicNOT_RUN
test of the same name.This method purges the given test, including attempting to delete the associated JTR file, then replaces it with a basicNOT_RUN
test of the same name.resolveUrl
(String url) Take a URL and find the node in the current test tree to which it refers to.void
Set the test finder for this object.void
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.void
boolean
validatePath
(String path) Validate that a path is valid in this TestResultTable according to the rules for initial URLs.boolean
This method blocks until the work directory data has been completely synchronized.
-
Constructor Details
-
TestResultTable
public TestResultTable()Create a table ready to be occupied. -
TestResultTable
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
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:
-
-
Method Details
-
getObjectPath
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
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
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
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
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
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
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 Enumeration<TestResult> 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:
-
getRootRelativePath
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
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 searchpath
- 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:
IllegalArgumentException
- If the starting node or path is null.- Since:
- 3.0
-
distillUrls
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
-
dispose
public void dispose() -
updateTestExecutionOrderOnTheFly
public void updateTestExecutionOrderOnTheFly() -
getWorkDir
Deprecated.Use getWorkDirectoryGet the workdir associated with this object.- Returns:
- The workdir. Null if not available.
-
getWorkDirectory
Get the work directory associated with this object.- Returns:
- The work directory, or null if none set.
- See Also:
-
setWorkDirectory
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:
-
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
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
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:
-
lookup
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
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
Take a URL and find the node in the current test tree to which it refers to. The resulting node may be:- A folder (non-leaf) node. Type
TreeNode
- A test (leaf) node. Type
TestResult
- 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
- A folder (non-leaf) node. Type
-
validatePath
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
-
getIterator
List all the tests in the tree.- Returns:
- An iterator which returns all tests in the tree.
- Since:
- 3.0
-
elements
List all the tests in the tree.- Returns:
- An enumerator which returns all tests in the tree.
- Since:
- 3.0
- See Also:
-
getIterator
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
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:
-
elements
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
public TestResultTable.TreeIterator getIterator(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:
-
elements
public Enumeration<TestResult> elements(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
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
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:
-
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
Get the root TreeNode of this result table.- Returns:
- The root of the tree.
-
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
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
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:
IllegalStateException
- Thrown if the finder for this object is already set.- Since:
- 3.0
- See Also:
-
addObserver
Add a general purpose observer.- Parameters:
o
- The observer to attach. Must never be null.
-
removeObserver
Remove a general purpose observer. Removing an observer which is not attached has no effect.- Parameters:
o
- The observer to remove.
-
addObserver
Add a tree-aware observer.- Parameters:
obs
- The observer to attach. Must never be null.
-
removeObserver
Remove a tree-aware observer. Removing an observer which is not attached has no effect.- Parameters:
obs
- The observer to remove.
-
resetTest
This method purges the given test, including attempting to delete the associated JTR file, then replaces it with a basicNOT_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 useresetTest(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
This method purges the given test, including attempting to delete the associated JTR file, then replaces it with a basicNOT_RUN
test of the same name. This operation has no effect if the given test is not in the tree. TheresetTest(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:
-
refreshIfNeeded
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
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.
-
prune
public boolean prune() -
prune
Removes empty nodes (things with no tests below them).- Parameters:
node
- The node to perform the prune operation upon.- Returns:
- True if some nodes were pruned, false otherwise.
-
finalize
-
getCachedResult
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
-