ListResourceBundle maps a simple list of keys to their localized objects. It is an abstract subclass of ResourceBundle for which you provide a getContents method that returns an array of key/resource pairs as an array of arrays of Object. The keys must be strings, but the resources can be any kind of object. The ListResourceBundle takes this array and builds the maps for the various “get” methods. The following classes use ListResourceBundle to define a few locales for GlobalRes. First, the base bundle:

public class GlobalRes extends ListResourceBundle {
    public static final String HELLO = "hello";
    public static final String GOODBYE = "goodbye";

    public Object[][] getContents() {
        return contents;
    }

    private static final Object[][] contents = {
        { GlobalRes.HELLO,      "Ciao" },
        { GlobalRes.GOODBYE,    "Ciao" },
    };
}

This is the top-level bundle—when no other bundle is found, this will be used. We have chosen Italian for the default. Before any “get” method is executed, GlobalRes.getContents will be invoked and the contents array's values will seed the data structures used by the “get” methods. ListResourceBundle uses an internal lookup table for efficient access; it does not search through your array of keys. The GlobalRes class also defines the constants that name known resources in the bundle. Here is another bundle for a more specific locale:

public class GlobalRes_en extends ListResourceBundle {
    public Object[][] getContents() {
        return contents;
    }

    private static final Object[][] contents = {
        { GlobalRes.HELLO,      "Hello" },
        { GlobalRes.GOODBYE,    "Goodbye" },
    };
}

This bundle covers the English-language locale en. It provides specific values for each localizable string. The next bundle uses the inheritance feature:

public class GlobalRes_en_AU extends ListResourceBundle {
    // mostly like basic English  - our parent bundle

    public Object[][] getContents() { return contents; }

    private static final Object[][] contents = {
        { GlobalRes.HELLO,      "G'day" },
    };
}

This bundle is for English speakers from Australia (AU). It provides a more colloquial version of the HELLO string and inherits all other strings from the general English locale GlobalRes_en. Whenever a resource bundle is instantiated, its parent chain is established. This proceeds by successively dropping the variant, country, and language components from the base bundle name and instantiating those bundles if they exist. If they do exist then setParent is called on the preceding bundle passing the new bundle as the parent. So in our example, when GlobalRes_en_AU is created, the system will create GlobalRes_en and set it as the parent of GlobalRes_en_AU. In turn, the parent of GlobalRes_en will be the base bundle GlobalRes.

Given these classes, someone with an English-language locale (en) would get the values returned by GlobalRes_en unless the locale also specified the country Australia (AU), in which case values from GlobalRes_en_AU would be used. Everyone else would see those in GlobalRes.

PropertyResourceBundle is a subclass of ResourceBundle that reads its list of resources from a text property description. Instead of using an array of key/resource pairs, the text contains key/resource pairs as lines of the form

key=value

Both keys and values must be strings. A PropertyResourceBundle object reads the text from an InputStream passed to the PropertyResourceBundle constructor and uses the information it reads to build a lookup table for efficient access.

The bundle search process that we described earlier actually has an additional step that looks for a file ResName.properties after it looks for a class ResName. For example, if the search process doesn't find the class GlobalRes_eo_KI_left it will then look for the file GlobalRes_eo_KI_left.properties before looking for the next resources class. If that file exists, an input stream is created for it and used to construct a PropertyResourceBundle that will read the properties from the file.

It is easier to use property files than to create subclasses of ListResourceBundle but the files have two limitations. First, they can only define string resources whereas ListResourceBundle can define arbitrary objects. Second, the only legal character encoding for property files is the byte format of ISO 8859-1. This means that other Unicode characters must be encoded with uxxxx escape sequences.

ListResourceBundle, PropertyResourceBundle, and .properties files will be sufficient for most of your bundles, but you can create your own subclass of ResourceBundle if they are not. You must implement two methods:

Exercise 24.1: Get GlobalHello to work with the example locales. Add some more locales, using ListResourceBundle, .properties files, and your own specific subclass of ResourceBundle.

Calendars mark the passage of time. Most of the world uses the same calendar, commonly called the Gregorian calendar after Pope Gregory XIII, under whose auspices it was first instituted. Many other calendars exist in the world, and the calendar abstractions are designed to express such variations. A given moment in time is expressed as a date according to a particular calendar, and the same moment can be expressed as different dates by different calendars. The calendar abstraction is couched in the following form:

