Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.javatest
Class TestResult

    java.lang.Object
      com.sun.javatest.TestResult

    public class TestResult

extends java.lang.Object

The TestResult object encapsulates the results from a test. Test results are formatted in sections of command output, comments and sometimes "streams" of output (`stdout` for example). Each of these sections is represented by a (@link TestResult.Section Section). Instances of this class are mutable until the result of the section is set or until the result of the test itself is set. Test results are stored in a structured text files. The TestResult class serves as the API for accessing the various components that make up the result of running a test. The status is cached as its size is small and it is accessed often. This class and inner classes will throw IllegalStateExceptions if an attempt is made to modify the any part of the object that has been marked immutable.

Nested Class Summary
`static class` | `TestResult.Fault` This exception is to report problems using TestResult objects.
`static interface` | `TestResult.Observer` An interface to observe activity in a TestResult as it is created.
`static class` | `TestResult.ReloadFault` This exception ay occur anytime the JTR file is being read from the filesystem.
`static class` | `TestResult.ResultFileNotFoundFault` This exception is thrown if the JTR file cannot be found.
`class` | `TestResult.Section` This "section" is the logical combination of a single action during test execution.

Field Summary
`static int` | `BAD_CHECKSUM` A code indicating that an invalid checksum was found in a .jtr file.
`static java.lang.String` | `DESCRIPTION` The name of the property that defines the test description file.
`static java.lang.String` | `END` The name of the property that defines the time at which the test execution finished.
`static java.lang.String` | `ENVIRONMENT` The name of the property that defines the environment name.
`static java.lang.String` | `EXEC_STATUS` The name of the property that defines the test execution status.
`static int` | `GOOD_CHECKSUM` A code indicating that a good checksum was found in a .jtr file.
`static java.lang.String` | `JAVATEST_OS` The name of the property that defines the OS on which JT Harness was running when the test was run.
`static java.lang.String` | `MESSAGE_OUTPUT_NAME` The name of the default output that all Sections are equipped with.
`static java.lang.String` | `MSG_SECTION_NAME` The name of the default section that all TestResult objects are equipped with.
`static int` | `NO_CHECKSUM` A code indicating that no checksum was found in a .jtr file.
`static int` | `NUM_CHECKSUM_STATES` The number of different checksum states (none, good, bad).
`static java.lang.String` | `SCRIPT` The name of the property that defines the script that ran the test.
`static java.lang.String` | `SECTIONS` The name of the property that defines the test output sections that were recorded when the test ran.
`static java.lang.String` | `START` The name of the property that defines the time at which the test execution started.
`static java.lang.String` | `TEST` The name of the property that defines the test for which this is the result object.
`static java.lang.String` | `VERSION` The name of the property that defines which version of JT Harness was used to run the test.
`static java.lang.String` | `WORK` The name of the property that defines the work directory for the test.

Constructor Summary
`TestResult(java.io.File file)` Reconstruct the results of a previously run test.
`TestResult(TestDescription td)` Construct a test result object that will be built as the test runs.
`TestResult(TestDescription td, Status s)` Create a temporary test result for which can be handed around in situations where a reasonable test result can't be created.
`TestResult(TestDescription td, WorkDirectory workDir)` Reconstruct the results of a previously run test.
`TestResult(WorkDirectory workDir, java.lang.String workRelativePath)` Reconstruct the results of a previously run test.

