satin.common
Class TimeLimit

java.lang.Object
  |
  +--satin.common.TimeLimit

public class TimeLimit
extends java.lang.Object

Sets a time limit and throws an exception when it expires. Use this class when you're waiting for some event to occur, and you don't want to wait forever. To use a TimeLimit, simply construct one and then call check or checkAndSleep periodically. When you're through with the TimeLimit, no special action is necessary; a TimeLimit will only throw an exception when one of its check methods is called.

Example

     // Wait for a window to become visible. 
     AWindow w = getSomeWindowFromSomewhere();
     TimeLimit t = new TimeLimit(5, "window not visible");
     while (! w.isVisible())
         t.check();

If the window does not become visible within 5 seconds, an exception will be thrown which, if printed by the Java runtime system, will look something like this:

Exception in thread "main" satin.common.TimeLimit$Expired: after 5.0 seconds, window not visible

Author:

Ed Stauff

Inner Class Summary

static class

TimeLimit.Expired Indicates the expiration of a TimeLimit object.

Constructor Summary

TimeLimit(double seconds, java.lang.String waitingWhile)
Constructs a time limit object.

Method Summary

java.lang.String	_dump() Dumps the state of the time limit object.
void	check() Checks to see if the time limit has expired.
void	checkAndSleep(double seconds) Checks to see if the time limit has expired, and then sleeps.

Methods inherited from class java.lang.Object

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

Constructor Detail

TimeLimit

public TimeLimit(double seconds,
                 java.lang.String waitingWhile)

Constructs a time limit object.

Parameters:

seconds

the maximum number of seconds to wait after the object is constructed.

waitingWhile

the existing condition that you're waiting for to end. (Not the event that you're waiting for to happen.)

Method Detail

check

public void check()
           throws TimeLimit.Expired

Checks to see if the time limit has expired. If the time limit has expired, it throws a TimeLimit.Expired. The time limit expires when the elapsed time since the object was created exceeds the time limit specified in the constructor. This is the only method that actually checks for expiration and throws an exception.

checkAndSleep

public void checkAndSleep(double seconds)
                   throws TimeLimit.Expired

Checks to see if the time limit has expired, and then sleeps. This method calls check and then sleeps for the given number of seconds before returning. Use this method to give the application under test a chance to breathe between checks.

Parameters:

seconds

the number of seconds to sleep. Must be greater than or equal to zero.

_dump

public java.lang.String _dump()

Dumps the state of the time limit object. Does not check to see if the time limit has expired. This is intended only for use during debugging of Java code. Information includes the time limit, description string, time remaining, and the number of times check() has been called.

Revision History

6/15/01 Ed Stauff - made changes per code review.

6/12/01 Ed Stauff - made changes per API review.

6/11/01 - Initial review by Satin team.

23 May 2001 Ed Stauff - file created.