The Date Class

With the Date class you can create an object that represents a given date and time. You have two ways to do this using the following constructors:

With either constructor you create a Date object that represents a specific instant in time to the nearest millisecond. Carrying dates around as the number of milliseconds since the dawn of the year 1970 won't grab you as being incredibly user-friendly – but we'll come back to how we can interpret a Date object better in a moment. The Date class provides three methods for comparing Date objects:

The equals() method returns true if two different Date objects represent the same date and time. Since the hashCode() method is also implemented for the class, you have all you need to use Date objects as keys in a hash table.

Interpreting Date Objects

The DateFormat class is an abstract class that you can use to create meaningful String representations of Date objects. It isn't in the java.util package though – it's defined in the package java.text. There are four standard representations for the date and the time that are identified by constants defined in the DateFormat class. The effects of these will vary in different countries, because the representation for the date and the time will reflect the conventions of those countries. The constants in the DateFormat class defining the four formats are:

A Locale object identifies information that is specific to a country, a region, or a language. You can define a Locale object for a specific country, for a specific language, for a country and a language, or for a country and a language and a variant, the latter being a vendor or browser specific code such as WIN or MAC. When you are creating a Locale object you use ISO codes to specify the language and/or the country. The language codes are defined by ISO-639. Countries are specified by the country codes in the standard ISO-3166. You can find the country codes on the Internet at:

http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

or at:

http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/en_listp1.html

You can find the language codes at:

http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

or at:

http://lcweb.loc.gov/standards/iso639-2/langhome.html

For some countries, the easiest way to specify the locale, if you don't have the ISO codes on the tip of your tongue, is to use the Locale objects defined within the Locale class. In Java 2 these are:

Because the DateFormat class is abstract, you can't create objects of the class directly, but you can obtain DateFormat objects by using any of the following static methods, each of which returns a value of type DateFormat:

When you've obtained a DateFormat object for the country and the style that you want, and the sort of data you want to format – the date or the time or both – you're ready to produce a String from the Date object.

All you need to do is to pass the Date object to the format() method for the DateFormat object. For example:

Date today = new Date();   // Object for now – today's date
DateFormat fmt = getDateTimeInstance(Locale.FULL, Locale.US);
String formatted = fmt.format(today);

After executing these statements, the String variable, formatted, will contain a full representation of the date and the time when the Date object, today, was created.

We can try out some dates and formats in a simple example.

Try It Out – Producing Dates and Times

This example will show the four different date formats for four countries:

// Trying date formatting
import java.util.Locale;
import java.util.Date;
import java.text.DateFormat;

public class TryDateFormats {
  public static void main(String[] args) {
    Date today = new Date();
    Locale[] locales = {Locale.US, Locale.UK,
                        Locale.GERMANY, Locale.FRANCE};  
    int[] styles = {DateFormat.FULL,DateFormat.LONG,
                     DateFormat.MEDIUM,DateFormat.SHORT}; 
    DateFormat fmt;
    String[] styleText = {"FULL", "LONG", "MEDIUM", "SHORT"};    

    // Output the date for each locale in four styles
    for(int i = 0; i < locales.length; i++) {
      System.out.println("\nThe Date for " + 
                         locales[i].getDisplayCountry() + ":");
      for(int j = 0; j < styles.length; j++) {
        fmt = DateFormat.getDateInstance(styles[j], locales[i]);
        System.out.println( "\tIn " + styleText[j] + 
                            " is " + fmt.format(today));
      }
    }
  }
}

When I compiled and ran this it produced the following output:

The Date for United States:
        In FULL is Saturday, February 9, 2002
        In LONG is February 9, 2002
        In MEDIUM is Feb 9, 2002
        In SHORT is 2/9/02

The Date for United Kingdom:
        In FULL is 09 February 2002
        In LONG is 09 February 2002
        In MEDIUM is 09-Feb-2002
        In SHORT is 09/02/02

The Date for Germany:
        In FULL is Samstag, 9. Februar 2002
        In LONG is 9. Februar 2002
        In MEDIUM is 09.02.2002
        In SHORT is 09.02.02
The Date for France:
        In FULL is samedi 9 fΘvrier 2002
        In LONG is 9 fΘvrier 2002
        In MEDIUM is 9 fΘvr. 2002
        In SHORT is 09/02/02

How It Works

The program creates a Date object for the current date and time, and an array of Locale objects for four countries using values defined in the Locale class. It then creates an array of the four possible styles, and another array containing a String representation for each style that will be used in the output.

The output is produced in the nested for loops. The outer loop iterates over the countries, and the inner loop iterates over the four styles for each country. A DateFormat object is created for each combination of style and country, and the format() method for the DateFormat object is called to produce the formatted date string in the inner call to println().

There are a couple of ways you could change the program. You could initialize the locales [] array with the expression DateFormat.getAvailableLocales(). This will return an array of type Locale containing all of the supported locales, but be warned – there are a lot of them. You'll also find that the characters won't display for many countries because your machine doesn't support the country-specific character set. You could also use the method getTimeInstance() or getDateTimeInstance() instead of getDateInstance() to see what sort of output they generate.

Under the covers, a DateFormat object contains a DateFormatSymbols object that contains all the strings for the names of days of the week and other fixed information related to time and dates. This class is also in the java.text package. Normally you don't use the DateFormatSymbols class directly, but it can be useful when all you want are the days of the week.

