test/tck/JSR166TestCase.java

/*
 * Written by members of JCP JSR-166 Expert Group and released to the
 * public domain. Use, modify, and redistribute this code in any way
 * without acknowledgement. Other contributors include Andrew Wright,
 * Jeffrey Hayes, Pat Fischer, Mike Judd.
 */

import junit.framework.*;
import java.util.*;
import java.util.concurrent.*;
import java.io.*;


/**
 * Base class for JSR166 Junit TCK tests.  Defines some constants and
 * utility methods, 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:
 *
 * <ol>
 *
 * <li> All assertions in code running in generated threads must use
 * the forms {@link threadFail} , {@link threadAssertTrue} {@link
 * threadAssertEquals}, or {@link threadAssertNull}, (not
 * <tt>fail</tt>, <tt>assertTrue</tt>, 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.</li>
 *
 * <li> If you override {@link setUp} or {@link tearDown}, make sure
 * to invoke <tt>super.setUp</tt> and <tt>super.tearDown</tt> within
 * them. These methods are used to clear and check for thread
 * assertion failures.</li>
 *
 * <li>All delays and timeouts must use one of the constants {@link
 * SHORT_DELAY_MS}, {@link SMALL_DELAY_MS}, {@link MEDIUM_DELAY_MS},
 * {@link LONG_DELAY_MS}. The idea here is that a SHORT is always
 * discriminatable 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</li>
 *
 * <li> All threads generated must be joined inside each test case
 * method (or <tt>fail</tt> to do so) before returning from the
 * method. The {@link joinPool} method can be used to do this when
 * using Executors.</li>
 *
 * </ol>
 */
public class JSR166TestCase extends TestCase {

    public static long SHORT_DELAY_MS;
    public static long SMALL_DELAY_MS;
    public static long MEDIUM_DELAY_MS;
    public static long LONG_DELAY_MS;


    /**
     * Return the shortest timed delay. This could
     * be reimplmented to use for example a Property.
     */ 
    protected long getShortDelay() {
        return 100;
    }


    /**
     * Set delays as multiples fo SHORT_DELAY.
     */
    protected  void setDelays() {
        SHORT_DELAY_MS = getShortDelay();
        SMALL_DELAY_MS = SHORT_DELAY_MS * 5;
        MEDIUM_DELAY_MS = SHORT_DELAY_MS * 10;
        LONG_DELAY_MS = SHORT_DELAY_MS * 50;
    }

    /**
     * Flag set true if any threadAssert methods fail
     */
    protected volatile boolean threadFailed;

    /**
     * Initialize test to indicate that no thread assertions have failed
     */
    public void setUp() { 
        setDelays();
        threadFailed = false;  
    }

    /**
     * Trigger test case failure if any thread assertions have failed
     */
    public void tearDown() { 
        assertFalse(threadFailed);  
    }

    public void threadFail(String reason) {
        threadFailed = true;
        fail(reason);
    }

    public void threadAssertTrue(boolean b) {
        if (!b) {
            threadFailed = true;
            assertTrue(b);
        }
    }
    public void threadAssertFalse(boolean b) {
        if (b) {
            threadFailed = true;
            assertFalse(b);
        }
    }
    public void threadAssertNull(Object x) {
        if (x != null) {
            threadFailed = true;
            assertNull(x);
        }
    }
    public void threadAssertEquals(long x, long y) {
        if (x != y) {
            threadFailed = true;
            assertEquals(x, y);
        }
    }
    public void threadAssertEquals(Object x, Object y) {
        if (x != y && (x == null || !x.equals(y))) {
            threadFailed = true;
            assertEquals(x, y);
        }
    }

    public void threadShouldThrow() {
        threadFailed = true;
        fail("should throw exception");
    }

    public void threadUnexpectedException() {
        threadFailed = true;
        fail("Unexpected exception");
    }


    /**
     * Wait out termination of a thread pool or fail doing so
     */
    public void joinPool(ExecutorService exec) {
        try {
            exec.shutdown();
            assertTrue(exec.awaitTermination(LONG_DELAY_MS, TimeUnit.MILLISECONDS));
        } catch(InterruptedException ie) {
            fail("Unexpected exception");
        }
    }

    
    public void shouldThrow() {
        fail("Should throw exception");
    }

