Class WorkDirectory


  • public class WorkDirectory
    extends java.lang.Object
    A class providing access to the working state of a test run, as embodied in a work directory.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String JTDATA  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void changeTemplate​(java.io.File dir, java.io.File newTemplate)  
      static WorkDirectory convert​(java.io.File dir, TestSuite ts)
      Convert an existing directory into a work directory.
      static WorkDirectory create​(java.io.File dir, TestSuite ts)
      Create a new work directory with a given name, and for a given test suite.
      static java.lang.String[] getDiffInPaths​(java.lang.String newPath, java.lang.String oldWDpath)  
      java.io.File getFile​(java.lang.String name)
      Get a file in this work directory.
      java.io.File getJTData()
      Get the data directory for this work directory.
      java.lang.String getLogFileName()  
      java.lang.String getPath()
      Get the root directory for this work directory.
      java.lang.String getPrevWDPath()  
      java.io.File getRoot()
      Get the root directory for this work directory.
      java.io.File getSystemFile​(java.lang.String name)
      Get a file in the system directory for this work directory.
      java.util.Map<java.lang.String,​java.lang.String> getTestAnnotations​(TestResult tr)
      Get any annotations for the given test in this work directory.
      java.util.Map<java.lang.String,​java.lang.String> getTestAnnotations​(java.lang.String testName)
      Get any annotations for the given test.
      TestResultTable getTestResultTable()
      Get a test result table containing the test results in this work directory.
      TestSuite getTestSuite()
      Get the test suite for this work directory.
      int getTestSuiteTestCount()
      Find out the number of tests in the entire test suite.
      static boolean isEmptyDirectory​(java.io.File dir)
      Check if a directory is an empty directory.
      boolean isTRTSet()  
      static boolean isUsableWorkDirectory​(java.io.File dir)
      Do sanity check of workdir.
      static boolean isWorkDirectory​(java.io.File dir)
      Check if a directory is a work directory.
      void log​(I18NResourceBundle i18n, java.lang.String key)
      Print a text message to the workdir logfile.
      void log​(I18NResourceBundle i18n, java.lang.String key, java.lang.Object arg)
      Print a text message to the workdir logfile.
      void log​(I18NResourceBundle i18n, java.lang.String key, java.lang.Object[] args)
      Print a text message to the workdir logfile.
      static WorkDirectory open​(java.io.File dir)
      Open an existing work directory, using the default test suite associated with it.
      static WorkDirectory open​(java.io.File dir, TestSuite testSuite)
      Open an existing work directory, using an explicit test suite.
      boolean purge​(java.lang.String path)
      Clean the contents of the given path.
      void putTestAnnotation​(TestResult tr, java.lang.String key, java.lang.String value)
      See putTestAnnotation(String,String,String).
      void putTestAnnotation​(java.lang.String testName, java.lang.String key, java.lang.String value)
      Add an annotation for the given test.
      void setTestResultTable​(TestResultTable trt)
      Set a test result table containing the test descriptions for the tests in this test suite.
      void setTestSuiteTestCount​(int num)
      Specify the total number of tests found in this testsuite.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • isWorkDirectory

        public static boolean isWorkDirectory​(java.io.File dir)
        Check if a directory is a work directory. This is intended to be a quick check, rather than exhaustive one; as such, it simply checks for the existence of the "jtData" subdirectory.
        Parameters:
        dir - the directory to be checked
        Returns:
        true if and only if the specified directory appears to be a work directory
      • isEmptyDirectory

        public static boolean isEmptyDirectory​(java.io.File dir)
        Check if a directory is an empty directory.
        Parameters:
        dir - the directory to be checked
        Returns:
        true if and only if the directory is empty
      • isUsableWorkDirectory

        public static boolean isUsableWorkDirectory​(java.io.File dir)
        Do sanity check of workdir. All critical areas must be read-write.
      • getLogFileName

        public java.lang.String getLogFileName()
      • changeTemplate

        public static void changeTemplate​(java.io.File dir,
                                          java.io.File newTemplate)
      • getDiffInPaths

        public static java.lang.String[] getDiffInPaths​(java.lang.String newPath,
                                                        java.lang.String oldWDpath)
      • getPrevWDPath

        public java.lang.String getPrevWDPath()
      • getRoot

        public java.io.File getRoot()
        Get the root directory for this work directory.
        Returns:
        the root directory for this work directory
      • getPath

        public java.lang.String getPath()
        Get the root directory for this work directory.
        Returns:
        the path of the root directory for this work directory
      • getJTData

        public java.io.File getJTData()
        Get the data directory for this work directory.
        Returns:
        the system (jtData) directory for this work directory
      • getFile

        public java.io.File getFile​(java.lang.String name)
        Get a file in this work directory.
        Parameters:
        name - the name of a file within this work directory
        Returns:
        the full (absolute) name of the specified file
      • getSystemFile

        public java.io.File getSystemFile​(java.lang.String name)
        Get a file in the system directory for this work directory.
        Parameters:
        name - the name of a file within the system (jtData) directory
        Returns:
        the full (absolute) name of the specified file
      • getTestSuite

        public TestSuite getTestSuite()
        Get the test suite for this work directory.
        Returns:
        the test suite for which this is a work directory
      • getTestSuiteTestCount

        public int getTestSuiteTestCount()
        Find out the number of tests in the entire test suite. This number is collected from either a previous iteration of the testsuite or from the TestSuite object.
        Returns:
        the number of tests in the test suite, -1 if not known.
        See Also:
        setTestSuiteTestCount(int), TestSuite.getEstimatedTestCount()
      • setTestSuiteTestCount

        public void setTestSuiteTestCount​(int num)
        Specify the total number of tests found in this testsuite. When available, this class prefers to use this number rather than that provided by a TestSuite object.
        Parameters:
        num - the number of tests in the test suite
        See Also:
        getTestSuiteTestCount(), TestSuite.getEstimatedTestCount()
      • setTestResultTable

        public void setTestResultTable​(TestResultTable trt)
        Set a test result table containing the test descriptions for the tests in this test suite.
        Parameters:
        trt - a test result table containing the test descriptions for the tests in this work directory
        Throws:
        java.lang.NullPointerException - if trt is null.
        java.lang.IllegalArgumentException - if the test result table has been initialized with a different work directory.
        See Also:
        getTestResultTable()
      • isTRTSet

        public boolean isTRTSet()
      • log

        public void log​(I18NResourceBundle i18n,
                        java.lang.String key)
        Print a text message to the workdir logfile. A single line of text which is as short as possible is highly recommended for readability purposes.
        Parameters:
        i18n - a resource bundle containing the localized messages
        key - a key into the resource bundle for the required message
        Since:
        3.0.1
      • log

        public void log​(I18NResourceBundle i18n,
                        java.lang.String key,
                        java.lang.Object arg)
        Print a text message to the workdir logfile. A single line of text which is as short as possible is highly recommended for readability purposes.
        Parameters:
        i18n - a resource bundle containing the localized messages
        key - a key into the resource bundle for the required message
        arg - An argument to be formatted into the specified message. If this is a Throwable, its stack trace will be included in the log.
        Since:
        3.0.1
      • log

        public void log​(I18NResourceBundle i18n,
                        java.lang.String key,
                        java.lang.Object[] args)
        Print a text message to the workdir logfile. A single line of text which is as short as possible is highly recommended for readability purposes.
        Parameters:
        i18n - a resource bundle containing the localized messages
        key - a key into the resource bundle for the required message
        args - An array of arguments to be formatted into the specified message. If the first arg is a Throwable, its stack trace will be included in the log.
        Since:
        3.0.1
      • putTestAnnotation

        public void putTestAnnotation​(java.lang.String testName,
                                      java.lang.String key,
                                      java.lang.String value)
        Add an annotation for the given test.
        Parameters:
        testName - Test for which the annotation should be added. This is the value from TestResult.getTestName().
        key - The name of the value to be entered. The namespace for this value is unique for each testName.
        value - The value of the annotation. Null removes the value from the map, an empty string should be used otherwise.
      • getTestAnnotations

        public java.util.Map<java.lang.String,​java.lang.String> getTestAnnotations​(TestResult tr)
        Get any annotations for the given test in this work directory. The annotations take the form of a map of strings for both the key and value.
        Parameters:
        tr - The test to get annotations for.
        Returns:
        Null if there are no annotations. May also be null if the test does not exist.
        Throws:
        java.lang.NullPointerException - if the parameter is null.
      • purge

        public boolean purge​(java.lang.String path)
                      throws WorkDirectory.PurgeFault
        Clean the contents of the given path. If path is a directory, it is recursively deleted. If it is a file, that file is removed. Any user confirmation should be done before calling this method. If the path does not exist in this work directory, false is returned.
        Parameters:
        path - Path to a directory in this work directory or a path to a jtr file. A zero length string removes the root.
        Returns:
        true is the purge occurred normally, false if the purge did not complete for some reason. Most failures to purge will be announced by Faults. A null parameter will result in false.
        Throws:
        WorkDirectory.PurgeFault - If the file cannot be removed; the message field may not contain any useful information due to deficiencies in java.io.File.delete()..