Package com.sun.ts.lib.harness

# Class Status

java.lang.Object
com.sun.ts.lib.harness.Status

Direct Known Subclasses:
  `ReasonableStatus`

public class Status extends Object

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `ERROR`
  A return code indicating that the test was not run because some error occurred before the test could even be attempted.
  `static final String`
  `EXIT_PREFIX`
  A string used to prefix the status when it is written to System.err by `exit()`.
  `static final int[]`
  `exitCodes`
  Exit codes used by TestStatus.exit corresponding to PASSED, FAILED, ERROR, NOT_RUN.
  `static final int`
  `FAILED`
  A return code indicating that the test was executed but the test reported that it failed.
  `static final int`
  `NOT_RUN`
  A return code indicating that the test has not yet been run in this context.
  `static final int`
  `NUM_STATES`
  Number of states which are predefined as "constants".
  `static final int`
  `PASSED`
  A return code indicating that the test was executed and was successful.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Status(int type, String reason)`
  Create a TestStatus object.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Status`
  `augment(Status aux)`
  Return a new TestStatus object with a possibly augmented reason field.
  `Status`
  `augment(String aux)`
  Return a new TestStatus object with a possibly augmented reason field.
  `static String`
  `decode(String str)`
  Decodes string encoded by encode(String) method.
  `static String`
  `encode(String str)`
  Encodes strings containing non-ascii characters, where all characters are replaced with with their Unicode code.
  `static Status`
  `error(String reason)`
  Create a TestStatus to indicate that an error occurred while trying to run a test: i.e.
  `void`
  `exit()`
  Convenience exit() function for the main() of tests to exit in such a way that the status passes up across process boundaries without losing information (ie exit codes don't give the associated text of the status and return codes when exceptions are thrown could cause unintended results).
  `static Status`
  `failed(String reason)`
  Create a TestStatus to indicate the unsuccessful outcome of a test: i.e.
  `String`
  `getReason()`
  Get the message given when the status was created.
  `int`
  `getType()`
  Get the type code indicating the type of this TestStatus object.
  `boolean`
  `isError()`
  Check if the type code of the status is ERROR.
  `boolean`
  `isFailed()`
  Check if the type code of the status is FAILED.
  `boolean`
  `isNotRun()`
  Check if the type code of the status is NOT_RUN.
  `boolean`
  `isPassed()`
  Check if the type code of the status is PASSED.
  `static Status`
  `notApplicable(String reason)`
  Deprecated.
  `static Status`
  `parse(String s)`
  Parse a string-form of a TestStatus.
  `static Status`
  `passed(String reason)`
  Create a TestStatus to indicate the successful outcome of a test.
  `String`
  `toString()`
  Convert a TestStatus to a string.
  `static String`
  `typeToString(int typeNum)`
  Translate the type number to a descriptive string.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### PASSED

    public static final int PASSED
    A return code indicating that the test was executed and was successful.
    See Also:
      - `passed(java.lang.String)`
      - `getType()`
      - Constant Field Values

  - ### FAILED

    public static final int FAILED
    A return code indicating that the test was executed but the test reported that it failed.
    See Also:
      - `failed(java.lang.String)`
      - `getType()`
      - Constant Field Values

  - ### ERROR

    public static final int ERROR
    A return code indicating that the test was not run because some error occurred before the test could even be attempted. This is generally a more serious error than FAILED.
    See Also:
      - `getType()`
      - Constant Field Values

  - ### NOT_RUN

    public static final int NOT_RUN
    A return code indicating that the test has not yet been run in this context. (More specifically, no status file has been recorded for this test in the current work directory.) This is for the internal use of the harness only.
    See Also:
      - `getType()`
      - Constant Field Values

  - ### NUM_STATES

    public static final int NUM_STATES
    Number of states which are predefined as "constants".
    See Also:
      - Constant Field Values

  - ### EXIT_PREFIX

    public static final String EXIT_PREFIX
    A string used to prefix the status when it is written to System.err by `exit()`.
    See Also:
      - Constant Field Values

  - ### exitCodes

    public static final int[] exitCodes
    Exit codes used by TestStatus.exit corresponding to PASSED, FAILED, ERROR, NOT_RUN. The only values that should normally be returned from a test are the first three; the other value is provided for completeness. Note: The assignment is historical and cannot easily be changed.

- ## Constructor Details

  - ### Status

    public Status(int type, String reason)
    Create a TestStatus object. See `passed(java.lang.String)`, `failed(java.lang.String)`, `error(java.lang.String)` etc. for more convenient factory methods to create TestStatus objects.
    Parameters:
      `type` - The type code for the TestStatus object.
      `reason` - A short string to store in the status. Unprintable characters (i.e. outside the range 040C to 177C) in the string are replaced by a space. All whitespace runs are reduced to a single whitespace.
    Throws:
      `IllegalArgumentException` - if the specified type is invalid.

- ## Method Details

  - ### passed

    public static Status passed(String reason)
    Create a TestStatus to indicate the successful outcome of a test.
    Parameters:
      `reason` - A short string describing why the test passed.
    Returns:
      a TestStatus to indicate the successful outcome of a test.

  - ### failed

    public static Status failed(String reason)
    Create a TestStatus to indicate the unsuccessful outcome of a test: i.e. the test completed, but the test determined that what was being tested did not pass the test.
    Parameters:
      `reason` - A short string describing why the test failed.
    Returns:
      a TestStatus to indicate the unsuccessful outcome of a test.

  - ### error

    public static Status error(String reason)
    Create a TestStatus to indicate that an error occurred while trying to run a test: i.e. the test did not complete for some reason, and so it could not determine whether what was being tested passed or failed.
    Parameters:
      `reason` - A short string describing the error that occurred.
    Returns:
      a TestStatus to indicate the error outcome of a test.

  - ### notApplicable

    @Deprecated public static Status notApplicable(String reason)
    Deprecated.
    Create a TestStatus to indicate that the test was not run because under the conditions given it was not applicable. This method is retained for backwards compatibility only; the resultant object is of FAILED type.
    Parameters:
      `reason` - A short string describing why the test was not applicable.
    Returns:
      a TestStatus to indicate that a test failed because it was not applicable

  - ### parse

    public static Status parse(String s)
    Parse a string-form of a TestStatus.
    Parameters:
      `s` - a string containing the string form of a TestStatus as generated by `toString()`
    Returns:
      the corresponding TestStatus, or null if it could not be parsed successfully
    See Also:
      - `exit()`

  - ### typeToString

    public static String typeToString(int typeNum)
    Translate the type number to a descriptive string. For example, type 0 corresponds to the "Passed." string.
    Parameters:
      `typeNum` - A number between zero and NUM_STATES
    Returns:
      null if the given integer was out of range, otherwise an appropriate string.

  - ### encode

    public static String encode(String str)
    Encodes strings containing non-ascii characters, where all characters are replaced with with their Unicode code. Encoded string will have the certain prefix and suffix to be distinguished from non-encode one. Strings of ASCII chars only are encoded into themselves.
    Example:

         System.out.println(TestStatus.encode("X ƫ")); // Encoded 58 20 1AB
         System.out.println(TestStatus.encode("Abc1")); // Abc1

    Parameters:
      `str` - - string to encode
    Returns:
      Encoded string or the same string if none non-ascii chars were found
    See Also:
      - `decode(java.lang.String)`

  - ### decode

    public static String decode(String str)
    Decodes string encoded by encode(String) method.
    Parameters:
      `str` - - string to decode
    Returns:
      Decoded string or the same string if encoded prefix/suffix were found
    See Also:
      - `encode(java.lang.String)`

  - ### isPassed

    public boolean isPassed()
    Check if the type code of the status is PASSED.
    Returns:
      true if the type code is PASSED.
    See Also:
      - `passed(java.lang.String)`
      - `getType()`
      - `PASSED`

  - ### isFailed

    public boolean isFailed()
    Check if the type code of the status is FAILED.
    Returns:
      true if the type code is FAILED.
    See Also:
      - `failed(java.lang.String)`
      - `getType()`
      - `FAILED`

  - ### isError

    public boolean isError()
    Check if the type code of the status is ERROR.
    Returns:
      true if the type code is ERROR.
    See Also:
      - `error(java.lang.String)`
      - `getType()`
      - `ERROR`

  - ### isNotRun

    public boolean isNotRun()
    Check if the type code of the status is NOT_RUN.
    Returns:
      true if the type code is ERROR.
    See Also:
      - `getType()`
      - `NOT_RUN`

  - ### getType

    public int getType()
    Get the type code indicating the type of this TestStatus object.
    Returns:
      the type code indicating the type of this TestStatus object.
    See Also:
      - `PASSED`
      - `FAILED`
      - `ERROR`

  - ### getReason

    public String getReason()
    Get the message given when the status was created.
    Returns:
      the string given when this TestStatus object was created.

  - ### augment

    public Status augment(String aux)
    Return a new TestStatus object with a possibly augmented reason field.
    Parameters:
      `aux` - if not null and not empty, it will be combined with the original reason.
    Returns:
      if aux is null or empty, the result will be the same as this object; otherwise, it will be a new object combining the original status reason and the additional information in aux.

  - ### augment

    public Status augment(Status aux)
    Return a new TestStatus object with a possibly augmented reason field.
    Parameters:
      `aux` - a TestStatus to combine with this object
    Returns:
      if aux is null, the result will be the same as this object; otherwise, it will be a new object combining the original status reason and the additional information in aux.

  - ### toString

    public String toString()
    Convert a TestStatus to a string.
    Overrides:
      `toString` in class `Object`
    See Also:
      - `parse(java.lang.String)`

  - ### exit

    public void exit()
    Convenience exit() function for the main() of tests to exit in such a way that the status passes up across process boundaries without losing information (ie exit codes don't give the associated text of the status and return codes when exceptions are thrown could cause unintended results). An identifying marker is written to the error stream, which the script running the test watches for as the last output before returning, followed by the type and reason The method does not return. It calls System.exit with a value dependent on the type.