Date aDate;
DateFormat fmt = DateFormat.getDateInstance(DateFormat.FULL, Locale.US); 
try {
  aDate = fmt.parse("Saturday, July 4, 1998 ");
  System.out.println("The Date string is: " + fmt.format(aDate));

} catch(ParseException e) {
  System.out.println(e);
}

Gregorian Calendars

The Gregorian calendar is the calendar generally in use today in the western world, and is represented by an object of the GregorianCalendar class. A GregorianCalendar object encapsulates time zone information, as well as date and time data. There are no less than seven constructors for GregorianCalendar objects, from the default that creates a calendar with the current date and time in the default locale for your machine, through to a constructor where you can specify the year, month, day, hour, minute, and second. The default suits most situations.

You can create a calendar with a statement such as:

GregorianCalendar calendar = new GregorianCalendar();

This will be set to the current instant in time, and you can retrieve this as a Date object by calling the getTime() method for the calendar:

Date now = calendar.getTime();

You can create a GregorianCalendar object encapsulating a specific date and/or time with the following constructors:

GregorianCalendar(int year, int month, int day)

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

GregorianCalendar(int year, int month, int day,

int hour, int minute, int second)

The day argument is the day within the month, so the value can be from 1 to 28, 29, 30, or 31, depending on the month and whether it's a leap year or not. The month value is zero-based so January is 0 and December is 11.

The GregorianCalendar class is derived from the abstract Calendar class from which it inherits a large number of methods and static constants for use with these methods. The constants includes month values with the names JANUARY to DECEMBER so you could create a calendar object with the statement:

GregorianCalendar calendar = new GregorianCalendar(1967, Calendar.MARCH, 10);

The time zone and locale will be the default for the computer on which this statement executes. If you want to specify a time zone there is a GregorianCalendar constructor that accepts an argument of type TimeZone. The TimeZone class is also defined in the java.util package. You can get the default TimeZone object by calling the static getDefault() method, but if you are going to the trouble of specifying a time zone, you probably want something other than the default. To create a particular time zone you need to know its ID. This is a string specifying a region or country plus a location. For instance, here are some examples of time zone IDs:

To obtain a reference to a TimeZone object corresponding to a given time zone ID, you pass the ID to the static getTimeZone() method. For instance, we could create a Calendar object for the Chicago time zone like this:

GregorianCalendar calendar =
      new GregorianCalendar(TimeZone.getTimeZone("America/Chicago"));

If you want to know what all the time zones IDs are, you could list them like this:

String[] ids = TimeZone.getAvailableIDs();
for(int i = 0 ; i<ids.length ; i++)
  System.out.println(ids[i]);

The calendar created from a TimeZone object will have the default locale. If you want to specify the locale explicitly, there's a constructor that accepts a Locale reference as the second argument. For example:

GregorianCalendar calendar =
      new GregorianCalendar(TimeZone.getTimeZone("America/Chicago"). Locale.US);

You can also create a Calendar object from a locale:

GregorianCalendar calendar =
      new GregorianCalendar(Locale.UK);

This will create a calendar set to the current time in the default time zone within the UK.

calendar.setTime(date);  

GregorianCalendar calendar = new GregorianCalendar();
calendar.set(1995, 10, 29);  // Date set to 29th November 1999

calendar.set(Calendar.DAY_OF_WEEK, Calendar.TUESDAY);

int day = calendar.get(calendar.DAY_OF_WEEK);

if(day == calendar.SATURDAY)
  // Go to game...

switch(day) {
  case Calendar.MONDAY:
  // do the washing...
  break;
  case Calendar.MONDAY:
  // do something else...
  break;
  // etc...
}

calendar.add(calendar.YEAR, 14);  // 14 years into the future

calendar.add(calendar.MONTH, -6);  // Go back 6 months

calendar.roll(calendar.MONTH, false);  // Go back a month

if(thisDate.before(today))
  // Do something

if(today.after(thisDate))
  // Do something

import java.util.GregorianCalendar;
import java.text.DateFormatSymbols;

class TryCalendar {
  public static void main(String[] args) {
    FormattedInput in = new FormattedInput();

    // Get the date of birth from the keyboard
    System.out.println("Enter your birth date as dd mm yyyy: ");
    int day = in.readInt();
    int month = in.readInt();
    int year = in.readInt();

    // Create birth date calendar – month is 0 to 11
    GregorianCalendar birthdate = new GregorianCalendar(year, month-1,day);
    GregorianCalendar today = new GregorianCalendar();  // Today's date

    // Create this year's birthday
    GregorianCalendar birthday = new GregorianCalendar(
                                        today.get(today.YEAR),
                                        birthdate.get(birthdate.MONTH),
                                        birthdate.get(birthdate.DATE));  

    int age = today.get(today.YEAR) – birthdate.get(birthdate.YEAR);

    String[] weekdays = new DateFormatSymbols().getWeekdays(); // Get day names

    System.out.println("You were born on a " + 
                        weekdays[birthdate.get(birthdate.DAY_OF_WEEK)]);
    System.out.println("This year you " + 
                        (birthday.after(today)   ?"will be " : "are ") +
                        age + " years old.");
    System.out.println("This year your birthday "+
                       (today.before(birthday)? "will be": "was")+
                       " on a "+ weekdays[birthday.get(birthday.DAY_OF_WEEK)]);
  }
}

Enter your birth date as dd mm yyyy:
5 12 1964
You were born on a Saturday
This year you will be 34 years old.
This year your birthday will be on a Saturday