Method Summary
`void` | `addObserver(TestResult.Observer obs)` Add an observer to watch this test result for changes.
`TestResult.Section` | `createSection(java.lang.String name)` Create a new section inside this test result.
`static java.lang.String` | `formatDate(java.util.Date d)` Format the date format used for timestamps, such as the start/stop timestamp.
`byte` | `getChecksumState()` Get info about the checksum in this object.
`TestDescription` | `getDescription()` Get the description of the test from which this result was created.
`long` | `getEndTime()` Gets the time when the test was completed, or at least the time when it's final status was set.
`java.util.Map` | `getEnvironment()` Get a copy of the environment that this object has stored.
`java.io.File` | `getFile()` Get the name, if any, for the result file for this object.
`TestResultTable.TreeNode` | `getParent()` Get the parent node in the test result table that contains this test result object.
`java.lang.String` | `getProperty(java.lang.String name)` Get the value of a property of this test result.
`java.util.Enumeration` | `getPropertyNames()` Get the keys of the properties that this object has stored.
`TestResult.Section` | `getSection(int index)` Get the section specified by index.
`int` | `getSectionCount()` Find out how many sections this test result contains.
`java.lang.String[]` | `getSectionTitles()` Get the titles of all sections in this test result.
`Status` | `getStatus()` Get the status for this test.
`java.io.PrintWriter` | `getTestCommentWriter()` A way to write comments about the test execution into the results.
`java.lang.String` | `getTestName()` Get the test name, as given by the test URL defined by TestDescription.getRootRelativeURL().
`java.lang.String` | `getWorkRelativePath()` Get the path name for the results file for this test, relative to the work directory.
`static java.lang.String` | `getWorkRelativePath(java.lang.String testURL)` Get the path name for the results file for a test, relative to the work directory.
`static java.lang.String` | `getWorkRelativePath(java.lang.String baseURL, java.lang.String testId)` Get the path name for the results file for a test, relative to the work directory.
`static java.lang.String` | `getWorkRelativePath(TestDescription td)` Get the path name for the results file for a test, relative to the work directory.
`boolean` | `isMutable()` Determine if the test result object is still mutable.
`boolean` | `isReloadable()` Check whether this test result can be reloaded from a file.
`static boolean` | `isResultFile(java.io.File f)` Check if this file is or appears to be a result (.jtr) file, according to its filename extension.
`boolean` | `isShrunk()` Check whether this object has been "shrunk" to reduce its memory footprint.
`static TestResult` | `notRun(TestDescription td)` Create a placeholder TestResult for a test that has not yet been run.
`static java.util.Date` | `parseDate(java.lang.String s)` Parse the date format used for timestamps, such as the start/stop timestamp.
`void` | `putProperty(java.lang.String name, java.lang.String value)` Add a new property value to this TestResult.
`void` | `reloadFromWorkDir(WorkDirectory workDir)` Reconstruct the results of a previously run test.
`void` | `removeObserver(TestResult.Observer obs)` Remove an observer that was previously added.
`void` | `resetFile()`
`void` | `setEnvironment(TestEnvironment environment)` Set the environment used by this test.
`void` | `setStatus(Status stat)` Set the result of this test.
`void` | `writeResults(WorkDirectory workDir, BackupPolicy backupPolicy)` Writes the TestResult into a version 2 jtr file.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### NO_CHECKSUM

    public static final int NO_CHECKSUM

  A code indicating that no checksum was found in a .jtr file.

  See Also:
    `getChecksumState()`, Constant Field Values

### BAD_CHECKSUM

    public static final int BAD_CHECKSUM

  A code indicating that an invalid checksum was found in a .jtr file.

  See Also:
    `getChecksumState()`, Constant Field Values

### GOOD_CHECKSUM

    public static final int GOOD_CHECKSUM

  A code indicating that a good checksum was found in a .jtr file.

  See Also:
    `getChecksumState()`, Constant Field Values

### NUM_CHECKSUM_STATES

    public static final int NUM_CHECKSUM_STATES

  The number of different checksum states (none, good, bad).

  See Also:
    Constant Field Values

### MESSAGE_OUTPUT_NAME

    public static final java.lang.String MESSAGE_OUTPUT_NAME

  The name of the default output that all Sections are equipped with.

  See Also:
    Constant Field Values

### MSG_SECTION_NAME

    public static final java.lang.String MSG_SECTION_NAME

  The name of the default section that all TestResult objects are equipped with.

  See Also:
    Constant Field Values

### DESCRIPTION

    public static final java.lang.String DESCRIPTION

  The name of the property that defines the test description file.

  See Also:
    Constant Field Values

### END

    public static final java.lang.String END

  The name of the property that defines the time at which the test execution finished.

  See Also:
    Constant Field Values

