Package com.sun.javatest

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

    • Constructor Detail

      • TestResultTable

        public TestResultTable()
        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

      • 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 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<TestResult> 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<TestResult> 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<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:
        getIterator()

      • 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

      • 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

      • dispose

        public void dispose()

      • updateTestExecutionOrderOnTheFly

        public void updateTestExecutionOrderOnTheFly()

      • getWorkDir

        @Deprecated
public WorkDirectory getWorkDir()
        Deprecated.
        Use getWorkDirectory
        Get the workdir associated with this object.
        Returns:
        The workdir. Null if not available.

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

      • 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

      • 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<TestResult> 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<TestResult> 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()

      • elements

        public java.util.Enumeration<TestResult> 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<TestResult> 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<TestResult> 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)

      • 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()

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

        public boolean prune​(TestResultTable.TreeNode node)
        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

        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()