Although I would tend to think that it is not realistic to accommodate all of the calendaring systems of humanity in a single API that is both not inadequately lowest common denominator (or alternatively overly complicated to cover cases where most users of the API don’t even understand why the complexity exists) and missing gaps due to the designers lack of knowledge of all of the variations, I hope to at least help the discussion by informing about the alternative calendar system that I know something about, the Hebrew calendar. And it is of modern relevance because national holidays in Israel are dictated by it.


The Hebrew calendar breaks at least three assumptions that would be typically made about a calendaring system.


One is that there is a consistent number of months in every year. In the Hebrew calendar most years are twelve months, some are 13. So just like in an ISO calendar you would never think to ask the days in the month of February without knowing which year the request is made about, you would never ask in a Hebrew calendar for the months of the year without passing the year as a parameter to the request.


The second is that the first month of the year has a value of 1. In the Hebrew calendar the cardinal and ordinal list of months is different (the first month of the year is the 7th month).


The third assumption is that a given month in one year is fully valid in another year. Although you have that concept with February 29th in the ISO calendar on days, this is true of both days and months in the Hebrew calendar. This goes both ways, in that Adar (the month which is doubled in a leap year) is the 12th month ordinally (5th cardinally) becomes the 13th month of a leap year and the 12th and 13th month are both represented in the 12th month of a non-leap year. (And from a presentation perspective “Adar” standing alone is only valid in a non-leap year. In a leap year it is Adar I and Adar II).


So given all of this, I would question the usefulness of accommodating “every” calendar for date pickers and other such use cases. Of course, I do think that just sticking with ISO is too limiting.


From: Roger Riggs []
Sent: Saturday, February 18, 2012 10:04 AM
Subject: Re: [threeten-develop] Non-Gregorian and Gregorian Calendar APIs


On 2/17/12 8:26 PM, Richard Warburton wrote:

This seems like a fairly fundamental change in terms of API design.  A
few comments/questions:
In case it wasn't obvious, LocalDate remains as is. This only affects
you if you need to work with other calendar systems.
I was somewhat confused over this point.  In Roger's original email he
seems to request support for writing code that will work with both
LocalDate and other calendar systems.  So surely a move to pluggable
chronologies doesn't address the exact same set of requirements?

yes, it is necessary to be able to write calendar neutral code. The use case
of writing a date picker and being able to switch between calenders is essential
and it muse be able to switch from Gregorian to non-Gregorian without
using different code and without hardcoded per-calendar types. The use case
is not just a date-picker, but any application that will work in multiple locales
and has to interface between dates in databases and their data model
and a user in their current locale.  Or if being used in a server,
formatting and output for a client's locale.

This is not just an edge case that only a few developers will encounter.
If this isn't simple enough, developers will be happy continue with Java.util.Date
and java.util.Calendar and their current hacks since they are familiar.

Using Calendrical is a tool for converting to different date-time types,
but the naming and design take a bit to understand.

I'm also concerned that between the ISO, non-Gregorian, and
the low level API there are now three different APIs for dates and times.

The design that uses ChronologyDate takes a very indirect approach to
the calendars.  That approach needs some cleanup before it can
be judged properly. Its hard to know where to start with that API.

You might think you could start with the Chronologies, but they don't
have any static or other "of" methods and are not the starting point.  The name ChronologyDate
isn't very inviting and then it seems you have to find a Chronology instance to get

By comparison, the APIs in the i18N package for HijrahDate, JapaneseDate, ThaiBuddistDate, etc.
are easy to recognize and have APIs very similar to LocalDate with a plethora
of get, plus, minus, with, and, of methods.  From the neutral API perspective
what's missing is a common interface for Dates so neutral code can
do the basics without having to know the type of calendar.

I believe that the chronology will need to hold some state, but I
don't think that affects possible generification. The chronology
doesn't hold date-specific state. Chronologies would be immutable. I
doubt there will be a default.
Thanks for clarifying.
2. I much prefer the month representation being an enum, both for type
safety and readability reasons.  It seems like you could still have
this within a Pluggable Chronology based system, if you take a generic
parameter for the Month representation.  It might make writing
chronologies a bit harder, but surely better to have the complexity
there than for the 'joe java developer' whose life is made easier by
having a methods take/return MonthOfYear.January instead of 1.
The question is whether it needs to be an enum for other calendar
systems. For LocalDate, MonthOfYear stays, but do we really want to
have a month enum for every supported calendar system?
To me the answer to that question depends on how varied the different
month systems are.  I was under the impression that most Calendaring
systems use twelve months - certainly from the examples you've listed
the Japanse, Thai, Hiraj (Islamic) systems all use twelve months.  In
that case I'd simply use the same MonthOfYear to represent the month
in these cases, and use a seperate 13 month enum for the
Ethiopian/Historical Coptic Calendars.  Conversion from say "January"
to "Muḥarram" in Islamic then becomes an internalization problem.  I
mean its not ideal, but assuming English language readability is a
primary concern here it does make sense.
I don't know how 'wrong' this would feel to someone who isn't an
English Language native, but since we'd be using English language
names for even the Gregorian Calendar months, January rather than
Janvier, it seems like a similar case.
Of course I'm not opposed to using separate Enums for the different
calendaring systems, and my understanding of the way modularity is
proposed would mean that these classes go into a non-core module,
which means there's less of a constraint in terms of size.

The direct month numbers should be available across all the date types.
The enums are a convenience; they can be worthwhile for the ISO case
but for the non-Gregorian calendars, the enums do not add enough value.

3. How does this interact with representation strategies?  I presume
Mixed Strategy is generally fine, even given the differing number of
months, since you still have a month and a day as a common concept
between chronologies.
I'm a bit unsure about what the solution for Epagomenal days is.  Are
you simply planning on having them as n+1 day within the previous
month, where n is the number of days in the month?  This then seems to
require some logic within the chronology in order to determine whether
the (DayOfMonth,EpochMonth) pair that is a mixed strategy date is
actually what it says it is.  Is there a cleaner solution?
I think mixed strategy will need major changes, effectively another strategy...
Good thing you mention this - since I was about to start a blog post
about different ThreeTen implementation strategies!  Also, if you want
any assistance/review/brainstorming on this front then we're happy to

The approach taken in one version of the API already implemented
is to treat the Epagomenal days as belonging to a separate month;
that's pretty clean (from the computer's perspective).  I've yet to see
an description of another workable treatment. 
How do real people talk about these extra days?


Virtualization & Cloud Management Using Capacity Planning
Cloud computing makes use of virtualization - but cloud computing 
also focuses on allowing computing to be delivered as a service.
threeten-develop mailing list