Class CalendarText

Source for localized calendrical informations on enum basis like month
or weekday names.

This class is a facade for an underlying implementation of
TextProvider which will be loaded as SPI-interface
by help of a ServiceLoader. If no such SPI-interface can be
found then this class will resort to the sources of JDK (usually
as wrapper around java.text.DateFormatSymbols).

Furthermore, an instance of CalendarText can also access
the UTF-8 text resources in the folder "calendar" relative to
the class path which are not based on JDK-defaults. In this case the
presence of the i18n-module is required. In all ISO-systems the
"iso8601_{locale}.properties"-files will override the
JDK-defaults unless it is the ROOT-locale. Example:

If you wish to use the name "Sonnabend" instead of the standard
word "Samstag" in german locale (english: Saturday) then you can
copy the existing file "calendar/iso8601_de.properties" from the
content of "time4j-i18n-v{version}.jar"-file into a new directory
with the same path. Then you can insert these lines extra (all seven entries
must be inserted, not just the sixth line):

getStdMonths

The underlying list is sorted such that it will obey to the
typical order of months in given calendar system. ISO-systems
define January as first month and at whole 12 months. Other
calendar systems can also define for example 13 months. The order
of element value enums must be in agreement with the order of
the text forms contained here.

The default implementation handles SHORT as synonym for
ABBREVIATED in the context of ISO-8601.

getQuarters

The underlying list of text forms is sorted in the same order
as the enum Quarter and uses its ordinal index as list
index. ISO systems define the range January-March as first quarter
etc. and at whole four quarters per calendar year.

The default implementation handles SHORT as synonym for
ABBREVIATED in the context of ISO-8601.

getWeekdays

The underlying list of text forms is sorted such that the
typical order of weekdays is used in given calendar system.
ISO systems define Monday as first day of week and at whole
7 weekdays. This order is also valid for US in the context of
this class although in US Sunday is considered as start of a
week. The order element value enums must be in agreement with
the order of text forms contained here.

getEras

The underlying list of text forms is sorted such that the
typical order of eras is used in given calendar system. ISO systems
define era names based on their historical extensions (eras of
gregorian/historic calendar) because they themselves have no internal
concept of eras. The order of element value enums must be in agreement
with the text forms contained here. If an era is not defined on enum
basis then the format API will not evaluate this class but the
CalendarSystem to get the right text forms.

getTextForms

Text forms might exist in different variations. In case of
enum-based variants the name of the enum (example "WIDE" in
the variant TextWidth) is to be used, in case of boolean-based
variants the literals "true" and "false" are to be
used.

While the methods getStdMonths(), getWeekdays()
etc. are mainly based on JDK-defaults, this method is escpecially
designed for querying chronological texts which are not contained in
JDK. Text forms will be stored internally in the resource folder
"calendar" relative to class path in properties-files using
UTF-8 encoding. The basic name of these resources is the calendar type.
The combination of element name and optionally variants in the form
"(variant1|variant2|...|variantN)" and the underscore and
finally a numerical suffix with base 1 (for era elements base 0) serves
as resource text key. If there is no entry for given key in the resources
then this method will simply yield the name of enum value associated
with given element value.

As example, the search for abbreviated historic era HistoricEra.AD of alternative form
looks up keys in this order (using E if there is an entry "useShortKeys=true"):

patternForInterval

Expressions of the form "{0}" will be interpreted as the start boundary format
and expressions of the form "{1}" will be interpreted as the end boundary format.
All other chars of the pattern will be treated as literals.