Because the Gregorian calendar is commonly used, you also have the following concrete implementations of the abstractions:

For example, the following code creates a GregorianCalendar object representing midnight (00:00:00), October 26, 1972, in the local time zone, then prints its value:

Calendar cal =
    new GregorianCalendar(1972, Calendar.OCTOBER, 26);
System.out.println(cal.getTime());

The method getTime returns a Date object for the calendar object's time, which was set by converting a year, month, and date into a millisecond-measured long. The output would be something like this (depending on your local time zone of course):

Thu Oct 26 00:00:00 GMT+10:00 1972

You can also work directly with the millisecond time value by using getTimeInMillis and setTimeInMillis. These are equivalent to working with a Date object; for example, getTimeInMillis is equivalent to invoking getTime().getTime().

The abstract Calendar class provides a large set of constants that are useful in many calendars, such as Calendar.AM and Calendar.PM for calendars that use 12-hour clocks. Some constants are useful only for certain calendars, but no calendar class is required to use such constants. In particular, the month names in Calendar (such as Calendar.JUNE) are names for the various month numbers (such as 5—month numbers start at 0), with a special month UNDECIMBER for the thirteenth month that many calendars have. But no calendar is required to use these constants.

Each Calendar object represents a particular moment in time on that calendar. The Calendar class provides only constructors that create an object for the current time, either in the default locale and time zone or in specified ones.

Calendar objects represent a moment in time, but they are not responsible for displaying the date. That locale-sensitive procedure is the job of the DateFormat class, which will soon be described.

You can obtain a calendar object for a locale by invoking one of the static Calendar.getInstance methods. With no arguments, getInstance returns an object of the best available calendar type (currently only GregorianCalendar) for the default locale and time zone, set to the current time. The other overloads allow you to specify the locale, the time zone, or both. The static getAvailableLocales method returns an array of Locale objects for which calendars are installed on the system.

With a calendar object in hand, you can manipulate the date. The following example prints the next week of days for a given calendar object:

public static void oneWeek(PrintStream out, Calendar cal) {
    Calendar cur = (Calendar) cal.clone(); //modifiable copy
    int dow = cal.get(Calendar.DAY_OF_WEEK);
    do {
        out.println(cur.getTime());
        cur.add(Calendar.DAY_OF_WEEK, 1);
    } while (cur.get(Calendar.DAY_OF_WEEK) != dow);
}

First we make a copy of the calendar argument so that we can make changes without affecting the calendar we were passed.^[1] Instead of assuming that there are seven days in a week (who knows what kind of calendar we were given?), we loop, printing the time and adding one day to that time, until we have printed a week's worth of days. We detect whether a week has passed by looking for the next day whose “day of the week” is the same as that of the original object.

The Calendar class defines many kinds of calendar fields for calendar objects, such as DAY_OF_WEEK in the preceding code. These calendar fields are constants used in the methods that manipulate parts of the time:

An int is used to store values for all these calendar field types. You use these constants—or any others defined by a particular calendar class—to specify a calendar field to the following methods (always as the first argument):

The greatest minimum and least maximum describe cases in which a value can vary within the overall boundaries. For example, the least maximum value for DAY_OF_MONTH on the Gregorian calendar is 28 because February, the shortest month, can have as few as 28 days. The maximum value is 31 because no month has more than 31 days.

The set method allows you to specify a date by certain calendar fields and then calculate the time associated with that date. For example, you can calculate on which day of the week a particular date falls:

public static int dotw(int year, int month, int date) {
    Calendar cal = new GregorianCalendar();
    cal.set(Calendar.YEAR, year);
    cal.set(Calendar.MONTH, month);
    cal.set(Calendar.DATE, date);
    return cal.get(Calendar.DAY_OF_WEEK);
}

The method dotw calculates the day of the week on the Gregorian calendar for the given date. It creates a Gregorian calendar object, sets the date fields for year, month, and day, and returns the resulting day of the week.

The clear method can be used to reset a field's value to be unspecified. You can use clear with no parameters to clear all calendar fields. The isSet method returns true if a field currently has a value set.

Three variants of set change particular fields you commonly need to manipulate, leaving unspecified fields alone:

