Package org.silverpeas.core.date

Class TemporalFormatter

  • public class TemporalFormatter
extends Object
    A formatter of date and datetime in String into different formats, both localized and ISO. It provides both methods to perform formatting of temporal objects in text and methods to perform formatting of date/datetime text representation into their temporal counterpart.
    Author:
    mmoquillon

    • Method Detail

      • toTemporal

        public static Temporal toTemporal​(String iso8601DateTime,
                                  boolean strict)

        Formats the specified ISO-8601 representation of a date/datetime into its corresponding Temporal object.

        Parameters:
        iso8601DateTime - an ISO-8601 representation of a date or of a datetime.
        strict - should be the parsing of the specified string strict? If true, a DateTimeParseException exception will be thrown if the string isn't correctly formatted. Otherwise null is simply returned.
        Returns:
        the Temporal instance decoded from the specified string. According to the date/datetime representation, the following temporal is returned:

        • a datetime with an offset indication: returns a OffsetDateTime instance
        • a datetime with a Zone id indication: returns a ZonedDateTime instance
        • a datetime without any offset nor zone id indication: returns a LocalDateTime instance
        • a date: returns a LocalDate instance

      • toIso8601

        public static String toIso8601​(Temporal temporal,
                               boolean withSeconds)

        Formats the specified temporal into the extended ISO-8601 String representation. The rules of formatting are based upon the DateTimeFormatter that fully follows the extended format of the ISO-8601 specification. The extended format is about the representation of the offset of the time.

        If the temporal is a date, then the ISO-8601 representation will be of an ISO local date. If the temporal is a local datetime, it will be converted without any Zone Offset indication, otherwise the offset will be printed out.

        Examples: 

           TemporalConverter.toIso8601(OffsetDateTime.now(), false)
   Result: 2018-03-13T15:11+01:00

   TemporalConverter.toIso8601(OffsetDateTime.now(), true)
   Result: 2018-03-13T15:11:14.971+01:00

   TemporalConverter.toIso8601(LocalDateTime.now(), false)
   Result: 2018-03-13T15:11

   TemporalConverter.toIso8601(LocalDateTime.now(), true)
   Result: 2018-03-13T15:11:14.971

   TemporalConverter.toIso8601(LocalDate, false)
   Result: 2018-03-13

   TemporalConverter.toIso8601(LocalDate, true)
   Result: 2018-03-13

        Parameters:
        temporal - a Temporal object to convert.
        withSeconds - if in the ISO-8601 string the seconds have to be represented (seconds following by nanoseconds can be optional a part according to the ISO 8601 specification). For displaying, usually the seconds aren't meaningful whereas for the datetime transport from one source to a target point this can be important.
        Returns:
        a String representation of the temporal in the extended format of the ISO-8601 specification.

      • toBaseIso8601

        public static String toBaseIso8601​(Temporal temporal,
                                   boolean withSeconds)

        Formats the specified temporal into the base ISO-8601 String representation.

        If the temporal is a date, then the ISO-8601 representation will be of an ISO local date. If the temporal is a local datetime, it will be converted without any Zone Offset indication, otherwise the offset will be printed out.

        Examples: 

           TemporalConverter.toIso8601(OffsetDateTime.now(), false)
   Result: 2018-03-13T15:11+0100

   TemporalConverter.toIso8601(OffsetDateTime.now(), true)
   Result: 2018-03-13T15:11:14.971+0100

   TemporalConverter.toIso8601(LocalDateTime.now(), false)
   Result: 2018-03-13T15:11

   TemporalConverter.toIso8601(LocalDateTime.now(), true)
   Result: 2018-03-13T15:11:14.971

   TemporalConverter.toIso8601(LocalDate, false)
   Result: 2018-03-13

   TemporalConverter.toIso8601(LocalDate, true)
   Result: 2018-03-13

        Parameters:
        withSeconds - if in the ISO-8601 string the seconds have to be represented (seconds following by nanoseconds can be optional a part according to the ISO 8601 specification). For displaying, usually the seconds aren't meaningful whereas for the datetime transport from one source to a target point this can be important.
        Returns:
        a String representation of the temporal in the base format of the ISO-8601 specification.

      • toLocalized

        public static String toLocalized​(Temporal temporal,
                                 String language)

        Formats the specified temporal into a string representation that conforms to the l10n rules of the country/language identified by the given ISO 632-1 locale code. The rules of formatting are based upon the DateTimeFormatter that fully follows the l10n rules of several country/language calendar systems.

        If the temporal is a date, then the localized representation will be of a local date. If the temporal is a local datetime, then the localized representation will be of a localized date + localized time. The seconds and nanoseconds aren't printed out as localized datetime are meaningful only for displaying usage (for transport, the ISO-8601 is always used).

        Examples: 

           TemporalConverter.toLocalized(OffsetDateTime.now(), "fr")
   Result: 13/03/2018 15:11

   TemporalConverter.toLocalized(LocalDate.now(), "fr")
   Result: 13/03/2018

        Parameters:
        temporal - a Temporal object to convert.
        language - an ISO 632-1 language code.
        Returns:
        a localized string representation of the temporal. The localized representation is based upon the l10n standard rules for the specified ISO 632-1 code.

      • toLocalizedDate

        public static String toLocalizedDate​(Temporal temporal,
                                     ZoneId zoneId,
                                     String language)

        Formats the specified temporal, for the specified zone identifier, into a string representation that conforms to the l10n rules of the country/language identified by the given ISO 632-1 locale code. The rules of formatting are based upon the DateTimeFormatter that fully follows the l10n rules of several country/language calendar systems. If the zone id of the temporal differs from the specified one, then the zone id of the temporal will be also formatted and represented into the returned result. Otherwise, this method will behave as the toLocalized(Temporal, String) one.

        This method is useful to format temporal expressed in a given timezone in its localized representation and for which the renderer is on a possible different timezone.

        If the temporal is a date, then the localized representation will be of a local date. If the temporal is a local datetime, then the localized representation will be of a localized date + localized time. If the temporal is in another timezone than the specified one, then the localized representation of the temporal will be expressed with its timezone. For datetime, the seconds and nanoseconds aren't represented as localized datetime are meaningful only for displaying usage (for transport, the ISO-8601 is always used).

        Examples: 

           TemporalConverter.toLocalized(OffsetDateTime.now(ZoneId.of("Europe/Paris")),
   ZoneId.of("America/Cancun"), "fr")
   Result: 13/03/2018 09:11 (Europe/Paris)

   TemporalConverter.toLocalized(OffsetDateTime.now(ZoneId.of("America/Cancun")),
   ZoneId.of("America/Cancun"), "fr")
   Result: 13/03/2018 09:11

        Parameters:
        temporal - a Temporal object to convert.
        zoneId - the zone id of the renderer or any objects that will handle the localized representation of the temporal.
        language - an ISO 632-1 language code.
        Returns:
        a localized string representation of the temporal. The localized representation is based upon the l10n standard rules for the specified ISO 632-1 code.

      • toLocalized

        public static String toLocalized​(Temporal temporal,
                                 ZoneId zoneId,
                                 String language)

        Formats the specified temporal, for the specified zone identifier, into a string representation that conforms to the l10n rules of the country/language identified by the given ISO 632-1 locale code. The rules of formatting are based upon the DateTimeFormatter that fully follows the l10n rules of several country/language calendar systems. If the zone id of the temporal differs of the specified one, then the zone id of the temporal will be also formatted and represented into the returned result. In the case the temporal doesn't carry its own time zone, if its time offset differs of the time offset implied by the specified time zone, then the time offset of the temporal will be also formatted and represented into the returned result. Otherwise, this method will behave as the toLocalized(Temporal, String) one.

        This method is useful to format temporal expressed in a given timezone or in a given time offset in its localized representation and for which the renderer is on a possible different timezone. Be cautious with temporal only expressed by a time offset and not by a time zone because with the daylight the rendered text can change (the time offset differ from winter to summer daylight for a same zone id).

        If the temporal is a date, then the localized representation will be of a local date. If the temporal is a local datetime, then the localized representation will be of a localized date + localized time. If the temporal is in another timezone (time offset) than the specified one, then the localized representation of the temporal will be expressed with its timezone (or time offset). For datetime, the seconds and nanoseconds aren't represented as localized datetime are meaningful only for displaying usage (for transport, the ISO-8601 is always used).

        Examples: 

           TemporalFormatter.toLocalized(ZonedDateTime.now(ZoneId.of("Europe/Paris")),
   ZoneId.of("America/Cancun"), "fr")
   Result: 13/03/2018 09:11 (Europe/Paris)

   TemporalFormatter.toLocalized(OffsetDateTime.now(ZoneId.of("Europe/Paris")),
    ZoneId.of("America/Cancun"), "fr")
    Result for a day in February: 13/02/2018 09:11 (+01:00)
    Result for a day in April   : 13/04/2018 09:11 (+02:00)

   TemporalFormatter.toLocalized(OffsetDateTime.now(ZoneId.of("America/Cancun")),
   ZoneId.of("America/Cancun"), "fr")
   Result: 13/03/2018 09:11

        Parameters:
        temporal - a Temporal object to convert.
        zoneId - the zone id of the renderer or any objects that will handle the localized representation of the temporal.
        language - an ISO 632-1 language code.
        Returns:
        a localized string representation of the temporal. The localized representation is based upon the l10n standard rules for the specified ISO 632-1 code.