### ENVIRONMENT

    public static final java.lang.String ENVIRONMENT

  The name of the property that defines the environment name.

  See Also:
    Constant Field Values

### EXEC_STATUS

    public static final java.lang.String EXEC_STATUS

  The name of the property that defines the test execution status.

  See Also:
    Constant Field Values

### JAVATEST_OS

    public static final java.lang.String JAVATEST_OS

  The name of the property that defines the OS on which JT Harness was running when the test was run.

  See Also:
    Constant Field Values

### SCRIPT

    public static final java.lang.String SCRIPT

  The name of the property that defines the script that ran the test.

  See Also:
    Constant Field Values

### SECTIONS

    public static final java.lang.String SECTIONS

  The name of the property that defines the test output sections that were recorded when the test ran.

  See Also:
    Constant Field Values

### START

    public static final java.lang.String START

  The name of the property that defines the time at which the test execution started.

  See Also:
    Constant Field Values

### TEST

    public static final java.lang.String TEST

  The name of the property that defines the test for which this is the result object.

  See Also:
    Constant Field Values

### VERSION

    public static final java.lang.String VERSION

  The name of the property that defines which version of JT Harness was used to run the test.

  See Also:
    Constant Field Values

### WORK

    public static final java.lang.String WORK

  The name of the property that defines the work directory for the test.

  See Also:
    Constant Field Values

Constructor Detail

### TestResult

    public TestResult(TestDescription td)

  Construct a test result object that will be built as the test runs. The status string will be "running..." rather than "not run".

  Parameters:
    `td` - The test description to base this new object on. Cannot be null.

### TestResult

    public TestResult(TestDescription td,
                      WorkDirectory workDir)
               throws TestResult.Fault

  Reconstruct the results of a previously run test.

  Parameters:
    `workDir` - Work directory in which the tests were run
    `td` - Description of the test that was run
  Throws:
    `TestResult.Fault` - if there is a problem recreating the results from the appropriate file in the work directory

### TestResult

    public TestResult(java.io.File file)
               throws TestResult.ResultFileNotFoundFault,
                      TestResult.ReloadFault

  Reconstruct the results of a previously run test.

  Parameters:
    `file` - File that the results have been stored into.
  Throws:
    `TestResult.ReloadFault` - if there is a problem recreating the results from the given file
    `TestResult.ResultFileNotFoundFault` - if there is a problem locating the given file

### TestResult

    public TestResult(WorkDirectory workDir,
                      java.lang.String workRelativePath)
               throws TestResult.Fault

  Reconstruct the results of a previously run test.

  Parameters:
    `workDir` - The work directory where previous results for the guven test can be found.
    `workRelativePath` - The path to the JTR to reload, relative to the workdir.
  Throws:
    `TestResult.Fault` - if there is a problem recreating the results from the given file

### TestResult

    public TestResult(TestDescription td,
                      Status s)

  Create a temporary test result for which can be handed around in situations where a reasonable test result can't be created.

  Parameters:
    `td` - Description of the test
    `s` - Status to associate with running the test... presumed to be of the Status.FAILED type.

Method Detail

### notRun

    public static TestResult notRun(TestDescription td)

  Create a placeholder TestResult for a test that has not yet been run.

  Parameters:
    `td` - The test description for the test
  Returns:
    A test result that indicates that the test has not yet been run

### createSection

    public TestResult.Section createSection(java.lang.String name)

  Create a new section inside this test result.

  Parameters:
    `name` - The symbolic name for this new section.
  Returns:
    The new section that was created.

### setEnvironment

    public void setEnvironment(TestEnvironment environment)

  Set the environment used by this test. When the test is run, those entries in the environment that are referenced are noted; those entries will be recorded here in the test result object.

  Parameters:
    `environment` - the test environment used by this test.
  See Also:
    `getEnvironment()`

### setStatus

    public void setStatus(Status stat)

  Set the result of this test. This action makes this object immutable. If a result comparison is needed, it will be done in here.

  Parameters:
    `stat` - A status object representing the outcome of the test
  See Also:
    `getStatus()`

