Description Tomer Mahlin 2008-11-17 10:52:13 EST

Background
------------

 On several platforms OS allows end user configure the way dates are formatted. In the context of this defect we review exclusively String representation of dates  (any graphical context such as various date pickers are out of the scope of this discussion). As part of date format configuration user is able to configure calendar preference (see some illustrations for Windows and Mac OS below). 

The problem
------------

  Via ICU4J Eclipse has support for a considerable amount of calendars (12 calendar types). However, right now this support can't be invoked by Eclipse user through any external configuration (i.e. Eclipse command line parameter, OS level configuration). Even those components in Eclipse which do use ICU4J for dates formatting (i.e. PropertiesDialog & Properties view using com.ibm.icu.text.DateFormat.getDateTimeInstance(int, int) for formatting the Last Modified Time property), don't pass calendar information into appropriate date formatting function. This happens for a very simple reason, this information is not available to those components, since user does not have any mechanism to pass this information to Eclipse / ICU4J. As a result in the overwhelming majority of cases only Gregorian calendar is used for date formatting. This is in a sharp contrast to user's experience with other system (OS level) applications which take into account user's calendar preference.
 
The analysis
-------------

 It is possible to retrieve user's calendar preference from OS level using native code. This information can be leveraged by Eclipse components using ICU4J for dates formatting in order to support a great repertoire of calendars. 

Which platforms support user's calendar preference specification ?
-----------------------------------------------------------------
  To the best of my knowledge at least following platforms have support for user calendar preference configuration: OS_WIN32 (13 calendar types) and OS_MACOSX (7 calendar types).

How information about user's calendar preference can be retrieved on OS_WIN32 ?
------------------------------------------------------------------------------
 On this OS user's calendar preference is available via Windows Calendar Identifiers (http://msdn.microsoft.com/en-us/library/ms776338(VS.85).aspx)

1	CAL_GREGORIAN	  			Gregorian (localized)
2	CAL_GREGORIAN_US  			Gregorian (English strings always)
3	CAL_JAPAN	  			Japanese Emperor Era
4	CAL_TAIWAN	  			Taiwan Calendar
5	CAL_KOREA	  			Korean Tangun Era
6	CAL_HIJRI	  			Hijri (Arabic Lunar)
7	CAL_THAI	                        Thai
8	CAL_HEBREW	                        Hebrew (Lunar)
9	CAL_GREGORIAN_ME_FRENCH	                Gregorian Middle East French
10	CAL_GREGORIAN_ARABIC	                Gregorian Arabic
11	CAL_GREGORIAN_XLIT_ENGLISH	        Gregorian transliterated English
12	CAL_GREGORIAN_XLIT_FRENCH	        Gregorian transliterated French
23	CAL_UMALQURA	Windows Vista or later: Um Al Qura (Arabic lunar) calendar

 It can be retrieved using a code similar to the following one:
    LCID = GetSystemDefaultLCID()
    GetUserLocaleInfo(LCID, LOCALE_ICALENDARTYPE)

How information about user's calendar preference can be retrieved on OS_MACOSX ?
------------------------------------------------------------------------------
 On this OS user's calendar preference is available via MAC OS Locale Calendar Identifiers (http://developer.apple.com/documentation/CoreFoundation/Reference/CFLocaleRef/Reference/reference.html#//apple_ref/doc/c_ref/kCFLocaleCalendar)

const CFStringRef kCFGregorianCalendar;
const CFStringRef kCFBuddhistCalendar;
const CFStringRef kCFChineseCalendar;
const CFStringRef kCFHebrewCalendar;
const CFStringRef kCFIslamicCalendar;
const CFStringRef kCFIslamicCivilCalendar;
const CFStringRef kCFJapaneseCalendar;

  It can be retrieved using a code similar to the following one:
       userLocaleRef = CFLocaleCopyCurrent();
       CFLocaleGetValue(userLocaleRef,kCFLocaleCalendarIdentifier)

How calendar information is represented in ICU4J ?
---------------------------------------------------
  In ICU4J calendar information is represented via ICU4J calendar tag values (com.ibm.icu.util.Calendar.java - http://icu-project.org/apiref/icu4j/com/ibm/icu/util/Calendar.html)
   
    private static final int BUDDHIST = 0;
    private static final int CHINESE = 1;
    private static final int COPTIC = 2;
    private static final int ETHIOPIC = 3;
    private static final int GREGORIAN = 4;
    private static final int HEBREW = 5;
    private static final int INDIAN = 6;
    private static final int ISLAMIC = 7;
    private static final int ISLAMIC_CIVIL = 8;
    private static final int JAPANESE = 9;
    private static final int TAIWAN = 10;
    private static final int ETHIOPIC_AMETE_ALEM = 11;

    private static final String[] calTypes = {
        "buddhist", 
	"chinese", 
	"coptic", 
	"ethiopic", 
	"gregorian", 
	"hebrew", 
        "indian", 
	"islamic", 
	"islamic-civil", 
	"japanese", 
	"roc", 
	"ethiopic-amete-alem"
    };

How to map between OS_MACOSX and ICU4J calendar specification ?
---------------------------------------------------------------
  In this case the mapping is straightforward:

kCFGregorianCalendar --> "gregorian"
kCFBuddhistCalendar --> "buddhist"
kCFChineseCalendar --> "chinese"
kCFHebrewCalendar --> "hebrew"
kCFIslamicCalendar --> "islamic"
kCFIslamicCivilCalendar --> "islamic-civil"
kCFJapaneseCalendar --> "japanese"

How to map between OS_WIN32 and ICU4J calendar specification ?
---------------------------------------------------------------
  In this case the mapping is less trivial. The suggested one is as follows:

CAL_GREGORIAN - Gregorian (localized) --> "gregorian"
CAL_GREGORIAN_US - Gregorian (English strings always) --> "gregorian"
CAL_JAPAN - Japanese Emperor Era --> "japanese"
CAL_TAIWAN - Taiwan Calendar --> "roc"
CAL_KOREA - Korean Tangun Era --> ? ( "gregorian" )
CAL_HIJRI - Hijri (Arabic Lunar) --> "islamic"
CAL_THAI - Thai --> ? ("buddhist", "gregorian")
CAL_HEBREW - Hebrew (Lunar) --> "hebrew"
CAL_GREGORIAN_ME_FRENCH - Gregorian Middle East French -->
CAL_GREGORIAN_ARABIC - Gregorian Arabic --> ? ("islamic-civil", "gregorian")
CAL_GREGORIAN_XLIT_ENGLISH - Gregorian transliterated English --> ? ( "gregorian" )
CAL_GREGORIAN_XLIT_FRENCH - Gregorian transliterated French --> ? ( "gregorian" )
CAL_UMALQURA - Windows Vista or later: Um Al Qura (Arabic lunar) calendar --> ? ( "gregorian" )