Package net.time4j.format

Class CalendarText

java.lang.Object
net.time4j.format.CalendarText
public final class CalendarText extends Object

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): 

  DAY_OF_WEEK(WIDE)_1=Montag
  DAY_OF_WEEK(WIDE)_2=Dienstag
  DAY_OF_WEEK(WIDE)_3=Mittwoch
  DAY_OF_WEEK(WIDE)_4=Donnerstag
  DAY_OF_WEEK(WIDE)_5=Freitag
  DAY_OF_WEEK(WIDE)_6=Sonnabend
  DAY_OF_WEEK(WIDE)_7=Sonntag

The general format of these lines is: 

  {element-name}({text-width}[|STANDALONE])_{one-based-integer}={text}

STANDALONE is optional. As element name in the context of ISO-8601 following names are supported:

  • MONTH_OF_YEAR
  • QUARTER_OF_YEAR
  • DAY_OF_WEEK
  • ERA
  • AM_PM_OF_DAY
Author:
Meno Hochschild

  • Field Details

    • ISO_CALENDAR_TYPE

      public static final String ISO_CALENDAR_TYPE

      Default calendar type for all ISO systems.

      See Also:
      Constant Field Values

  • Method Details

    • getIsoInstance

      public static CalendarText getIsoInstance​(Locale locale)

      Returns an instance of CalendarText for ISO calendar systems and given language.

      Parameters:
      locale - language
      Returns:
      CalendarText object maybe cached
      Since:
      3.13/4.10

    • getInstance

      public static CalendarText getInstance​(Chronology<?> chronology, Locale locale)

      Returns an instance of CalendarText for given chronology and language.

      Parameters:
      chronology - chronology (with calendar system)
      locale - language
      Returns:
      CalendarText object maybe cached

    • getInstance

      public static CalendarText getInstance​(String calendarType, Locale locale)

      Returns an instance of CalendarText for given calendar type and language.

      Parameters:
      calendarType - name of calendar system
      locale - language
      Returns:
      CalendarText object maybe cached
      See Also:
      CalendarType

    • getStdMonths

      public TextAccessor getStdMonths​(TextWidth textWidth, OutputContext outputContext)

      Yields an Accessor for all standard months.

      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.

      Parameters:
      textWidth - text width of displayed month name
      outputContext - output context (stand-alone?)
      Returns:
      accessor for standard month names
      See Also:
      Month

    • getLeapMonths

      public TextAccessor getLeapMonths​(TextWidth textWidth, OutputContext outputContext)

      Yields an Accessor for all months if a leap month is relevant.

      Note: Leap months are defined in some calendar systems like the hebrew calendar ("Adar II") else there is no difference between standard and leap months escpecially not in ISO-8601.

      Parameters:
      textWidth - text width of displayed month name
      outputContext - output context (stand-alone?)
      Returns:
      accessor for month names
      See Also:
      Month, getStdMonths(TextWidth, OutputContext)

    • getQuarters

      public TextAccessor getQuarters​(TextWidth textWidth, OutputContext outputContext)

      Yields an Accessor for all quarter years.

      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.

      Parameters:
      textWidth - text width of displayed quarter name
      outputContext - output context (stand-alone?)
      Returns:
      accessor for quarter names
      See Also:
      Quarter

    • getWeekdays

      public TextAccessor getWeekdays​(TextWidth textWidth, OutputContext outputContext)

      Yields an Accessor for all weekday names.

      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.

      Parameters:
      textWidth - text width of displayed weekday name
      outputContext - output context (stand-alone?)
      Returns:
      accessor for weekday names
      See Also:
      Weekday

    • getEras

      public TextAccessor getEras​(TextWidth textWidth)

      Yields an Accessor for all era names.

      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.

      Parameters:
      textWidth - text width of displayed era name
      Returns:
      accessor for era names
      See Also:
      CalendarSystem.getEras()

    • getMeridiems

      public TextAccessor getMeridiems​(TextWidth textWidth, OutputContext outputContext)

      Yields an Accessor for all am/pm-names.

      The underlying list of text forms is sorted in AM-PM-order. The order of element value enums must be the same.

      Parameters:
      textWidth - text width of displayed AM/PM name
      outputContext - output context (stand-alone?)
      Returns:
      accessor for AM/PM names
      See Also:
      Meridiem

    • getTextForms

      public Map<String,​String> getTextForms()

      Yields all text forms in raw format.

      Returns:
      unmodifiable map of all text forms
      Since:
      3.12/4.9

    • getTextForms

      public <V extends Enum<V>> TextAccessor getTextForms​(ChronoElement<V> element, String... variants)

      Yields an Accessor for all text forms of given chronological element.

      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"):

      1. value of "E(a|alt)_1"
      2. value of "E(a)_1"
      3. value of "E_1"
      4. fallback=>AD
      Type Parameters:
      V - generic type of element values based on enums
      Parameters:
      element - element text forms are searched for
      variants - text form variants (optional)
      Returns:
      accessor for any text forms
      Throws:
      MissingResourceException - if for given calendar type there are no text resource files

    • getTextForms

      public <V extends Enum<V>> TextAccessor getTextForms​(String name, Class<V> type, String... variants)

      See getTextForms(ChronoElement, String...).

      Type Parameters:
      V - generic type of element values based on enums
      Parameters:
      name - name of text entries in resource file
      type - type of enum values
      variants - text form variants (optional)
      Returns:
      accessor for any text forms
      Throws:
      MissingResourceException - if for given calendar type there are no text resource files
      Since:
      3.11/4.8

    • patternForDate

      @Deprecated public static String patternForDate​(DisplayMode mode, Locale locale)
      Deprecated.
      Use patternForDate(FormatStyle, Locale)

      Returns the localized date pattern suitable for formatting of objects of type PlainDate.

      Parameters:
      mode - display mode
      locale - language and country setting
      Returns:
      localized date pattern
      Since:
      3.13/4.10
      See Also:
      PlainDate

    • patternForTime

      @Deprecated public static String patternForTime​(DisplayMode mode, Locale locale)
      Deprecated.
      Use patternForTime(FormatStyle, Locale)

      Returns the localized time pattern suitable for formatting of objects of type PlainTime.

      Parameters:
      mode - display mode
      locale - language and country setting
      Returns:
      localized time pattern
      Since:
      3.13/4.10
      See Also:
      PlainTime

    • patternForTimestamp

      @Deprecated public static String patternForTimestamp​(DisplayMode dateMode, DisplayMode timeMode, Locale locale)
      Deprecated.
      Use patternForTimestamp(FormatStyle, FormatStyle, Locale)

      Yields a format pattern without any timezone symbols for plain timestamps.

      Parameters:
      dateMode - display mode of date part
      timeMode - display mode of time part
      locale - language and country setting
      Returns:
      format pattern for plain timestamps without timezone symbols
      Since:
      3.13/4.10
      See Also:
      PlainTimestamp

    • patternForMoment

      @Deprecated public static String patternForMoment​(DisplayMode dateMode, DisplayMode timeMode, Locale locale)
      Deprecated.
      Use patternForMoment(FormatStyle, FormatStyle, Locale)

      Returns the localized date-time pattern suitable for formatting of objects of type Moment.

      Parameters:
      dateMode - display mode of date part
      timeMode - display mode of time part
      locale - language and country setting
      Returns:
      localized date-time pattern including timezone symbols
      Since:
      3.13/4.10
      See Also:
      Moment

    • patternForDate

      public static String patternForDate​(FormatStyle style, Locale locale)

      Returns the localized date pattern suitable for formatting of objects of type PlainDate.

      Parameters:
      style - format style
      locale - language and country setting
      Returns:
      localized date pattern
      Since:
      5.8
      See Also:
      PlainDate

    • patternForTime

      public static String patternForTime​(FormatStyle style, Locale locale)

      Returns the localized time pattern suitable for formatting of objects of type PlainTime.

      Parameters:
      style - format style
      locale - language and country setting
      Returns:
      localized time pattern
      Since:
      5.8
      See Also:
      PlainTime

    • patternForTimestamp

      public static String patternForTimestamp​(FormatStyle dateStyle, FormatStyle timeStyle, Locale locale)

      Yields a format pattern without any timezone symbols for plain timestamps.

      Parameters:
      dateStyle - format style of date part
      timeStyle - format style of time part
      locale - language and country setting
      Returns:
      format pattern for plain timestamps without timezone symbols
      Since:
      5.8
      See Also:
      PlainTimestamp

    • patternForMoment

      public static String patternForMoment​(FormatStyle dateStyle, FormatStyle timeStyle, Locale locale)

      Returns the localized date-time pattern suitable for formatting of objects of type Moment.

      Parameters:
      dateStyle - format style of date part
      timeStyle - format style of time part
      locale - language and country setting
      Returns:
      localized date-time pattern including timezone symbols
      Since:
      5.8
      See Also:
      Moment

    • patternForInterval

      public static String patternForInterval​(Locale locale)

      Returns the localized interval pattern.

      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.

      Parameters:
      locale - language and country setting
      Returns:
      localized interval pattern
      Since:
      3.13/4.10

    • toString

      public String toString()

      Yields the name of the internal TextProvider in conjunction with the configuring locale.

      Overrides:
      toString in class Object

    • clearCache

      public static void clearCache()

      Clears the internal cache.

      This method should be called if the internal text resources have changed and must be reloaded with a suitable ClassLoader.

    • isRTL

      public static boolean isRTL​(Locale locale)

      Determines if given language is written in right-to-left direction.

      Parameters:
      locale - language to be checked
      Returns:
      true if right-to-left else false
      Since:
      3.25/4.21