### putProperty

    public void putProperty(java.lang.String name,
                            java.lang.String value)

  Add a new property value to this TestResult.

  Parameters:
    `name` - The name of the property to be updated.
    `value` - The new value of the specified property.

### reloadFromWorkDir

    public void reloadFromWorkDir(WorkDirectory workDir)
                           throws TestResult.Fault

  Reconstruct the results of a previously run test.

  Parameters:
    `workDir` - Work directory in which the tests were run
  Throws:
    `TestResult.Fault` - if an error occurs while reloading the results

### getChecksumState

    public byte getChecksumState()

  Get info about the checksum in this object.

  Returns:
    a value indicating the validity or otherwise of the checksum found while reading this result object.
  See Also:
    `NO_CHECKSUM`, `BAD_CHECKSUM`, `GOOD_CHECKSUM`

### getTestCommentWriter

    public java.io.PrintWriter getTestCommentWriter()

  A way to write comments about the test execution into the results.

  Returns:
    If this is null, then the object is in a state in which it does not accept new messages.

### getTestName

    public java.lang.String getTestName()

  Get the test name, as given by the test URL defined by TestDescription.getRootRelativeURL(). This method always returns a useful string, representing the test name.

  Returns:
    the name of the test for which this is the result object
  See Also:
    `TestDescription.getRootRelativeURL()`

### isReloadable

    public boolean isReloadable()

  Check whether this test result can be reloaded from a file. This method does not validate the contents of the file.

  Returns:
    true if the result file for this object can be read

### isShrunk

    public boolean isShrunk()

  Check whether this object has been "shrunk" to reduce its memory footprint. If it has, some or all of the data will have to be reloaded. This method is somewhat orthogonal to `isReloadable()` and should not be used as a substitute.

  Returns:
    True if this object is currently incomplete, false otherwise.
  See Also:
    `isReloadable()`

### getDescription

    public TestDescription getDescription()
                                   throws TestResult.Fault

  Get the description of the test from which this result was created. Depending on how the test result was created, this information may not be immediately available, and may be recreated from the test result file.

  Returns:
    the test description for this test result object
  Throws:
    `TestResult.Fault` - if there is a problem recreating the description from the results file.

### getWorkRelativePath

    public java.lang.String getWorkRelativePath()

  Get the path name for the results file for this test, relative to the work directory. The internal separator is '/'.

  Returns:
    the path name for the results file for this test, relative to the work directory

### getFile

    public java.io.File getFile()

  Get the name, if any, for the result file for this object. The path information contains platform specific path separators.

  Returns:
    the name, if any, for the result file for this object

### resetFile

    public void resetFile()

### getWorkRelativePath

    public static java.lang.String getWorkRelativePath(TestDescription td)

  Get the path name for the results file for a test, relative to the work directory. The internal separator is '/'.

  Parameters:
    `td` - the test description for the test in question
  Returns:
    the path name for the results file for a test, relative to the work directory

### getWorkRelativePath

    public static java.lang.String getWorkRelativePath(java.lang.String testURL)

  Get the path name for the results file for a test, relative to the work directory. The internal separator is '/'.

  Parameters:
    `testURL` - May not be null;
  Returns:
    The work relative path of the JTR for this test. Null if the given URL is null.

### getWorkRelativePath

    public static java.lang.String getWorkRelativePath(java.lang.String baseURL,
                                                       java.lang.String testId)

  Get the path name for the results file for a test, relative to the work directory. The internal separator is '/'.

  Parameters:
    `baseURL` - May not be null;
    `testId` - The test identifier that goes with the URL. This may be null.
  Returns:
    The work relative path of the JTR for this test. Null if the given URL is null.

### getPropertyNames

    public java.util.Enumeration getPropertyNames()

  Get the keys of the properties that this object has stored.

  Returns:
    the keys of the properties that this object has stored

### getProperty

    public java.lang.String getProperty(java.lang.String name)
                                 throws TestResult.Fault

  Get the value of a property of this test result.

  Parameters:
    `name` - The name of the property to be retrieved.
  Returns:
    The value corresponding to the property name, null if not found.
  Throws:
    `TestResult.Fault` - if there is a problem recreating data from the results file.

