You need to determine how much time has elapsed during the execution of a block of code.

Use StopWatch to measure the time it takes to execute a section of code. Example 1-20 demonstrates the use of this class to measure the time it takes to perform simple arithmetic operations.

import org.apache.commons.lang.time.StopWatch;

StopWatch clock = new StopWatch( );
        
System.out.println("Time to Math.sin(0.34) ten million times?" );
clock.start( );
for( int i = 0; i < 100000000; i++ ) {
    Math.sin( 0.34 );
}
clock.stop( );
System.out.println( "It takes " + clock.getTime( ) + " milliseconds" );

clock.reset( );
System.out.println( "How long to multiply 2 doubles one billion times?" );

clock.start( );
for( int i = 0; i < 1000000000; i++) {
    double result = 3423.2234 * 23e-4;
}
clock.stop( );
System.out.println( "It takes " + clock.getTime( ) + " milliseconds." );

This example measures execution time with StopWatch and produces the following output:

Time to Math.sin(0.34) ten million times?
It takes 6865 milliseconds

How long to multiply 2 doubles one billion times?
It takes 1992 milliseconds.

StopWatch performs the same functions as a physical stop watch; you can start, stop, pause, resume, reset, and split the clock. The name of this utility conveys unmistakable meaning: starting, stopping, pausing, and resuming a clock are methods that need no explanation, and resetting an instance of StopWatch simply resets the elapsed time to zero. When a StopWatch is “split” the clock continues to tick, but every call to StopWatch.getTime() will return the time at which split( ) was invoked. This is analogous to the “lap” button on a real stop watch; the StopWatch.split( ) causes StopWatch.getTime( ) to return “lap time.” When a runner completes a lap, you can “freeze” the lap time while the clock continues to count seconds. Once you split a StopWatch, you will need to invoke the StopWatch.unsplit( ) method to measure the total time elapsed since the clock was started.

Example 1-21 demonstrates the split() method on StopWatch. The clock continues to tick for three seconds, and after one second the StopWatch is split. Calling getTime() between the split and unsplit times will return one second. After three seconds, the unsplit( ) method is invoked, and calling getTime( ) returns three seconds. Figure 1-1 shows a timeline for this example.

Figure 1-1. Timeline of StopWatch.split( ) and unsplit( )

import org.apache.commons.lang.time.StopWatch;

System.out.println( "Testing the split( ) method." );

clock.reset( );
clock.start( );
try { Thread.sleep(1000); } catch( Exception e ) {}

clock.split( );
System.out.println( "Split Time after 1 sec: " + clock.getTime( ) );

try { Thread.sleep(1000); } catch( Exception e ) {}
System.out.println( "Split Time after 2 sec: " + clock.getTime( ) );

clock.unsplit( );
try { Thread.sleep(1000); } catch( Exception e ) {}
System.out.println( "Time after 3 sec: " + clock.getTime( ) );

This example produces the following output, which shows that a split at one second resulted in 1001 being returned by the StopWatch after two seconds:

Split Time after 1 sec: 1001
Split Time after 2 sec: 1001
Time after 3 sec: 3004

The same requirements are easily fulfilled without the use of the StopWatch class. A program can measure time by calling System.currentTimeMillis( ) and subtracting the time after a section of code from a time measured before that same section of code; this yields the number of milliseconds elapsed. But the real benefit of using this little Commons Lang utility is to the readability and maintainability of a system. Writing good code is similar to writing a well-written essay, and StopWatch is a clear and concise noun that conveys direct meaning; it is a tangible analogy to a familiar object. In the previous example, the execution time of a block of code was obtained without adding clutter. Statements like clock.start( ) and clock.stop() are more apparent than long time1 = System.currentTimeMillis( ) and long time2 = System.currentTimeMillis( ). And, for the same reasons, clock.getTime() conveys a stronger message than long timeElapsed = time2 - time1.