public void set(int year, int month, int date)
public void set(int year, int month, int date, int hrs, int min)
public void set(int year, int month, int date, int hrs, int min, int sec)

You can also use setTime to set the calendar's time from a Date object.

A calendar field that is out of range can be interpreted correctly. For example, January 32 can be equivalent to February 1. Whether it is treated as such or as an error depends on whether the calendar is considered to be lenient. A lenient calendar will do its best to interpret values as valid. A strict (non-lenient) calendar will not accept any values out of range, throwing IllegalArgumentException. The setLenient method takes a boolean that specifies whether parsing should be lenient; isLenient returns the current setting.

A week can start on any day, depending on the calendar. You can discover the first day of the week with the method getFirstDayOfWeek. In a Gregorian calendar for the United States this method would return SUNDAY, whereas Ireland uses MONDAY. You can change this by invoking setFirstDayOfWeek with a valid weekday index.

Some calendars require a minimum number of days in the first week of the year. The method getMinimalDaysInFirstWeek returns that number; the method setMinimalDaysInFirstWeek lets you change it. The minimum number of days in a week is important when you are trying to determine in which week a particular date falls—for example, in some calendars, if January 1 is a Friday it may be considered part of the last week of the preceding year.

You can compare two Calendar objects by using compareTo since Calendar implements Comparable. If you prefer, you can use the before and after methods to compare the objects.

TimeZone is an abstract class that encapsulates not only offset from GMT but also other offset issues, such as daylight saving time. As with other locale-sensitive classes, you can get the default TimeZone by invoking the static method getDefault. You can change the default time zone by passing setDefault a new TimeZone object to use—or null to reset to the original default time zone. Time zones are understood by particular calendar types, so you should ensure that the default calendar and time zone are compatible.

Each time zone has a string identifier that is interpreted by the time zone object and can be displayed to the user. These identifiers use a long form consisting of a major and minor regional name, separated by '/'. For example, the following are all valid time zone identifiers: America/New_York, Australia/Brisbane, Africa/Timbuktu. Many time zones have a short form identifier— often just a three letter acronym—some of which are recognized by TimeZone for backward compatibility. You should endeavor to always use the long form—after all, while many people know that EST stands for “Eastern Standard Time,” that doesn't tell you for which country. TimeZone also recognizes generic identifiers expressed as the difference in time from GMT. For example, GMT+10:00 and GMT-4:00 are both valid generic time zone identifiers. You can get an array of all the identifiers available on your system from the static method getAvailableIDs. If you want only those for a given offset from GMT, you can invoke getAvailableIDs with that offset. An offset might, for example, have identifiers for both daylight saving and standard time zones.

You can find the identifier of a given TimeZone object from getID, and you can set it with setID. Setting the identifier changes only the identifier on the time zone—it does not change the offset or other values. You can get the time zone for a given identifier by passing it to the static method getTimeZone.