    public void unexpectedException() {
        fail("Unexpected exception");
    }


    /**
     * The number of elements to place in collections, arrays, etc.
     */
    public static final int SIZE = 20;

    // Some convenient Integer constants

    public static final Integer zero = new Integer(0);
    public static final Integer one = new Integer(1);
    public static final Integer two = new Integer(2);
    public static final Integer three  = new Integer(3);
    public static final Integer four  = new Integer(4);
    public static final Integer five  = new Integer(5);
    public static final Integer six = new Integer(6);
    public static final Integer seven = new Integer(7);
    public static final Integer eight = new Integer(8);
    public static final Integer nine = new Integer(9);
    public static final Integer m1  = new Integer(-1);
    public static final Integer m2  = new Integer(-2);
    public static final Integer m3  = new Integer(-3);
    public static final Integer m4 = new Integer(-4);
    public static final Integer m5 = new Integer(-5);
    public static final Integer m10 = new Integer(-10);


    // Some convenient Runnable classes

    public static class NoOpRunnable implements Runnable {
        public void run() {}
    }

    public static class NoOpCallable implements Callable {
        public Object call() { return Boolean.TRUE; }
    }

    public class ShortRunnable implements Runnable {
        public void run() {
            try {
                Thread.sleep(SHORT_DELAY_MS);
            }
            catch(Exception e) {
                threadUnexpectedException();
            }
        }
    }

    public class ShortInterruptedRunnable implements Runnable {
        public void run() {
            try {
                Thread.sleep(SHORT_DELAY_MS);
                threadShouldThrow();
            }
            catch(InterruptedException success) {
            }
        }
    }

    public class SmallRunnable implements Runnable {
        public void run() {
            try {
                Thread.sleep(SMALL_DELAY_MS);
            }
            catch(Exception e) {
                threadUnexpectedException();
            }
        }
    }

    public class SmallCallable implements Callable {
        public Object call() {
            try {
                Thread.sleep(SMALL_DELAY_MS);
            }
            catch(Exception e) {
                threadUnexpectedException();
            }
            return Boolean.TRUE;
        }
    }

    public class SmallInterruptedRunnable implements Runnable {
        public void run() {
            try {
                Thread.sleep(SMALL_DELAY_MS);
                threadShouldThrow();
            }
            catch(InterruptedException success) {
            }
        }
    }


    public class MediumRunnable implements Runnable {
        public void run() {
            try {
                Thread.sleep(MEDIUM_DELAY_MS);
            }
            catch(Exception e) {
                threadUnexpectedException();
            }
        }
    }

    public class MediumInterruptedRunnable implements Runnable {
        public void run() {
            try {
                Thread.sleep(MEDIUM_DELAY_MS);
                threadShouldThrow();
            }
            catch(InterruptedException success) {
            }
        }
    }

    public class MediumPossiblyInterruptedRunnable implements Runnable {
        public void run() {
            try {
                Thread.sleep(MEDIUM_DELAY_MS);
            }
            catch(InterruptedException success) {
            }
        }
    }
    
}
Revision:	1.4
Committed:	Thu Sep 25 11:02:41 2003 UTC (20 years, 7 months ago) by dl
Branch:	MAIN
Changes since 1.3:	+2 -2 lines
Log Message:	improve tck javadocs; rename and add a few tests
#	User	Rev	Content
1	dl	1.1	/*
2			* Written by members of JCP JSR-166 Expert Group and released to the
3			* public domain. Use, modify, and redistribute this code in any way
4			* without acknowledgement. Other contributors include Andrew Wright,
5			* Jeffrey Hayes, Pat Fischer, Mike Judd.
6			*/
7
8			import junit.framework.*;
9			import java.util.*;
10			import java.util.concurrent.*;
11			import java.io.*;
12
13
14			/**
15			* Base class for JSR166 Junit TCK tests. Defines some constants and
16			* utility methods, as well as a simple framework for helping to make
17			* sure that assertions failing in generated threads cause the
18			* associated test that generated them to itself fail (which JUnit doe
19			* not otherwise arrange). The rules for creating such tests are:
20			*
21			* <ol>
22			*
23			* <li> All assertions in code running in generated threads must use
24			* the forms {@link threadFail} , {@link threadAssertTrue} {@link
25			* threadAssertEquals}, or {@link threadAssertNull}, (not
26			* <tt>fail</tt>, <tt>assertTrue</tt>, etc.) It is OK (but not
27			* particularly recommended) for other code to use these forms too.
28			* Only the most typically used JUnit assertion methods are defined
29			* this way, but enough to live with.</li>
30			*
31			* <li> If you override {@link setUp} or {@link tearDown}, make sure
32			* to invoke <tt>super.setUp</tt> and <tt>super.tearDown</tt> within
33			* them. These methods are used to clear and check for thread
34			* assertion failures.</li>
35			*
36			* <li>All delays and timeouts must use one of the constants {@link
37			* SHORT_DELAY_MS}, {@link SMALL_DELAY_MS}, {@link MEDIUM_DELAY_MS},
38			* {@link LONG_DELAY_MS}. The idea here is that a SHORT is always
39			* discriminatable from zero time, and always allows enough time for
40			* the small amounts of computation (creating a thread, calling a few
41			* methods, etc) needed to reach a timeout point. Similarly, a SMALL
42			* is always discriminable as larger than SHORT and smaller than
43			* MEDIUM. And so on. These constants are set to conservative values,
44	dl	1.2	* but even so, if there is ever any doubt, they can all be increased
45			* in one spot to rerun tests on slower platforms</li>
46	dl	1.1	*
47			* <li> All threads generated must be joined inside each test case
48			* method (or <tt>fail</tt> to do so) before returning from the
49			* method. The {@link joinPool} method can be used to do this when
50			* using Executors.</li>
51			*
52			* </ol>
53			*/
54			public class JSR166TestCase extends TestCase {
55
56	dl	1.2	public static long SHORT_DELAY_MS;
57			public static long SMALL_DELAY_MS;
58			public static long MEDIUM_DELAY_MS;
59			public static long LONG_DELAY_MS;
60
61
62			/**
63			* Return the shortest timed delay. This could
64			* be reimplmented to use for example a Property.
65			*/
66			protected long getShortDelay() {
67	dl	1.4	return 100;
68	dl	1.2	}
69
70
71			/**
72			* Set delays as multiples fo SHORT_DELAY.
73			*/
74			protected void setDelays() {
75			SHORT_DELAY_MS = getShortDelay();
76			SMALL_DELAY_MS = SHORT_DELAY_MS * 5;
77			MEDIUM_DELAY_MS = SHORT_DELAY_MS * 10;
78			LONG_DELAY_MS = SHORT_DELAY_MS * 50;
79			}
80
81	dl	1.1	/**
82			* Flag set true if any threadAssert methods fail
83			*/
84			protected volatile boolean threadFailed;
85
86			/**
87	dl	1.4	* Initialize test to indicate that no thread assertions have failed
88	dl	1.1	*/
89			public void setUp() {
90	dl	1.2	setDelays();
91	dl	1.1	threadFailed = false;
92			}
93
94			/**
95			* Trigger test case failure if any thread assertions have failed
96			*/
97			public void tearDown() {
98			assertFalse(threadFailed);
99			}
100
101			public void threadFail(String reason) {
102			threadFailed = true;
103			fail(reason);
104			}
105
106			public void threadAssertTrue(boolean b) {
107			if (!b) {
108			threadFailed = true;
109			assertTrue(b);
110			}
111			}
112			public void threadAssertFalse(boolean b) {
113			if (b) {
114			threadFailed = true;
115			assertFalse(b);
116			}
117			}
118			public void threadAssertNull(Object x) {
119			if (x != null) {
120			threadFailed = true;
121			assertNull(x);
122			}
123			}
124			public void threadAssertEquals(long x, long y) {
125			if (x != y) {
126			threadFailed = true;
127			assertEquals(x, y);
128			}
129			}
130			public void threadAssertEquals(Object x, Object y) {
131			if (x != y && (x == null \|\| !x.equals(y))) {
132			threadFailed = true;
133			assertEquals(x, y);
134			}
135			}
136
137	dl	1.3	public void threadShouldThrow() {
138			threadFailed = true;
139			fail("should throw exception");
140			}
141
142			public void threadUnexpectedException() {
143			threadFailed = true;
144			fail("Unexpected exception");
145			}
146
147
148	dl	1.1	/**
149			* Wait out termination of a thread pool or fail doing so
150			*/
151			public void joinPool(ExecutorService exec) {
152			try {
153			exec.shutdown();
154			assertTrue(exec.awaitTermination(LONG_DELAY_MS, TimeUnit.MILLISECONDS));
155			} catch(InterruptedException ie) {
156	dl	1.3	fail("Unexpected exception");
157	dl	1.1	}
158			}
159
160	dl	1.3
161			public void shouldThrow() {
162			fail("Should throw exception");
163			}
164
165			public void unexpectedException() {
166			fail("Unexpected exception");
167			}
168	dl	1.1
169
170			/**
171			* The number of elements to place in collections, arrays, etc.
172			*/
173			public static final int SIZE = 20;
174
175			// Some convenient Integer constants
176
177			public static final Integer zero = new Integer(0);
178			public static final Integer one = new Integer(1);
179			public static final Integer two = new Integer(2);
180			public static final Integer three = new Integer(3);
181			public static final Integer four = new Integer(4);
182			public static final Integer five = new Integer(5);
183			public static final Integer six = new Integer(6);
184			public static final Integer seven = new Integer(7);
185			public static final Integer eight = new Integer(8);
186			public static final Integer nine = new Integer(9);
187			public static final Integer m1 = new Integer(-1);
188			public static final Integer m2 = new Integer(-2);
189			public static final Integer m3 = new Integer(-3);
190			public static final Integer m4 = new Integer(-4);
191			public static final Integer m5 = new Integer(-5);
192			public static final Integer m10 = new Integer(-10);
193
194
195			// Some convenient Runnable classes
196
197			public static class NoOpRunnable implements Runnable {
198			public void run() {}
199			}
200
201			public static class NoOpCallable implements Callable {
202			public Object call() { return Boolean.TRUE; }
203			}
204
205			public class ShortRunnable implements Runnable {
206			public void run() {
207			try {
208			Thread.sleep(SHORT_DELAY_MS);
209			}
210			catch(Exception e) {
211	dl	1.3	threadUnexpectedException();
212	dl	1.1	}
213			}
214			}
215
216			public class ShortInterruptedRunnable implements Runnable {
217			public void run() {
218			try {
219			Thread.sleep(SHORT_DELAY_MS);
220	dl	1.3	threadShouldThrow();
221	dl	1.1	}
222			catch(InterruptedException success) {
223			}
224			}
225			}
226
227			public class SmallRunnable implements Runnable {
228			public void run() {
229			try {
230			Thread.sleep(SMALL_DELAY_MS);
231			}
232			catch(Exception e) {
233	dl	1.3	threadUnexpectedException();
234	dl	1.1	}
235			}
236			}
237
238			public class SmallCallable implements Callable {
239			public Object call() {
240			try {
241			Thread.sleep(SMALL_DELAY_MS);
242			}
243			catch(Exception e) {
244	dl	1.3	threadUnexpectedException();
245	dl	1.1	}
246			return Boolean.TRUE;
247			}
248			}
249
250			public class SmallInterruptedRunnable implements Runnable {
251			public void run() {
252			try {
253			Thread.sleep(SMALL_DELAY_MS);
254	dl	1.3	threadShouldThrow();
255	dl	1.1	}
256			catch(InterruptedException success) {
257			}
258			}
259			}
260
261
262			public class MediumRunnable implements Runnable {
263			public void run() {
264			try {
265			Thread.sleep(MEDIUM_DELAY_MS);
266			}
267			catch(Exception e) {
268	dl	1.3	threadUnexpectedException();
269	dl	1.1	}
270			}
271			}
272
273			public class MediumInterruptedRunnable implements Runnable {
274			public void run() {
275			try {
276			Thread.sleep(MEDIUM_DELAY_MS);
277	dl	1.3	threadShouldThrow();
278	dl	1.1	}
279			catch(InterruptedException success) {
280			}
281			}
282			}
283
284			public class MediumPossiblyInterruptedRunnable implements Runnable {
285			public void run() {
286			try {
287			Thread.sleep(MEDIUM_DELAY_MS);
288			}
289			catch(InterruptedException success) {
290			}
291			}
292			}
293
294			}