Section 5.4. Dates and Times

5.4. Dates and Times

Java allows dates and times to be represented and manipulated in three forms: as long values or as java.util.Date or java.util.Calendar objects. Java 5.0 introduces the enumerated type java.util.concurrent.TimeUnit. The values of this type represent time granularities or units: seconds, milliseconds, microseconds, and nanoseconds. They have useful convenience methods but do not themselves represent a time value.

5.4.1. Milliseconds and Nanoseconds

At the lowest level, dates and times are represented as a long value that holds the positive or negative number of milliseconds since midnight on January 1, 1970. This special date and time is known as the epoch and is measured in Greenwich Mean Time (GMT) or Universal Time (UTC). To query the current time in this millisecond representation, use System.currentTimeMillis()

long now = System.currentTimeMillis();

In Java 5.0 and later, you can use System.nanoTime() to query time in nanoseconds. This method returns a long number of nanoseconds long. Unlike currentTimeMillis( ), the nanoTime() does not return a time relative to any defined epoch. nanoTime() is good for measuring relative or elapsed time (as long as the elapsed time is not more than 292 years) but is not suitable for absolute time:

long start = System.nanoTime();
doSomething();
long end = System.nanoTime();
long elapsedNanoSeconds = end - start;

5.4.2. The Date Class

java.util.Date is an object wrapper around a long that holds a number of milliseconds since the epoch. Using a Date object instead of a long allows simple conversion to a nonlocalized string with the toString method. Date objects can be compared for equality with the equals( ) method and they can be compared for order with the compareTo() method or the before( ) and after() methods.

The no-argument version of the Date( ) constructor creates a Date that represents the current time. You can also pass a long number of milliseconds to create a Date that represents some other time. getTime( ) returns the millisecond representation of the Date. Date is a mutable class, so you can also pass a number of milliseconds to setTime( ).

Date has a number of methods for querying and setting the year, month, day, hour, minute, and second. All of these methods have been deprecated, however, in favor of the Calendar class, described next.

5.4.3. The Calendar Class

The java.util.Calendar class is a properly localized version of Date. It is simply a wrapper around a long number of milliseconds but can represent that instant in time according to the calendar of the current locale (usually a Gregorian calendar) and the time zone of the current locale. Furthermore, it has methods for querying, setting, and doing arithmetic on the various fields of the date and time.

The code below shows common uses of the Calendar class. Note that the set( ), get(), and add( ) methods all take an initial argument that specifies what field of the date or time is being set, queried, or added to. Fields such as year, day of month, day of week, hour, minute, and second are defined by integer constants in the class. Other integer constants define values for the months and weekdays of the Gregorian calendar. The month constant UNDECIMBER represents a 13th month used in lunar calendars.

// Get a Calendar for current locale and time zone
Calendar cal = Calendar.getInstance();  

// Figure out what day of the year today is
cal.setTimeInMillis(System.currentTimeMillis()); // Set to the current time
int dayOfYear = cal.get(Calendar.DAY_OF_YEAR);  // What day of the year is it?

// What day of the week does the leap day in the year 2008 occur on?
cal.set(2008, Calendar.FEBRUARY, 29);            // Set year, month, day fields
int dayOfWeek = cal.get(Calendar.DAY_OF_WEEK);   // Query a different field

// What day of the month is the 3rd Thursday of May, 2005?
cal.set(Calendar.YEAR, 2005);                    // Set the year
cal.set(Calendar.MONTH, Calendar.MAY);           // Set the month
cal.set(Calendar.DAY_OF_WEEK,Calendar.THURSDAY); // Set the day of week
cal.set(Calendar.DAY_OF_WEEK_IN_MONTH, 3);       // Set the week
int dayOfMonth = cal.get(Calendar.DAY_OF_MONTH); // Query the day in month

// Get a Date object that represents three months from now
cal.setTimeInMillis(System.currentTimeMillis()); // Current time
cal.add(Calendar.MONTH, 3);                      // Add 3 months
Date expiration = cal.getTime();                 // Retrieve result as a Date
long millis = cal.getTimeInMillis();             // or get it as a long

5.4.4. Formatting Dates and Times

The toString() method of Date produces a textual representation of a date and time but does no localization and allows no customization of which fields (day, month and year or hours and minutes, for example) are to be displayed. The toString( ) method should be used only to produce a machine-readable timestamp, not a human-readable string.

Like numbers, dates and times can be converted to strings using the String.format( ) method and the related java.util.Formatter class of Java 5.0. Format strings for displaying dates and times are all two-character sequences that begin with the letter t. The second letter of each sequence specifies the field or set of fields of the date or time to display. For example %tr displays the hours and minutes fields using 24-hour time, and %TD displays the month, day, and year fields separated by slashes. String.format( ) can format a date or time specified as a long, a Date, or a Calendar:

// current hours and minutes
long now = System.currentTimeMillis();
String s = String.format("%tR", now);         // "15:12"

// Current month/day/year
Date d = new Date(now);
s = String.format("%tD", d);                  // "07/13/04"

// Hours and minutes using 12-hour clock
Calendar c = Calendar.getInstance();
c.setTime(d);
s = String.format("%tl:%tM %tp", now, d, c);  // "3:12 pm"

Prior to Java 5.0 and its Formatter class, you can format dates and times using the java.text.DateFormat class, which automatically handles locale-specific conventions for date and time formatting. DateFormat even works correctly in locales that use a calendar other than the common era (Gregorian) calendar in use throughout much of the world:

import java.util.Date;
import java.text.*;

// Display today's date using a default format for the current locale
DateFormat defaultDate = DateFormat.getDateInstance();
System.out.println(defaultDate.format(new Date()));

// Display the current time using a short time format for the current locale
DateFormat shortTime = DateFormat.getTimeInstance(DateFormat.SHORT);
System.out.println(shortTime.format(new Date()));

// Display date and time using a long format for both
DateFormat longTimestamp = 
  DateFormat.getDateTimeInstance(DateFormat.FULL, DateFormat.FULL);
System.out.println(longTimestamp.format(new Date()));

// Use SimpleDateFormat to define your own formatting template
// See java.text.SimpleDateFormat for the template syntax
DateFormat myformat = new SimpleDateFormat("yyyy.MM.dd");  
System.out.println(myformat.format(new Date()));
try {   // DateFormat can parse dates too
  Date leapday = myformat.parse("2000.02.29"); 
}
catch (ParseException e) { /* Handle parsing exception */ }