A time zone can be converted into a displayable form by using one of the getDisplayName methods, similar to those of Locale. These methods allow you to specify whether to use the default locale or a specified one, and whether to use a short or long format. The string returned by the display methods is controlled by a DateFormat object (which you'll see a little later). These objects maintain their own tables of information on how to format different time zones. On a given system they may not maintain information for all the supported time zones, in which case the generic identifier form is used, such as in the example on page 696.

Each time zone has a raw offset from GMT, which can be either positive or negative. You can get or set the raw offset by using getRawOffset or set RawOffset, but you should rarely need to do this.

Daylight saving time supplements the raw offset with a seasonal time shift. The value of this shift can be obtained from getDSTSavings—the default implementation returns 3,600,000 (the number of milliseconds in an hour). You can ask whether a time zone ever uses daylight saving time during the year by invoking the method useDaylightTime, which returns a boolean. The method inDaylightTime returns true if the Date argument you pass would fall inside daylight saving time in the zone.

You can obtain the exact offset for a time zone on a given date by specifying that date in milliseconds or by using calendar fields to specify the year and month and so on.

The GregorianCalendar class is a concrete subclass of Calendar that reflects UTC (Coordinated Universal Time), although it cannot always do so exactly. Imprecise behavior is inherited from the time mechanisms of the underlying system.^[2] Parts of a date are specified in UTC standard units and ranges. Here are the ranges for GregorianCalendar:

The GregorianCalendar class supports several constructors:

In addition to the methods it inherits from Calendar, GregorianCalendar provides an isLeapYear method that returns true if the passed in year is a leap year in that calendar.

The Gregorian calendar was preceded by the Julian calendar in many places. In a GregorianCalendar object, the default date at which this change happened is midnight local time on October 15, 1582. This is when the first countries switched, but others changed later. The getGregorianChange method returns the time the calendar is currently using for the change as a Date. You can set a calendar's change-over time by using setGregorianChange with a Date object.

The SimpleTimeZone class is a concrete subclass of TimeZone that expresses values for Gregorian calendars. It does not handle historical complexities, but instead projects current practices onto all times. For historical dates that precede the use of daylight saving time, for example, you will want to use a calendar with a time zone you have selected that ignores daylight saving time. For future dates, SimpleTimeZone is probably as good a guess as any.

The java.util.Formatter class, described in Chapter 22, also supports the formatting of date and time information using a supplied Date or Calendar object, or a date represented as a long (or Long). Using the available format conversions you can extract information about that date/time, including things like the day of the month, the day of the week, the year, the hour of the day, and so forth.

The output of the formatter is localized according to the locale associated with that formatter, so things like the name of the day and month will be in the correct language—however, digits themselves are not localized. Unlike DateFormat, a formatter cannot help you with localization issues such as knowing whether the month or the day should come first in a date—it simply provides access to each individual component and your program must combine them in the right way.

A date/time conversion is indicated by a format conversion of t (or T for uppercase output), followed by various suffixes that indicate what is to be output and in what form. The following table lists the conversion suffixes related to times:

So, for example, the following code will print out the current time in the familiar hh:mm:ss format:

System.out.printf("%1$tH:%1$tM:%1$tS %n", new Date());

The conversion suffixes that deal with dates are

Naturally, the valid range for day of month, month of year, and so forth, depends on the calendar that is being used. To continue the example, the following code will print the current date in the common mm/dd/yy format:

System.out.printf("%1$tm/%1$td/%1$ty %n", new Date());

As you can see, all the information about a date or time can be extracted and you can combine the pieces in whatever way you need. Doing so, however, is rather tedious both for the writer and any subsequent readers of the code. To ease the tedium a third set of conversion suffixes provides convenient shorthands for common combinations of the other conversions:

So the previous examples could be combined in the more compact and somewhat more readable

System.out.printf("%1$tT %1$tD %n", new Date());

As with all format conversions a width can be specified before the conversion indicator, to specify the minimum number of characters to output. If the converted value is smaller than the width then the output is padded with spaces. The only format flag that can be specified with the date/time conversions is the '–' flag for left-justification—if this flag is given then a width must be supplied as well.

Comparing strings in a locale-sensitive fashion is called collation. The central class for collation is Collator, which provides a compare method that takes two strings and returns an int less than, equal to, or greater than zero as the first string is less than, equal to, or greater than the second.

As with most locale-sensitive classes, you get the best available Collator object for a locale from a getInstance method, either passing a specific Locale object or specifying no locale and so using the default locale. For example, you get the best available collator to sort a set of Russian-language strings like this:

Locale russian = new Locale("ru", "");
Collator coll = Collator.getInstance(russian);

You then can use coll.compare to determine the order of strings. A Collator object takes locality—not Unicode equivalence—into account when comparing. For example, in a French-speaking locale, the characters ç and c are considered equivalent for sorting purposes. A naïve sort that used String.compare would put all strings starting with ç after all those starting with c (indeed, it would put them after z), but in a French locale this would be wrong. They should be sorted according to the characters that follow the initial c or ç characters in the strings.

Determining collation factors for a string can be expensive. A CollationKey object examines a string once, so you can compare precomputed keys instead of comparing strings with a Collator. The method Collator.getCollationKey returns a key for a string. For example, because Collator implements the interface Comparator, you could use a Collator to maintain a sorted set of strings:

class CollatorSorting {
    private TreeSet<String> sortedStrings;

    CollatorSorting(Collator collator) {

        sortedStrings = new TreeSet<String>(collator);
    }

    void add(String str) {
        sortedStrings.add(str);
    }

    Iterator<String> strings() {
        return sortedStrings.iterator();
    }
}

Each time a new string is inserted in sortedStrings, the Collator is used as a Comparator, with its compare method invoked on various elements of the set until the TreeSet finds the proper place to insert the string. This results in several comparisons. You can make this quicker at the cost of space by creating a TreeMap that uses a CollationKey to map to the original string. CollationKey implements the interface Comparable with a compareTo method that can be much more efficient than using Collator.compare.

class CollationKeySorting {
    private TreeMap<CollationKey, String> sortedStrings;
    private Collator collator;

    CollationKeySorting(Collator collator) {
        this.collator = collator;
        sortedStrings = new TreeMap<CollationKey, String>();
    }

    void add(String str) {
        sortedStrings.put(
            collator.getCollationKey(str), str);
    }

    Iterator<String> strings() {
        return sortedStrings.values().iterator();
    }
}

The abstract Format class provides methods to format and parse objects according to a locale. Format declares a format method that takes an object and returns a formatted String, throwing IllegalArgumentException if the object is not of a type known to the formatting object. Format also declares a parseObject method that takes a String and returns an object initialized from the parsed data, throwing ParseException if the string is not understood. Each of these methods is implemented as appropriate for the particular kind of formatting. The package java.text provides three Format subclasses:

NumberFormat in turn has four different kinds of “get instance” methods. Each method uses either a provided Locale object or the default locale.

Here is a method you can use to print a number using the format for several different locales:

public void reformat(double num, String[] locales) {
    for (String loc : locales) {
        Locale pl = parseLocale(loc);
        NumberFormat fmt = NumberFormat.getInstance(pl);
        System.out.print(fmt.format(num));
        System.out.println("	" + pl.getDisplayName());
    }
}

public static Locale parseLocale(String desc) {
    StringTokenizer st = new StringTokenizer(desc, "_");
    String lang = "", ctry = "", var = "";
    try {
        lang = st.nextToken();
        ctry = st.nextToken();
        var = st.nextToken();
    } catch (java.util.NoSuchElementException e) {
        ; // fine, let the others default
    }
    return new Locale(lang, ctry, var);
}

The first argument to reformat is the number to format; the other arguments specify locales. We use a StringTokenizer to break locale argument strings into constituent components. For example, cy_GB will be broken into the language cy (Welsh), the country GB (United Kingdom), and the empty variant "". We create a Locale object from each result, get a number formatter for that locale, and then print the formatted number and the locale. When run with the number 5372.97 and the locale arguments en_US, lv, it_CH, and lt, reformat prints:

5,372.97        English (United States)
5 372,97        Latvian
5'372.97        Italian (Switzerland)
5.372,97        Lithuanian

A similar method can be written that takes a locale and a number formatted in that locale, uses the parse method to get a Number object, and prints the resulting value formatted according to a list of other locales:

public void parseAndReformat(String locale, String number,
                             String[] locales)
    throws ParseException
{
    Locale loc = LocalNumber.parseLocale(locale);
    NumberFormat parser = NumberFormat.getInstance(loc);
    Number num = parser.parse(number);
    for (String str : locales) {
        Locale pl = LocalNumber.parseLocale(str);
        NumberFormat fmt = NumberFormat.getInstance(pl);
        System.out.println(fmt.format(num));
    }
}

When run with the original locale it_CH, the number string "5'372.97" and the locale arguments en_US, lv, and lt, parseAndReformat prints:

5,372.97
5 372,97
5.372,97

Parsing requires finding boundaries in text. The class BreakIterator provides a locale-sensitive tool for locating such break points. It has four kinds of “get instance” methods that return specific types of BreakIterator objects:

The following code prints each break shown by a given BreakIterator:

static void showBreaks(BreakIterator breaks, String str) {
    breaks.setText(str);
    int start = breaks.first();
    int end = breaks.next();
    while (end != BreakIterator.DONE) {
        System.out.println(str.substring(start, end));
        start = end;
        end = breaks.next();
    }
    System.out.println(str.substring(start)); // the last
}

A BreakIterator is a different style of iterator from the usual java.util.Iterator objects you have seen. It provides several methods for iterating forward and backward within a string, looking for different break positions.

You should always use these boundary classes when breaking up text because the issues involved are subtle and widely varying. For example, the logical characters used in these classes are not necessarily equivalent to a single char. Unicode characters can be combined, so it can take more than one 16-bit Unicode value to constitute a logical character. And word breaks are not necessarily spaces—some languages do not even use spaces.