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,
 * 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:
 *
 * <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
 * 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</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 of 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
     */
    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);  
    }

    /**
     * Fail, also setting status to indicate current testcase should fail
     */ 
    public void threadFail(String reason) {
        threadFailed = true;
        fail(reason);
    }

    /**
     * If expression not true, set status to indicate current testcase
     * should fail
     */ 
    public void threadAssertTrue(boolean b) {
        if (!b) {
            threadFailed = true;
            assertTrue(b);
        }
    }

    /**
     * If expression not false, set status to indicate current testcase
     * should fail
     */ 
    public void threadAssertFalse(boolean b) {
        if (b) {
            threadFailed = true;
            assertFalse(b);
        }
    }

    /**
     * If argument not null, set status to indicate current testcase
     * should fail
     */ 
    public void threadAssertNull(Object x) {
        if (x != null) {
            threadFailed = true;
            assertNull(x);
        }
    }

    /**
     * If arguments not equal, set status to indicate current testcase
     * should fail
     */ 
    public void threadAssertEquals(long x, long y) {
        if (x != y) {
            threadFailed = true;
            assertEquals(x, y);
        }
    }

    /**
     * If arguments not equal, set status to indicate current testcase
     * should fail
     */ 
    public void threadAssertEquals(Object x, Object y) {
        if (x != y && (x == null || !x.equals(y))) {
            threadFailed = true;
            assertEquals(x, y);
        }
    }

    /**
     * threadFail with message "should throw exception"
     */ 
    public void threadShouldThrow() {
        threadFailed = true;
        fail("should throw exception");
    }

    /**
     * threadFail with message "Unexpected 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");
        }
    }


    /**
     * fail with message "should throw exception"
     */ 
    public void shouldThrow() {
        fail("Should throw exception");
    }

    /**
     * fail with message "Unexpected exception"
     */
    public void unexpectedException() {
        fail("Unexpected exception");
    }


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

    // Some convenient Integer constants

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


    // Some convenient Runnable classes

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

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

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

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

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

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

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


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

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

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

    /**
     * For use as ThreadFactory in constructors
     */
    static class SimpleThreadFactory implements ThreadFactory{
        public Thread newThread(Runnable r){
            return new Thread(r);
        }   
    }

    static class TrackedRunnable implements Runnable {
        volatile boolean done = false;
        public void run() {
            try {
                Thread.sleep(SMALL_DELAY_MS);
                done = true;
            } catch(Exception e){
            }
        }
    }

    static class TrackedCallable implements Callable {
        volatile boolean done = false;
        public Object call() {
            try {
                Thread.sleep(SMALL_DELAY_MS);
                done = true;
            } catch(Exception e){
            }
            return Boolean.TRUE;
        }
    }

    /**
     * For use as RejectedExecutionHandler in constructors
     */
    static class NoOpREHandler implements RejectedExecutionHandler{
        public void rejectedExecution(Runnable r, ThreadPoolExecutor executor){} 
    }
 
    
}
Revision:	1.5
Committed:	Fri Sep 26 15:33:13 2003 UTC (20 years, 7 months ago) by dl
Branch:	MAIN
Changes since 1.4:	+117 -37 lines
Log Message:	Javadoc fixes
#	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	dl	1.5	* Base class for JSR166 Junit TCK tests. Defines some constants,
16			* utility methods and classes, as well as a simple framework for
17			* helping to make sure that assertions failing in generated threads
18			* cause the associated test that generated them to itself fail (which
19			* JUnit doe not otherwise arrange). The rules for creating such
20			* tests are:
21	dl	1.1	*
22			* <ol>
23			*
24			* <li> All assertions in code running in generated threads must use
25			* the forms {@link threadFail} , {@link threadAssertTrue} {@link
26			* threadAssertEquals}, or {@link threadAssertNull}, (not
27			* <tt>fail</tt>, <tt>assertTrue</tt>, etc.) It is OK (but not
28			* particularly recommended) for other code to use these forms too.
29			* Only the most typically used JUnit assertion methods are defined
30			* this way, but enough to live with.</li>
31			*
32			* <li> If you override {@link setUp} or {@link tearDown}, make sure
33			* to invoke <tt>super.setUp</tt> and <tt>super.tearDown</tt> within
34			* them. These methods are used to clear and check for thread
35			* assertion failures.</li>
36			*
37			* <li>All delays and timeouts must use one of the constants {@link
38			* SHORT_DELAY_MS}, {@link SMALL_DELAY_MS}, {@link MEDIUM_DELAY_MS},
39			* {@link LONG_DELAY_MS}. The idea here is that a SHORT is always
40	dl	1.5	* discriminable from zero time, and always allows enough time for the
41			* small amounts of computation (creating a thread, calling a few
42	dl	1.1	* methods, etc) needed to reach a timeout point. Similarly, a SMALL
43			* is always discriminable as larger than SHORT and smaller than
44			* MEDIUM. And so on. These constants are set to conservative values,
45	dl	1.2	* but even so, if there is ever any doubt, they can all be increased
46			* in one spot to rerun tests on slower platforms</li>
47	dl	1.1	*
48			* <li> All threads generated must be joined inside each test case
49			* method (or <tt>fail</tt> to do so) before returning from the
50			* method. The {@link joinPool} method can be used to do this when
51			* using Executors.</li>
52			*
53			* </ol>
54			*/
55			public class JSR166TestCase extends TestCase {
56
57	dl	1.2	public static long SHORT_DELAY_MS;
58			public static long SMALL_DELAY_MS;
59			public static long MEDIUM_DELAY_MS;
60			public static long LONG_DELAY_MS;
61
62
63			/**
64			* Return the shortest timed delay. This could
65			* be reimplmented to use for example a Property.
66			*/
67			protected long getShortDelay() {
68	dl	1.4	return 100;
69	dl	1.2	}
70
71
72			/**
73	dl	1.5	* Set delays as multiples of SHORT_DELAY.
74	dl	1.2	*/
75			protected void setDelays() {
76			SHORT_DELAY_MS = getShortDelay();
77			SMALL_DELAY_MS = SHORT_DELAY_MS * 5;
78			MEDIUM_DELAY_MS = SHORT_DELAY_MS * 10;
79			LONG_DELAY_MS = SHORT_DELAY_MS * 50;
80			}
81
82	dl	1.1	/**
83			* Flag set true if any threadAssert methods fail
84			*/
85	dl	1.5	volatile boolean threadFailed;
86	dl	1.1
87			/**
88	dl	1.4	* Initialize test to indicate that no thread assertions have failed
89	dl	1.1	*/
90			public void setUp() {
91	dl	1.2	setDelays();
92	dl	1.1	threadFailed = false;
93			}
94
95			/**
96			* Trigger test case failure if any thread assertions have failed
97			*/
98			public void tearDown() {
99			assertFalse(threadFailed);
100			}
101
102	dl	1.5	/**
103			* Fail, also setting status to indicate current testcase should fail
104			*/
105	dl	1.1	public void threadFail(String reason) {
106			threadFailed = true;
107			fail(reason);
108			}
109
110	dl	1.5	/**
111			* If expression not true, set status to indicate current testcase
112			* should fail
113			*/
114	dl	1.1	public void threadAssertTrue(boolean b) {
115			if (!b) {
116			threadFailed = true;
117			assertTrue(b);
118			}
119			}
120	dl	1.5
121			/**
122			* If expression not false, set status to indicate current testcase
123			* should fail
124			*/
125	dl	1.1	public void threadAssertFalse(boolean b) {
126			if (b) {
127			threadFailed = true;
128			assertFalse(b);
129			}
130			}
131	dl	1.5
132			/**
133			* If argument not null, set status to indicate current testcase
134			* should fail
135			*/
136	dl	1.1	public void threadAssertNull(Object x) {
137			if (x != null) {
138			threadFailed = true;
139			assertNull(x);
140			}
141			}
142	dl	1.5
143			/**
144			* If arguments not equal, set status to indicate current testcase
145			* should fail
146			*/
147	dl	1.1	public void threadAssertEquals(long x, long y) {
148			if (x != y) {
149			threadFailed = true;
150			assertEquals(x, y);
151			}
152			}
153	dl	1.5
154			/**
155			* If arguments not equal, set status to indicate current testcase
156			* should fail
157			*/
158	dl	1.1	public void threadAssertEquals(Object x, Object y) {
159			if (x != y && (x == null \|\| !x.equals(y))) {
160			threadFailed = true;
161			assertEquals(x, y);
162			}
163			}
164
165	dl	1.5	/**
166			* threadFail with message "should throw exception"
167			*/
168	dl	1.3	public void threadShouldThrow() {
169			threadFailed = true;
170			fail("should throw exception");
171			}
172
173	dl	1.5	/**
174			* threadFail with message "Unexpected exception"
175			*/
176	dl	1.3	public void threadUnexpectedException() {
177			threadFailed = true;
178			fail("Unexpected exception");
179			}
180
181
182	dl	1.1	/**
183			* Wait out termination of a thread pool or fail doing so
184			*/
185			public void joinPool(ExecutorService exec) {
186			try {
187			exec.shutdown();
188			assertTrue(exec.awaitTermination(LONG_DELAY_MS, TimeUnit.MILLISECONDS));
189			} catch(InterruptedException ie) {
190	dl	1.3	fail("Unexpected exception");
191	dl	1.1	}
192			}
193
194	dl	1.5
195			/**
196			* fail with message "should throw exception"
197			*/
198	dl	1.3	public void shouldThrow() {
199			fail("Should throw exception");
200			}
201
202	dl	1.5	/**
203			* fail with message "Unexpected exception"
204			*/
205	dl	1.3	public void unexpectedException() {
206			fail("Unexpected exception");
207			}
208	dl	1.1
209
210			/**
211			* The number of elements to place in collections, arrays, etc.
212			*/
213	dl	1.5	static final int SIZE = 20;
214	dl	1.1
215			// Some convenient Integer constants
216
217	dl	1.5	static final Integer zero = new Integer(0);
218			static final Integer one = new Integer(1);
219			static final Integer two = new Integer(2);
220			static final Integer three = new Integer(3);
221			static final Integer four = new Integer(4);
222			static final Integer five = new Integer(5);
223			static final Integer six = new Integer(6);
224			static final Integer seven = new Integer(7);
225			static final Integer eight = new Integer(8);
226			static final Integer nine = new Integer(9);
227			static final Integer m1 = new Integer(-1);
228			static final Integer m2 = new Integer(-2);
229			static final Integer m3 = new Integer(-3);
230			static final Integer m4 = new Integer(-4);
231			static final Integer m5 = new Integer(-5);
232			static final Integer m10 = new Integer(-10);
233	dl	1.1
234
235			// Some convenient Runnable classes
236
237	dl	1.5	static class NoOpRunnable implements Runnable {
238	dl	1.1	public void run() {}
239			}
240
241	dl	1.5	static class NoOpCallable implements Callable {
242	dl	1.1	public Object call() { return Boolean.TRUE; }
243			}
244
245	dl	1.5	class ShortRunnable implements Runnable {
246	dl	1.1	public void run() {
247			try {
248			Thread.sleep(SHORT_DELAY_MS);
249			}
250			catch(Exception e) {
251	dl	1.3	threadUnexpectedException();
252	dl	1.1	}
253			}
254			}
255
256	dl	1.5	class ShortInterruptedRunnable implements Runnable {
257	dl	1.1	public void run() {
258			try {
259			Thread.sleep(SHORT_DELAY_MS);
260	dl	1.3	threadShouldThrow();
261	dl	1.1	}
262			catch(InterruptedException success) {
263			}
264			}
265			}
266
267	dl	1.5	class SmallRunnable implements Runnable {
268	dl	1.1	public void run() {
269			try {
270			Thread.sleep(SMALL_DELAY_MS);
271			}
272			catch(Exception e) {
273	dl	1.3	threadUnexpectedException();
274	dl	1.1	}
275			}
276			}
277
278	dl	1.5	class SmallCallable implements Callable {
279	dl	1.1	public Object call() {
280			try {
281			Thread.sleep(SMALL_DELAY_MS);
282			}
283			catch(Exception e) {
284	dl	1.3	threadUnexpectedException();
285	dl	1.1	}
286			return Boolean.TRUE;
287			}
288			}
289
290	dl	1.5	class SmallInterruptedRunnable implements Runnable {
291	dl	1.1	public void run() {
292			try {
293			Thread.sleep(SMALL_DELAY_MS);
294	dl	1.3	threadShouldThrow();
295	dl	1.1	}
296			catch(InterruptedException success) {
297			}
298			}
299			}
300
301
302	dl	1.5	class MediumRunnable implements Runnable {
303	dl	1.1	public void run() {
304			try {
305			Thread.sleep(MEDIUM_DELAY_MS);
306			}
307			catch(Exception e) {
308	dl	1.3	threadUnexpectedException();
309	dl	1.1	}
310			}
311			}
312
313	dl	1.5	class MediumInterruptedRunnable implements Runnable {
314	dl	1.1	public void run() {
315			try {
316			Thread.sleep(MEDIUM_DELAY_MS);
317	dl	1.3	threadShouldThrow();
318	dl	1.1	}
319			catch(InterruptedException success) {
320			}
321			}
322			}
323
324	dl	1.5	class MediumPossiblyInterruptedRunnable implements Runnable {
325	dl	1.1	public void run() {
326			try {
327			Thread.sleep(MEDIUM_DELAY_MS);
328			}
329			catch(InterruptedException success) {
330			}
331			}
332			}
333	dl	1.5
334			/**
335			* For use as ThreadFactory in constructors
336			*/
337			static class SimpleThreadFactory implements ThreadFactory{
338			public Thread newThread(Runnable r){
339			return new Thread(r);
340			}
341			}
342
343			static class TrackedRunnable implements Runnable {
344			volatile boolean done = false;
345			public void run() {
346			try {
347			Thread.sleep(SMALL_DELAY_MS);
348			done = true;
349			} catch(Exception e){
350			}
351			}
352			}
353
354			static class TrackedCallable implements Callable {
355			volatile boolean done = false;
356			public Object call() {
357			try {
358			Thread.sleep(SMALL_DELAY_MS);
359			done = true;
360			} catch(Exception e){
361			}
362			return Boolean.TRUE;
363			}
364			}
365
366			/**
367			* For use as RejectedExecutionHandler in constructors
368			*/
369			static class NoOpREHandler implements RejectedExecutionHandler{
370			public void rejectedExecution(Runnable r, ThreadPoolExecutor executor){}
371			}
372
373	dl	1.1
374			}