Locale-Sensitive Data

How to Format Dates and Times

You use one class, DateFormat, to format both dates and times. DateFormat converts internal date and time data into text strings for meaningful display. It can:

• Handle timezones and daylight savings adjustments
• Support multiple calendars
• Support European date fields such as the number of the week in the year
• Support definition of formats with string patterns and can retrieve the normalized pattern
• Can parse anything it can format

Let's look at how the AroundTheWorld applet uses DateFormat to format its current date and time fields and then look at more advanced formatting of data and time data.

AroundTheWorld uses the following code to format the current date:

TimeZone tz = TimeZone.getTimeZone(labels.getString("TimeZone"));
. . .
dateFormatter = DateFormat.getDateInstance(DateFormat.DEFAULT, currentLocale);
dateFormatter.setTimeZone(tz);
dateValue.setText(dateFormatter.format(date));

The first line of code gets a TimeZone object. TimeZones represent a time zone and are used by the date and time formatters to figure out the current date and time for the specified zone. So, if you are running AroundTheWorld in California in the late evening, the date for the France locale is correctly displayed as tomorrow's date because France is several hours ahead of California.

The second line of code gets a date formatter for currentLocale. DateFormat.DEFAULT specifies that the date formatter should use the formatter's default style. DateFormat provides four format styles that control the length of the result, SHORT, MEDIUM, LONG, and FULL. The default style is set to MEDIUM.

Note that the applet called DateFormat's getDateInstance. DateFormat has other factory methods, such as getInstance and getTimeInstance, that create formatters for formatting dates and times together or just times. Later in the program AroundTheWorld uses getTimeInstance to get a formatter for formatting the current time. You'll see this in action in a moment.

The third line sets the formatter's time zone. This ensures that the date and time fields reflect the current date and time in the time zone for the displayed locale.

Finaly, the program calls format to format the date. The format method returns the the date formatted in a String that is then used to set the Label's text.

AroundTheWorld formats the current time in a similar fashion but uses getTimeInstance instead of getDateInstance to get a DateFormat object appropriate for formatting times:

timeFormatter = DateFormat.getTimeInstance(DateFormat.DEFAULT, locale);
TimeZone tz = TimeZone.getTimeZone(labels.getString("TimeZone"));
timeFormatter.setTimeZone(tz);
. . .
timeValue.setText(timeFormatter.format(date));

Note that the current time is updated every second so the code for updating the label's text is in a separate method that gets called by the clock thread.

The two examples shown above are fairly simple--they both use one of DateFormat's default styles. For most programmers, the default styles are good enough. However, other programmers want more control. DateFormat provides the ability to format you own date and time format styles.

Here's another demo program from Taligent that you can use to get an idea of how to customize date and time formatting styles.

Since you can't run the applet, here's a picture of it:

The 1.1 Date text box is the result of using DateFormat to format the data in the millis text box (the date and time when the demo program was first invoked). The Pattern is used to format the date and time. You can control the pattern using the radio buttons and pulldown menus in the lower right of the demo program window.

Here's a guide from Taligent that points out interesting things you can do with the demo program. Experiment with the various settings in the demo program according to Taligent's instructions.

Here's a snippet of Java code that yields the same results as the demo program when it's first invoked:

Calendar calendar = Calendar.getInstance();
Date date = calendar.getTime();
TimeZone tz = TimeZone.getTimeZone("ECT");

DateFormat formatter = DateFormat.getDateTimeInstance(DateFormat.LONG, DateFormat.LONG, Locale.US);
formatter.setTimeZone(tz);
String result = formatter.format(date);
System.out.println(result);

The first three lines of code set up a Date object with the current time and a TimeZone object that represents the time zone for Paris. In the demo program, the time zone is set with the City pulldown menu. So the current date and time in Paris will be displayed.

The fourth line of code gets a DateFormat object. This formatter will include the date and time in the result. (In the demo program this is controlled by the Date and Time Format radio button, in the code it's controlled by the getDateTimeInstance factory method). This formatter will use the LONG styles for formatting the date and the time (corresponding to the Date Style and Time Style pulldown menus in the demo program). In addition, the formatter is set up to format the date and time in a manner appropriate for the United States Locale (the Locale pulldown menu).

Then the code sets the time zone on the formatter, formats the result, and displays it.

Tweaking the settings in the demo applet corresponds to changing this basic Java code in various ways. The following table shows the relationship between the demo programs user interface elements and the number formatter's API.

GUI Element	Java Code Equivalent	Class
	getInstance, getDateTimeInstance	DateFormat
	getDateInstance	DateFormat
	getTimeInstance	DateFormat
	getXxxxxInstance(Locale)	DateFormat
	getDateInstance(dateStyle), getDateInstance(dateStyle, Locale), getDateTimeInstance(dateStyle, timeStyle), getDateInstance(dateStyle, timeStyle, Locale)	DateFormat
	getTimeInstance(timeStyle), getTimeInstance(timeStyle, Locale), getDateTimeInstance(dateStyle, timeStyle), getDateInstance(dateStyle, timeStyle, Locale)	DateFormat
	setTimeZone	DateFormat
	setLenient	DateFormat
	applyPattern	SimpleDateFormat
	applyLocalizedPattern	SimpleDateFormat
	add, roll	Calendar

Let's do an example. Taligent's guide suggests that you do the following in the demo program:

1. Select the Date Format and the English (U.S.) locale
2. In the Pattern field, delete an "M"--the month changes to the abbreviated format
3. Delete another "M"--the month changes to the numeric format

After you've done this, the formatter is no longer using one of its pre-programmed styles. Instead, it's using a user-customized pattern. Here's the Java code that gives the same result:

Calendar calendar = Calendar.getInstance();
Date date = calendar.getTime();
TimeZone tz = TimeZone.getTimeZone("ECT");

SimpleDateFormat formatter = 
	    (SimpleDateFormat)DateFormat.getDateTimeInstance(DateFormat.LONG,
		 DateFormat.LONG, Locale.US);

formatter.setTimeZone(tz);
formatter.applyPattern("MM d, yyyy h:mm:ss a z");
String result = formatter.format(date);
System.out.println(result);

The bold areas of the code mark the differences between this code segment and the previous. The DateFormat had to be changed to a SimpleDateFormat because the DateFormat API does not support patterns. Also, a line of code was added to set the formatter's pattern before formatting the date. This table lists the field specifications that you can use when specifying a pattern for a SimpleDateFormat.

---

This page incorporates material or code copyrighted by Taligent, Inc. For more information on international resources, see their International Fact Sheet.

Locale-Sensitive Data