### getEnvironment

    public java.util.Map getEnvironment()
                                 throws TestResult.Fault

  Get a copy of the environment that this object has stored.

  Returns:
    a copy of the environment that this object has stored
  Throws:
    `TestResult.Fault` - if there is a problem recreating data from the results file.
  See Also:
    `setEnvironment(com.sun.javatest.TestEnvironment)`

### getParent

    public TestResultTable.TreeNode getParent()

  Get the parent node in the test result table that contains this test result object.

  Returns:
    the parent node in the test result table that contains this test result object.

### isMutable

    public boolean isMutable()

  Determine if the test result object is still mutable. Test results are only mutable while they are being created, up to the point that the final status is set.

  Returns:
    true if the test result object is still mutable, and false otherwise

### getStatus

    public Status getStatus()

  Get the status for this test.

  Returns:
    the status for this test
  See Also:
    `setStatus(com.sun.javatest.Status)`

### getSectionCount

    public int getSectionCount()

  Find out how many sections this test result contains.

  Returns:
    The number of sections in this result.

### getSection

    public TestResult.Section getSection(int index)
                                  throws TestResult.ReloadFault

  Get the section specified by index. Remember that index 0 is the default message section.

  Parameters:
    `index` - The index of the section to be retrieved.
  Returns:
    The requested section. Will be null if the section does not exist.
  Throws:
    `TestResult.ReloadFault` - Will occur if an error is encountered when reloading JTR data. This may be the result of a corrupt or missing JTR file.
  See Also:
    `MSG_SECTION_NAME`

### getSectionTitles

    public java.lang.String[] getSectionTitles()

  Get the titles of all sections in this test result. A null result probably indicates that there are no sections. This is improbable since most test result object automatically have one section.

  Returns:
    The titles, one at a time in the array. Null if the titles do not exist or could not be determined.

### isResultFile

    public static boolean isResultFile(java.io.File f)

  Check if this file is or appears to be a result (.jtr) file, according to its filename extension.

  Parameters:
    `f` - the file to be checked
  Returns:
    true if this file is or appears to be a result (.jtr) file.

### writeResults

    public void writeResults(WorkDirectory workDir,
                             BackupPolicy backupPolicy)
                      throws java.io.IOException

  Writes the TestResult into a version 2 jtr file.

  Parameters:
    `workDir` - The work directory in which to write the results
    `backupPolicy` - a policy object defining what to do if a file already exists with the same name as that which is about to be written.
  Throws:
    `java.lang.IllegalStateException` - This will occur if you attempt to write a result which is still mutable.
    `java.io.IOException` - Occurs when the output file cannot be created or written to. Under this condition, this object will change it status to an error.

### addObserver

    public void addObserver(TestResult.Observer obs)

  Add an observer to watch this test result for changes.

  Parameters:
    `obs` - the observer to be added

### removeObserver

    public void removeObserver(TestResult.Observer obs)

  Remove an observer that was previously added.

  Parameters:
    `obs` - the observer to be removed

### getEndTime

    public long getEndTime()

  Gets the time when the test was completed, or at least the time when it's final status was set. Be aware that if the information is not available in memory, it will be loaded from disk.

  Returns:
    Time when this test acquired its final status setting.
  See Also:
    `setStatus(com.sun.javatest.Status)`, `Date`

### parseDate

    public static java.util.Date parseDate(java.lang.String s)
                                    throws java.text.ParseException

  Parse the date format used for timestamps, such as the start/stop timestamp.

  Parameters:
    `s` - The string containing the date to be restored.
  Throws:
    `java.text.ParseException`
  See Also:
    `formatDate(java.util.Date)`

### formatDate

    public static java.lang.String formatDate(java.util.Date d)

  Format the date format used for timestamps, such as the start/stop timestamp.

  Parameters:
    `d` - The date object to be formatted into a string.
  See Also:
    `parseDate(java.lang.String)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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