Deviation Options for the Hijrah Calendar #95

dchiba opened this Issue Sep 22, 2012 · 20 comments


None yet
3 participants

dchiba commented Sep 22, 2012

The Islamic calendar has different forms with minor but significant variance in the way dates are identified. The requirement is to accommodate the adjustments needed to create the exactly desired form of the calendar.

Please document the mechanism to load the deviation data from the configuration file.

It might be desirable to specify deviation at runtime. For instance:

HijrahChronology withDeviation(Deviation deviation)
creates a HijrahChronology with deviation

This allows the application to dynamically use a new desired deviation.

Other approaches may be possible. We need to determine the desirability and the specifics.


jodastephen commented Sep 22, 2012

My understanding is that the plugin required is solely a question of "is year n a leap year or not". This should be plugged in similar to the proposal above.

dchiba commented Sep 28, 2012

The Hijrah chronology author Ryoji points out that dynamically plugging in can help ease the system administration task to maintain the deviation definitions. It would eliminate the need to update the configuration file for JRE.

This may have a revision issue similar to tzdata updates'. Hijrah deviation updates would be less frequently needed than timezone definitions.


jodastephen commented Oct 5, 2012

Agreed to make this not configurable at runtime. Remaining issue is integration/coding issue.

dchiba commented Nov 7, 2012

We reviewed the current implementation and consulted Ryoji and other experts for the desired configuration file format. Evaluated 3 proposed formats and today we just settled with the options. Here is a sample entry:

  <deviation start-date="2012-05-21" days="-1"/>
  <!-- repeat as needed -->

This means on the Gregorian date May 21, 2012, a day is removed (-1) or added (if +1) from the Hijrah calendar. From this date onwards, the Hijrah dates are shifted forward or backward by the number of days (usually 1).

Also we said a mechanism similar to TZUpdater is desirable, but for now it is beyond what is planned for JDK8.

We are going to take a closer look to verify feasibility with this option.


jodastephen commented Nov 13, 2012

Is XML a standard JDK thing? This format would be shorter:

2012-05-21 -1
2012-05-22 +1

RogerRiggs commented Nov 13, 2012

XML would only be consumed by the conversion tool. A compact serialized form would be preferred. It remains to see if we have time in this release to handle a full two step conversion. Defining the deviations in terms of deltas to ISO/Gregorian dates will be much easier to maintain than the current Hijrah format.

dchiba commented Nov 13, 2012

I agree the plain text form seems preferred for the usage scenarios planned for JDK8. The exercise to define the configuration file format had focus on the logical content, not the physical format. Whether it is XML or plain text based was beyond the scope, although we did say XML might be easier to exchange the data for the possible future scenarios. I think only the text format should be implemented for the time being.


RogerRiggs commented Nov 17, 2012

Is there any merit in making the deviation mechanism be implemented as a ServiceProvider so it can be re-implemented to get the data from another source. It would still require an initial implementation that reads from a file but the file source reading would not be hardwired.


jodastephen commented Nov 18, 2012

A service loader sounds good to me,

dchiba commented Nov 19, 2012

