Working in Java time

Learn the basics of calculating elapsed time in Java

By Robert Nielsen, JavaWorld.com, 03/30/01

1. Java reckons time in milliseconds before or after the start of January 1, 1970.
2. The Date class's constructor Date() returns an object that represents the moment the object was created. Date's getTime() method returns a long value whose number equals the number of milliseconds before or after January 1, 1970.
3. The DateFormat class is used to convert Dates to Strings, and vice versa. The static getDateInstance() method returns a DateFormat object in the default format; the getDateInstance(DateFormat.FIELD) returns a DateFormat object with a specified format. The format(Date d) method returns a String that represents the date, such as "January 1, 2002." Conversely, the parse(String s) method returns a Date object based on the date the String argument represents.
4. The appearance of Strings returned by the format() method can vary according to the regional settings on the computer where the program is being run.
5. The GregorianCalendar class has two important constructors: GregorianCalendar(), which returns an object that represents the moment it was created, and the GregorianCalendar(int year, int month, int date) constructor used to create an object that represents an arbitrary date. The GregorianCalendar class's getTime() method returns a Date object. The add(int field, int amount) method calculates dates by adding or subtracting units of time like days, months, or years.

GregorianCalendar and time

Two GregorianCalendar class constructors can be used to deal with time. The first creates an object that represents a date, hour, and minute:

GregorianCalendar(int year, int month, int date, int hour, int minute)

The second creates an object that represents a date, hour, minute, and second:

GregorianCalendar(int year, int month, int date, int hour, int minute, int second)

First, I should note that each constructor requires date information (year, month, and day) in addition to time information. If you want to talk about 2:30 p.m., you must specify the date.

Also, each GregorianCalendar constructor creates an object that represents a moment in time calculated to the nearest millisecond. Thus, if your constructor takes arguments for only the year, month, and date, then the values for hours, minutes, seconds, and milliseconds are set to zero. Similarly, if your constructor takes arguments for year, month, date, hours, and minutes, then seconds and milliseconds are set to zero.

DateFormat and time

To create a DateFormat object to display time and date, you can use the static method getDateTimeInstance(int dateStyle, int timeStyle). That method specifies the date and time styles you wish to use. If you are happy with the default styles, you can substitute the shorter getDateTimeInstance().

To create a DateFormat object to display just the time, you can use the static method getTimeInstance(int timeStyle).

The program below shows how the getDateTimeInstance() and getTimeInstance() methods work:

import java.util.*;
import java.text.*;
public class Apollo {
   public static void main(String[] args) {
      GregorianCalendar liftOffApollo11 = new GregorianCalendar(1969, Calendar.JULY, 16, 9, 32);
      Date d = liftOffApollo11.getTime();
      DateFormat df1 = DateFormat.getDateTimeInstance(DateFormat.MEDIUM, DateFormat.MEDIUM);
      DateFormat df2 = DateFormat.getTimeInstance(DateFormat.SHORT);
      String s1 = df1.format(d);
      String s2 = df2.format(d);
      System.out.println(s1);
      System.out.println(s2);
   }
}          

On my computer, the above program displays the following:

Jul 16, 1969 9:32:00 AM
9:32 AM
(Output can vary according to your computer's regional settings.)

Calculating elapsed time

You may sometimes need to calculate elapsed time; for instance, you may want to know the duration of a manufacturing process, given the starting and ending times. A rental company that rents items by the hour or day may also find it useful to calculate elapsed time. Similarly, in the financial world, it is often necessary to calculate interest payments over elapsed time.

To complicate the issue, humans calculate elapsed time in at least two ways. You can say that a day has gone by when 24 hours have elapsed, or when the calendar changes from one day to the next. I'll now discuss those two ways of thinking.

Elapsed time, case 1: Full units

In this case, a day has not elapsed until 24 hours have passed, an hour has not elapsed until 60 minutes have passed, a minute has not elapsed until 60 seconds have passed, and so on. Under this method, 23 hours of elapsed time would translate to zero days.

To calculate elapsed time this way, you start by calculating elapsed milliseconds. To do so, first convert each date to the number of milliseconds since the start of January 1, 1970. You then subtract the first millisecond value from the second millisecond value. Here is a sample calculation:

import java.util.*;
public class ElapsedMillis {
   public static void main(String[] args) {
      GregorianCalendar gc1 = new GregorianCalendar(1995, 11, 1, 3, 2, 1);
      GregorianCalendar gc2 = new GregorianCalendar(1995, 11, 1, 3, 2, 2);
      // the above two dates are one second apart
      Date d1 = gc1.getTime();
      Date d2 = gc2.getTime();
      long l1 = d1.getTime();
      long l2 = d2.getTime();
      long difference = l2 - l1;
      System.out.println("Elapsed milliseconds: " + difference);
   }
}     

The above program prints the following:

Elapsed milliseconds: 1000

That program also causes some confusion. The GregorianCalendar class's getTime() returns a Date object, while the Date class's getTime() method returns a long number representing the milliseconds before or after the beginning of January 1, 1970. So even though the methods have the same name, their return types are different!

You can convert milliseconds to seconds using simple integer division, as in the following code fragment: