Saint Louis University |
Computer Science 290
|
Dept. of Math & Computer Science |
Topic: Calendar
Related Reading: Ch. 3 of text
Due:
Thursday, 25 September 2008, 11:59pm
Tuesday, 30 September 2008, 11:59pm
The goal of this assignment is to provide experience in using libraries that provide internationalization for dates and calendars.
For this assignment, you must work individually.
Please make sure you adhere to the policies on academic integrity in this regard.
The most commonly used is the Gregorian calendar (e.g. January, February, March, ...). As an example, here is how October 2008 of the Gregorian calendar is typically displayed in the United States:
October 2008
Sun Mon Tue Wed Thu Fri Sat
1 2 3 4
5 6 7 8 9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30 31
However, other calendars are used in some cultures, such as the Islamic Calendar, Hebrew Calendar, Chinese Calendar, and so on. For example, here is a typical month of the Hebrew Calendar (as it would be displayed in the United States).
Heshvan 5769
Sun Mon Tue Wed Thu Fri Sat
1 2 3
4 5 6 7 8 9 10
11 12 13 14 15 16 17
18 19 20 21 22 23 24
25 26 27 28 29
Here is a typical month of the Islamic calendar (as it would be displayed in
the United States)
Shawwal 1429
Sun Mon Tue Wed Thu Fri Sat
1 2 3
4 5 6 7 8 9 10
11 12 13 14 15 16 17
18 19 20 21 22 23 24
25 26 27 28 29
Note: in the case of the Islamic calendar, there are two different
sets of conventions.
The traditional religious calendar has lunar months whose
beginings depend upon local sightings of the new moon. Because those
sightings are less predictable and change from location to location, there
is also an Islamic civil calendar based
upon a predictable pattern for the month beginnings. The example of
Shawwal above is actually the civic version of that month.
A separate factor when displaying a calendar is the locale for which the calendar is to be viewed. For example, the Gregorian calendar as displayed in the United States is different than the Gregorian calendar as it might be displayed in France, or Spain, or Israel.
The issues are twofold. First, the names of the months and days of the week typically differ across languages. Secondly, different countries have different conventions for what is considered the first day of the week when displaying a calendar. For example, in the United States a week is displayed with Sunday being the first day of the week, yet in much of Europe Monday is displayed in the leftmost column as the first day of the week, with that week ending on Sunday.
As an example, here is a typical display of October 2008 in Spain:
octubre 2008
lun mar mié jue vie sáb dom
1 2 3 4 5
6 7 8 9 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 29 30 31
Here is an example of the same month, as displayed in Somalia; notice that the first day of the displayed week is Saturday.
Bisha Tobnaad 2008
Sab Axa Isn Sal Arb Kha Jim
1 2 3
4 5 6 7 8 9 10
11 12 13 14 15 16 17
18 19 20 21 22 23 24
25 26 27 28 29 30 31
It should be possible to combine any of the calendar choices with any of the local conventions for a particular locale. As further examples, the following display a Hebrew month and an Islamic (civil) month, as it might appear in France:
Hesvan 5769
lun. mar. mer. jeu. ven. sam. dim.
1 2 3 4
5 6 7 8 9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29
Chaououal 1429
lun. mar. mer. jeu. ven. sam. dim.
1 2 3 4
5 6 7 8 9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29
The standard Java libraries contains some support for calendars and internationalization. Most notably, they provide an abstract class java.util.Calendar that gives a more general structure for a world calendar, when specialized for display in a specific locale. This class provides support for the rules for advancing from day to day and month to month in a calendar. It also provides methods such as getFirstDayOfWeek() to determine which weekday is considered the first. It also provides accessors to determine variables such as how many days are in a given month, or how many months are in a given year.
Java also provides the java.util.Locale object to identify and encapsulate conventions of a particular world locale. The classes java.text.DateFormat and java.text.DateFormatSymbols can be used to generate appropriate strings for displaying dates, or getting full or abbreviated names for months in the year and days in the week.
However, Java's support for calendars is limited. Although the abstract Calendar class is designed to handle a more general view of calendars, the only underlying implementation that they provide is the GregorianCalendar. This means that it is possible to typeset the Gregorian calendar in a variety of world locales, there is not support for other calendars such as the Hebrew, Islamic, Japanese, or Chinese calendars.
To provide greater support for this assignment,
we will rely upon an outside library known as the
The ICU is an open-source project supported by IBM in an effort to provide greater internationalization for global software. It is available for C/C++ and Java. We will be using the Java API named ICU4J.
Access to the library: We have installed the icu4j library for local use at turing:/usr/share/java/icu4j.jar. If you would like to work on this project on some other system (other than remote access to turing), you will need to copy that file on your local system.
Using with Eclipse:
After creating a new project, you will need to add icu4j to the path
for your project. Select the project from the Package Explorer and
then select Properties from the File menu (or from the pop-up menu
when clicking the mouse). Goto the
Using directly with JDK: When compiling your project, you will need to add the library to the classpath, using the command
javac -cp .:/usr/share/java/icu4j.jar YourProgram.javaYou will also need to adjust the classpath when executing your program, as follows:
java -cp .:/usr/share/java/icu4j.jar YourProgram
Documentation: the ICU4J API will be a necessary reference for this assignment.
Overview of Relevant Components: The ICU libraries are modeled very closely after corresponding components in the standard Java libraries, but the ICU classes are not formally extensions of Java's classes. The most important classes for this assignment include:
com.ibm.icu.util.ULocale
This serves a similar purpose to the java.util.Locale
class, but is renamed ULocale to emphasize its
difference. A new instance can be constructed based upon a
String serving as a local ID. As examples,
en_US designates English language in the United States,
whereas en_UK is English Language in the United
Kingdom. A choice of underlying calendar can be specified using
a syntax such as en_US@calendar=hebrew to designate use
of the Hebrew calendar (for English language speakers in the
United States). Please note that for the Islamic calendar a tag
of @calendar=islammic is used to represent the Islamic
religious calendar; the tag
@calendar=islamic-civil produes the Islamic civil calendar.
A list of all available language/country locales on the system can be queried with the static function ULocale.getAvailableLocales(), and each returned ULocale provides accessors for its common name as well as its underlying base code (e.g., en_US).
com.ibm.icu.util.Calendar
The ICU Calendar class uses a very similar interface as
that of java.util.Calendar. It provides an interface
for manipulating arbitrary calendars. An informative
introduction to the class is provided in the
formal
API documentation.
The true logic for specific calendars are provided by subclasses such as GregorianCalendar, HebrewCalendar, IslamicCalendar, etc. However, there is no need to directly instantiate those subclasses; a new calendar of the appropriate underlying type can be created using the factory function, Calendar.getInstance(Locale).
You should avoid unnecessary assumptions about the format of a calendar. What is safe to presume is that all calendars have aspects of years, months, weeks, and days. However there are many differences as to the number of months in a year, number of days in a month, and so forth. In some calendars, those quantities may even change from year to year (such as the extra day added to Februrary on leap years in the Gregorian calendar, or an extra month added to the Hebrew calendar in certain years). Once you have a specific calendar instance, you can query the relevant quantities for a field using methods such as getMaximum (for the overall maximum under any circumstance) and getActualMaximum (the maximum for the particular setting).
com.ibm.icu.util.DateFormat
com.ibm.icu.util.DateFormatSymbols
These classes are similar in purpose to those found in the
standard java.text library. A DateFormat
instance can be used to produce a string to express a specific
date or date/time combination in the proper language and
alphabet for a specific locale. The DateFormatSymbols
can provide additional language-specific information such as the
names of the months or the names of the days of the week (either
in full or abbreviated fashion).
You should write a program that offers the user a choice of locale, a choice of calendar, and a choice of year, and then produces an appropriate representation of the given year (see Sample Output section below).
For the choice of locales, you should offer a menu of all available locales on the system. As an example, on turing the list of available locales begins as
Afrikaans Afrikaans (South Africa) Amharic Amharic (Ethiopia) Arabic ...We suggest numbering each of these and allowing the user to select a locale by indicating the associated number.
For the choice of calendar, you should explicitly offer the choice of either Gregorian, Hebrew, or Islamic (civil).
We have prepared samples of six different calendars, each displayed in three different locales. The six years employed are:
Each of these calendars is displayed in the following three locales:
Your assignment should be submitted electronically (details on the submission process).
Source Code
Please submit a single file containing your source code.
Readme File
Submit a separate text file named "readme" that provides a brief
overview of your program an any interesting design decisions that
you made. You may include any other discussion that you feel
will be helpful when grading your assignment, for example, if there
are known bugs or problems with your program.
In the main part of the assignment, we demonstrated calendars as shown in several different locales. But we intentionally avoided languages that are read right-to-left (e.g, Hebrew, Arabic). Ideally, a good internationalized package should support those locales gracefully. That is true of ICU, but it takes additional care.
Let's begin by looking at what might go wrong for example when using the Israel locale. The conventional first day of a week in Israel is Sunday and is represented using the character aleph (א). That is followed by Monday (ב), and so on, leading to column labels:
א ב ג ד ה ו שChance are, if your original program were to use the Israel locale, you would find these labels displayed appropriately. The Hebrew column labels are correctly reported by DateFormatSymbol, and when your print them starting with ב, that line is automatically displayed from right-to-left because such an ordering is encoded as part of the Unicode characters.
The problem is that other lines of the calendar would be displayed from left-to-right using standard numerals. For example, an errant view of the Gregorian October 2008 might appear as:
אוקטובר 2008 א ב ג ד ה ו ש
1 2 3 4
5 6 7 8 9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30 31
Notice that the column headers were displayed from right-to-left with
the rightmost column labeled aleph (א) representing Sunday on this calendar. Yet the first
Sunday in October 2008 is the 5th. If the dates were properly
arranged in columns, the calendar would be typeset as
אוקטובר 2008 א ב ג ד ה ו ש
4 3 2 1 11 10 9 8 7 6 5 18 17 16 15 14 13 12 25 24 23 22 21 20 19 31 30 29 28 27 26
Your Challenge: Update your original program so that it produces a calendar with dates arranged right-to-left for appropriate locales, while still working properly for left-to-right locales.
By the way, we are not sure how to accomplish this in a clean, transparent way. Hence, its extra credit!