Java Doc for HebrewCalendar.java in  » Internationalization-Localization » icu4j » com » ibm » icu » util » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The Hebrew calendar is lunisolar and thus has a number of interesting properties that distinguish it from the Gregorian. Months start on the day of (an arithmetic approximation of) each new moon. Since the solar year (approximately 365.24 days) is not an even multiple of the lunar month (approximately 29.53 days) an extra "leap month" is inserted in 7 out of every 19 years. To make matters even more interesting, the start of a year can be delayed by up to three days in order to prevent certain holidays from falling on the Sabbath and to prevent certain illegal year lengths. Finally, the lengths of certain months can vary depending on the number of days in the year.

The leap month is known as "Adar 1" and is inserted between the months of Shevat and Adar in leap years. Since the leap month does not come at the end of the year, calculations involving month numbers are particularly complex. Users of this class should make sure to use the HebrewCalendar.roll roll and HebrewCalendar.add add methods rather than attempting to perform date arithmetic by manipulating the fields directly.

Note: In the traditional Hebrew calendar, days start at sunset. However, in order to keep the time fields in this class synchronized with those of the other calendars and with local clock time, we treat days and months as beginning at midnight, roughly 6 hours after the corresponding sunset.

If you are interested in more information on the rules behind the Hebrew calendar, see one of the following references:

• "Calendrical Calculations", by Nachum Dershowitz & Edward Reingold, Cambridge University Press, 1997, pages 85-91.
• Hebrew Calendar Science and Myths, http://www.geocities.com/Athens/1584/
• The Calendar FAQ, http://www.faqs.org/faqs/calendars/faq/

This class should not be subclassed.

HebrewCalendar usually should be instantiated using com.ibm.icu.util.Calendar.getInstance(ULocale) passing in a ULocale with the tag "@calendar=hebrew".

When adding to certain fields, the values of other fields may conflict and need to be changed. For example, when adding one to the HebrewCalendar.MONTH MONTH field for the date "30 Av 5758", the HebrewCalendar.DAY_OF_MONTH DAY_OF_MONTH field must be adjusted so that the result is "29 Elul 5758" rather than the invalid "30 Elul 5758".

This method is able to add to all fields except for HebrewCalendar.ERA ERA , HebrewCalendar.DST_OFFSET DST_OFFSET , and HebrewCalendar.ZONE_OFFSET ZONE_OFFSET .

Note: You should always use HebrewCalendar.roll roll and add rather than attempting to perform arithmetic operations directly on the fields of a HebrewCalendar. Since the HebrewCalendar.MONTH MONTH field behaves discontinuously in non-leap years, simple arithmetic can give invalid results.

Parameters:
  field - the time field.
Parameters:
  amount - the amount to add to the field.
exception:
  IllegalArgumentException - if the field is invalid or refersto a field that cannot be handled by this method.

• ERA
• YEAR
• MONTH
• DAY_OF_MONTH
• DAY_OF_YEAR
• EXTENDED_YEAR

In addition, subclasses should compute any subclass-specific fields, that is, fields from BASE_FIELD_COUNT to getFieldCount() - 1.

When rolling certain fields, the values of other fields may conflict and need to be changed. For example, when rolling the HebrewCalendar.MONTH MONTH field upward by one for the date "30 Av 5758", the HebrewCalendar.DAY_OF_MONTH DAY_OF_MONTH field must be adjusted so that the result is "29 Elul 5758" rather than the invalid "30 Elul".

This method is able to roll all fields except for HebrewCalendar.ERA ERA , HebrewCalendar.DST_OFFSET DST_OFFSET , and HebrewCalendar.ZONE_OFFSET ZONE_OFFSET . Subclasses may, of course, add support for additional fields in their overrides of roll.

Note: You should always use roll and HebrewCalendar.add add rather than attempting to perform arithmetic operations directly on the fields of a HebrewCalendar. Since the HebrewCalendar.MONTH MONTH field behaves discontinuously in non-leap years, simple arithmetic can give invalid results.

Parameters:
  field - the time field.
Parameters:
  amount - the amount by which the field should be rolled.
exception:
  IllegalArgumentException - if the field is invalid or refersto a field that cannot be handled by this method.