The default service provider could look for a predefined file source. An extended provider could load the data from an alternate location.
A couple of points to clarify:
(1) Where should be the default location? (how about jre/lib/
(2) JDK8 only supports the default provider for the predefined file source, correct?
(3) The data is loaded while the VM initializes; once VM is up, could the data get updated? (no on JDK8)

dchiba commented Dec 6, 2012

We are noticing some variants are purely rule based and no configuration is required, except for the possibilities to use various epoch dates; they just needed to be unambiguously identified.

Also, the decision to use "islamicc" for the formal CLDR calendar name lacked consideration. "islamic" is for the sighting based variants and we do mean to support them. Now, the issue is we seem to be unable to identify the variants unambiguously.

dchiba commented Dec 13, 2012

A related update in #118


RogerRiggs commented Dec 20, 2012

The different Hijrah calendars need to be come from different HijrahChrono instances.
HijrahChrono and HijrahDate need to be refactored so that each HijrahDate refers to a specific HijrahChrono instance. This will allow them to be treated as separate calendars.

@ghost ghost assigned RogerRiggs Dec 23, 2012


RogerRiggs commented Dec 23, 2012

Please review and comment on:

The changes include refactoring the support for the deviations into the Chrono class
from the HijrahDate class. The change includes changing HijrahDate so that it refers
explicitly to an instance of HijrahChrono. Changes to HijrahChrono include multiple
instances with different Ids and calendarTypes that encapsulate the different deviations.
Each acts as a different calendar. The serialized form of HijrahDate includes the reference
to the HijrahChrono instance (already serialized as represented by the id).

The format of the deviation file is modified to use ISO dates which are converted to
HijrahDates using the default Islamic calendar. The offsets modify the length of the
HijrahMonths for the alternate calendar.

The configuration mechanism for the deviation options is not final. System properties
identify the additional Hijrah calendars; and the default location of the deviation files
which are named according to the calendar id.
The additional calendars are created when the standard Hijrah calendar is initialized.

These changes also exposed a flaw in the registration mechanism used for Chrono.of(id);
the registration was being done before the constructor of the Chrono was complete
allowing incompletely constructed Chronos to be visible to other threads.
A separate registerChrono method was added that is the last thing called in
the subclasses constructor.

There may be a better initialization sequence but it cannot involve recursion between
the static initializers and the constructors.

dchiba commented Dec 26, 2012

The changes to support multiple HijrahChrono instances look good to me. We will write some tests to verify the mechanism is functioning properly.

I think the deviation file format should be refined to fit to the variants being configured. For example, Umm Al-Qura has no deviation so there should be no configuration elements other than identifying itself as Umm Al-Qura. On the other hand, the sighting based variants must configure the deviations. Ideally, they should be specified with the absolute length of the Islamic month being configured, so no "default Islamic calendar" is needed (Doubtful if this makes sense for the users. Also, using a complex algorithm to define the default calendar is a wasteful effort, considering the presence of much simpler variants.). For the other possible future variants such as Kwaiti, they need to identify which of the tabular forms they are, as well as their epoch date.

To help address this point we are collecting the calendar data for specific variants.


jodastephen commented Dec 27, 2012

I won't be checking the details of the calendar system impelementation. I do note the following:

  • the Javadoc on the HijrahDate class is not part of the spec, so any description of configuration is not part of the spec, which may or may not be deliberate.
  • the registration mechanism may still not be thread-safe. There is no guarantee of no-reordering within the subclass constructor AFAIK
    More broadly, the question is how much of this to specify, restricting change in future JDKs.

Overall though, I'm happy to see this added to hg.


RogerRiggs commented Dec 28, 2012

Correct, the configuration mechanism and details are not part of the spec. They are necessary and controlled by the Oracle change process that maintains compatibility between implementation releases.


RogerRiggs commented Dec 28, 2012

The various Islamic calendars do need to be identified and specified any detailed recommendations are welcomed.
The changes so far only handle the same case as the original deviation mechanism. Absolute month lengths would be preferable, easier to understand, and require fewer entries. The current mechanism almost always pairs extending a month by shortening the next month. In the case of absolute months, it may make more sense to go back to Hijrah year numbering instead of using ISO dates as the indices.


RogerRiggs commented Dec 28, 2012

With respect to initialization, it should be considered doing the initialization more lazily, perhaps during the calls to the methods that do lookup. An init() method could be written that does the service loader processing only on the first lookup "miss" and then attempts to (re-)register the built-in calendars. The registration would outside the scope of the constructor ensuring that the chrono is completely constructed before use. There may be a best practice in the JDK for initialization the can be used as a template.


RogerRiggs commented Feb 21, 2013

Replaced Hijrah implementation by a table driven mechanism configurable via lib/
Resolved with

@RogerRiggs RogerRiggs closed this Feb 21, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment