JSR166TestCase (Apache Geode 1.8.0)
Date: 2018-11-29

org.apache.geode.util

## Class JSR166TestCase

- java.lang.Object
- - org.apache.geode.util.JSR166TestCase

-     public class JSR166TestCase
      extends java.lang.Object

  Base class for JSR166 Junit TCK tests. Defines some constants, utility methods and classes, as well as a simple framework for helping to make sure that assertions failing in generated threads cause the associated test that generated them to itself fail (which JUnit doe not otherwise arrange). The rules for creating such tests are:
  1. All assertions in code running in generated threads must use the forms threadFail, threadAssertTrue, threadAssertEquals, or threadAssertNull, (not `fail`, `assertTrue`, etc.) It is OK (but not particularly recommended) for other code to use these forms too. Only the most typically used JUnit assertion methods are defined this way, but enough to live with.
  2. If you override `setUp()` or `tearDown()`, make sure to invoke `super.setUp` and `super.tearDown` within them. These methods are used to clear and check for thread assertion failures.
  3. All delays and timeouts must use one of the constants `SHORT_DELAY_MS`, `SMALL_DELAY_MS`, `MEDIUM_DELAY_MS`, `LONG_DELAY_MS`. The idea here is that a SHORT is always discriminable from zero time, and always allows enough time for the small amounts of computation (creating a thread, calling a few methods, etc) needed to reach a timeout point. Similarly, a SMALL is always discriminable as larger than SHORT and smaller than MEDIUM. And so on. These constants are set to conservative values, but even so, if there is ever any doubt, they can all be increased in one spot to rerun tests on slower platforms
  4. All threads generated must be joined inside each test case method (or `fail` to do so) before returning from the method. The `joinPool` method can be used to do this when using Executors.

  Other notes

  - Usually, there is one testcase method per JSR166 method covering "normal" operation, and then as many exception-testing methods as there are exceptions the method can throw. Sometimes there are multiple tests per JSR166 method when the different "normal" behaviors differ significantly. And sometimes testcases cover multiple methods when they cannot be tested in isolation.
  - The documentation style for testcases is to provide as javadoc a simple sentence or two describing the property that the testcase method purports to test. The javadocs do not say anything about how the property is tested. To find out, read the code.
  - These tests are "conformance tests", and do not attempt to test throughput, latency, scalability or other performance factors (see the separate "jtreg" tests for a set intended to check these for the most central aspects of functionality.) So, most tests use the smallest sensible numbers of threads, collection sizes, etc needed to check basic conformance.
  - The test classes currently do not declare inclusion in any particular package to simplify things for people integrating them in TCK test suites.
  - As a convenience, the `main` of this class (JSR166TestCase) runs all JSR166 unit tests.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.Integer` | `eight`
    `static java.lang.Integer` | `five`
    `static java.lang.Integer` | `four`
    `static long` | `LONG_DELAY_MS`
    `static java.lang.Integer` | `m1`
    `static java.lang.Integer` | `m10`
    `static java.lang.Integer` | `m2`
    `static java.lang.Integer` | `m3`
    `static java.lang.Integer` | `m4`
    `static java.lang.Integer` | `m5`
    `static java.lang.Class<?>` | `MAP_CLASS`
    `static long` | `MEDIUM_DELAY_MS`
    `static java.lang.Integer` | `nine`
    `static java.lang.Integer` | `one`
    `static java.lang.Integer` | `seven`
    `static long` | `SHORT_DELAY_MS`
    `static java.lang.Integer` | `six`
    `static int` | `SIZE` The number of elements to place in collections, arrays, etc.
    `static long` | `SMALL_DELAY_MS`
    `static java.lang.Integer` | `three`
    `static java.lang.Integer` | `two`
    `static java.lang.Integer` | `zero`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JSR166TestCase()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected long` | `getShortDelay()` Return the shortest timed delay.
    `protected void` | `setDelays()` Set delays as multiples of SHORT_DELAY.
    `void` | `setUp()` Initialize test to indicate that no thread assertions have failed
    `void` | `shouldThrow()` fail with message "should throw exception"
    `void` | `tearDown()` Trigger test case failure if any thread assertions have failed
    `void` | `threadAssertEquals(long x, long y)` If arguments not equal, set status to indicate current testcase should fail
    `void` | `threadAssertEquals(java.lang.Object x, java.lang.Object y)` If arguments not equal, set status to indicate current testcase should fail
    `void` | `threadAssertFalse(boolean b)` If expression not false, set status to indicate current testcase should fail
    `void` | `threadAssertNull(java.lang.Object x)` If argument not null, set status to indicate current testcase should fail
    `void` | `threadAssertTrue(boolean b)` If expression not true, set status to indicate current testcase should fail
    `void` | `threadFail(java.lang.String reason)` Fail, also setting status to indicate current testcase should fail
    `void` | `threadShouldThrow()` threadFail with message "should throw exception"
    `void` | `threadUnexpectedException()` threadFail with message "Unexpected exception"
    `void` | `unexpectedException()` fail with message "Unexpected exception"

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

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

- - ### Field Detail

    - #### SHORT_DELAY_MS

          public static long SHORT_DELAY_MS

    - #### SMALL_DELAY_MS

          public static long SMALL_DELAY_MS

    - #### MEDIUM_DELAY_MS

          public static long MEDIUM_DELAY_MS

    - #### LONG_DELAY_MS

          public static long LONG_DELAY_MS

    - #### MAP_CLASS

          public static java.lang.Class<?> MAP_CLASS

    - #### SIZE

          public static final int SIZE

      The number of elements to place in collections, arrays, etc.
      See Also:
        Constant Field Values

    - #### zero

          public static final java.lang.Integer zero

    - #### one

          public static final java.lang.Integer one

    - #### two

          public static final java.lang.Integer two

    - #### three

          public static final java.lang.Integer three

    - #### four

          public static final java.lang.Integer four

    - #### five

          public static final java.lang.Integer five

    - #### six

          public static final java.lang.Integer six

    - #### seven

          public static final java.lang.Integer seven

    - #### eight

          public static final java.lang.Integer eight

    - #### nine

          public static final java.lang.Integer nine

    - #### m1

          public static final java.lang.Integer m1

    - #### m2

          public static final java.lang.Integer m2

    - #### m3

          public static final java.lang.Integer m3

    - #### m4

          public static final java.lang.Integer m4

    - #### m5

          public static final java.lang.Integer m5

    - #### m10

          public static final java.lang.Integer m10

  - ### Constructor Detail

    - #### JSR166TestCase

          public JSR166TestCase()

  - ### Method Detail

    - #### getShortDelay

          protected long getShortDelay()

      Return the shortest timed delay. This could be reimplmented to use for example a Property.

    - #### setDelays

          protected void setDelays()

      Set delays as multiples of SHORT_DELAY.

    - #### setUp

          public void setUp()
                     throws java.lang.Exception

      Initialize test to indicate that no thread assertions have failed
      Throws:
        `java.lang.Exception`

    - #### tearDown

          public void tearDown()
                        throws java.lang.Exception

      Trigger test case failure if any thread assertions have failed
      Throws:
        `java.lang.Exception`

    - #### threadFail

          public void threadFail(java.lang.String reason)

      Fail, also setting status to indicate current testcase should fail

    - #### threadAssertTrue

          public void threadAssertTrue(boolean b)

      If expression not true, set status to indicate current testcase should fail

    - #### threadAssertFalse

          public void threadAssertFalse(boolean b)

      If expression not false, set status to indicate current testcase should fail

    - #### threadAssertNull

          public void threadAssertNull(java.lang.Object x)

      If argument not null, set status to indicate current testcase should fail

    - #### threadAssertEquals

          public void threadAssertEquals(long x,
                                         long y)

      If arguments not equal, set status to indicate current testcase should fail

    - #### threadAssertEquals

          public void threadAssertEquals(java.lang.Object x,
                                         java.lang.Object y)

      If arguments not equal, set status to indicate current testcase should fail

    - #### threadShouldThrow

          public void threadShouldThrow()

      threadFail with message "should throw exception"

    - #### threadUnexpectedException

          public void threadUnexpectedException()

      threadFail with message "Unexpected exception"

    - #### shouldThrow

          public void shouldThrow()

      fail with message "should throw exception"

    - #### unexpectedException

          public void unexpectedException()

      fail with message "Unexpected exception"