Package org.apache.sis.internal.util

Class StandardDateFormat

java.lang.Object
java.text.Format
java.text.DateFormat
org.apache.sis.internal.util.StandardDateFormat
All Implemented Interfaces:
Serializable, Cloneable
public final class StandardDateFormat extends DateFormat
A date format used for parsing dates in the "yyyy-MM-dd'T'HH:mm:ss.SSSX" pattern, but in which the time is optional. For this class, "Standard" is interpreted as "close to ISO 19162 requirements", which is not necessarily identical to other ISO standards.

External users should use nothing else than the parsing and formatting methods. The methods for configuring the DateFormat instances may or may not work depending on the branch.

The main usage for this class is Well Known Text (WKT) parsing and formatting. ISO 19162 uses ISO 8601:2004 for the dates. Any precision is allowed: the date could have only the year, or only the year and month, etc. The clock part is optional and also have optional fields: can be only hours, or only hours and minutes, etc. ISO 19162 said that the timezone is restricted to UTC but nevertheless allows to specify a timezone.

Since:
0.6
Version:
1.1
See Also:

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:

    • UTC

      public static final String UTC
      The "UTC" timezone ID.
      See Also:

    • MIDNIGHT

      private static final OffsetTime MIDNIGHT
      Midnight (00:00) UTC.

    • FORMAT

      public static final DateTimeFormatter FORMAT
      The thread-safe instance to use for reading and formatting dates. Only the year is mandatory, all other fields are optional at parsing time. However, all fields are written, including milliseconds at formatting time.
      See Also:

    • QUERIES

      private static TemporalQuery<?>[] QUERIES
      The kinds of objects to get from calls to parseBest(CharSequence), in preference order. The time is converted to UTC timezone if possible.
      Tip: if we want to preserve the timezone instead of converting to UTC, we could try replacing Instant::from by ZonedDateTime::from, OffsetDateTime::from.
      See Also:

    • MILLISECONDS_PER_DAY

      public static final int MILLISECONDS_PER_DAY
      The length of a day in number of milliseconds. Can be casted to float with exact precision.
      See Also:

    • MILLIS_PER_SECOND

      public static final int MILLIS_PER_SECOND
      Number of milliseconds in one second. Can be casted to float with exact precision.
      See Also:

    • NANOS_PER_MILLISECOND

      public static final int NANOS_PER_MILLISECOND
      Number of nanoseconds in one millisecond. Can be casted to float with exact precision.
      See Also:

    • NANOS_PER_SECOND

      public static final int NANOS_PER_SECOND
      Number of nanoseconds in one second. Can be casted to float with exact precision.
      See Also:

    • format

      private DateTimeFormatter format
      The java.time parser and formatter. This is usually the FORMAT instance unless a different locale or timezone has been specified.

  • Constructor Details

    • StandardDateFormat

      public StandardDateFormat()
      Creates a new format for a default locale in the UTC timezone.

    • StandardDateFormat

      public StandardDateFormat(Locale locale)
      Creates a new format for the given locale in the UTC timezone.
      Parameters:
      locale - the locale of the format to create.

    • StandardDateFormat

      public StandardDateFormat(Locale locale, TimeZone zone)
      Creates a new format for the given locale.
      Parameters:
      locale - the locale of the format to create.
      zone - the timezone.

  • Method Details

    • parseBest

      public static Temporal parseBest(CharSequence text)
      Parses the given date and/or time, which may have an optional timezone. This method applies heuristic rules for choosing if the object should be returned as a local date, or a date and time with timezone, etc. The full date format is of the form "1970-01-01T00:00:00.000Z", but this method also accepts spaces in place of 'T' as in "1970-01-01 00:00:00".
      Parameters:
      text - the character string to parse, or null.
      Returns:
      a temporal object for the given text, or null if the given text was null.
      Throws:
      DateTimeParseException - if the text cannot be parsed as a date.
      Since:
      0.8

    • parseInstantUTC

      public static Instant parseInstantUTC(CharSequence text)
      Parses the given date as an instant, assuming UTC timezone if unspecified.
      Parameters:
      text - the text to parse as an instant in UTC timezone by default, or null.
      Returns:
      the instant for the given text, or null if the given text was null.
      Throws:
      DateTimeParseException - if the text cannot be parsed as a date.

    • parseInstantUTC

      public static Instant parseInstantUTC(CharSequence text, int lower, int upper)
      Parses the given date as an instant, assuming UTC timezone if unspecified.
      Parameters:
      text - the text to parse as an instant in UTC timezone by default.
      lower - index of the first character to parse.
      upper - index after the last character to parse.
      Returns:
      the instant for the given text.
      Throws:
      DateTimeParseException - if the text cannot be parsed as a date.

    • toISO

      static CharSequence toISO(CharSequence text, int lower, int upper)
      Modifies the given date and time string for making it more compliant to ISO syntax. If date and time are separated by spaces, then this method replaces those spaces by the 'T' letter. All other spaces that are not between two digits are removed.
      Parameters:
      text - the text to make more compliant with ISO syntax.
      lower - index of the first character to examine.
      upper - index after the last character to examine.
      Returns:
      sub-sequence of text from lower to upper, potentially modified.

    • toHeuristicTemporal

      public static Temporal toHeuristicTemporal(Date date, ZoneId zone)
      Converts the given legacy Date object into a java.time implementation in given timezone. The method performs the following choice:
      • If the given date has zero values in hours, minutes, seconds and milliseconds fields in UTC timezone, then the returned implementation will be a LocalDate, dropping the timezone information (i.e. the date is considered an approximation). Note that this is consistent with ISO 19162 requirement that dates are always in UTC, even if Apache SIS allows some flexibility.
      • Otherwise if the timezone is not null and not UTC, then this method returns an OffsetDateTime.
      • Otherwise this method returns a LocalDateTime in the given timezone.
      Parameters:
      date - the date to convert, or null.
      zone - the timezone of the temporal object to obtain, or null for UTC.
      Returns:
      the temporal object for the given date, or null if the given argument was null.

    • toDate

      public static Date toDate(TemporalAccessor temporal)
      Converts the given temporal object into a date. The given temporal object is typically the value parsed by FORMAT.
      Parameters:
      temporal - the temporal object to convert, or null.
      Returns:
      the legacy date for the given temporal object, or null if the argument was null.
      Throws:
      DateTimeException - if a value for the field cannot be obtained.
      ArithmeticException - if the number of milliseconds is too large.

    • hasDateFields

      public static boolean hasDateFields(Class<?> date)
      Returns true if objects of the given class have day, month and hour fields. This method is defined here for having a single class where to concentrate such heuristic rules. Note that Instant does not have date fields.
      Parameters:
      date - class of object to test (may be null).
      Returns:
      whether the given class is LocalDate or one of the classes with date + time. This list may be expanded in future versions.

    • hasTimeFields

      public static boolean hasTimeFields(Class<?> date)
      Returns true if objects of the given class have time fields. This method is defined here for having a single class where to concentrate such heuristic rules. Note that Instant does not have hour fields.
      Parameters:
      date - class of object to test (may be null).
      Returns:
      whether the given class is LocalTime, OffsetTime or one of the classes with date + time. This list may be expanded in future versions.

    • getCalendar

      public final Calendar getCalendar()
      Returns the calendar, creating it when first needed. This StandardDateFormat class does not use the calendar, but we nevertheless create it if requested in order to comply with DateFormat contract.
      Overrides:
      getCalendar in class DateFormat
      Returns:
      a calendar, created when first needed.

    • getNumberFormat

      public final NumberFormat getNumberFormat()
      Returns the number format, creating it when first needed. This StandardDateFormat class does not use the number format, but we nevertheless create it if requested in order to comply with DateFormat contract.
      Overrides:
      getNumberFormat in class DateFormat
      Returns:
      a number format, created when first needed.

    • getTimeZone

      public final TimeZone getTimeZone()
      Returns the timezone used for formatting instants.
      Overrides:
      getTimeZone in class DateFormat
      Returns:
      the timezone.

    • setTimeZone

      public final void setTimeZone(TimeZone zone)
      Sets the timezone.
      Overrides:
      setTimeZone in class DateFormat
      Parameters:
      zone - the new timezone.

    • setLenient

      public final void setLenient(boolean lenient)
      Overridden for compliance with DateFormat contract, but has no incidence on this format.
      Overrides:
      setLenient in class DateFormat
      Parameters:
      lenient - value forwarded to Calendar.setLenient(boolean).

    • isLenient

      public final boolean isLenient()
      Overridden for compliance with DateFormat contract, but has no incidence on this format.
      Overrides:
      isLenient in class DateFormat
      Returns:
      value fetched Calendar.isLenient().

    • format

      public StringBuffer format(Date date, StringBuffer toAppendTo, FieldPosition pos)
      Formats the given date. If hours, minutes, seconds and milliseconds are zero and the timezone is UTC, then this method omits the clock part (unless the user has overridden the pattern).
      Specified by:
      format in class DateFormat
      Parameters:
      date - the date to format.
      toAppendTo - where to format the date.
      pos - ignored.
      Returns:
      the given buffer, for method calls chaining.

    • parse

      public Date parse(String text, ParsePosition position)
      Parses the given text starting at the given position. Contrarily to parse(String), this method does not accept spaces as a separator between date and time.
      Specified by:
      parse in class DateFormat
      Parameters:
      text - the text to parse.
      position - position where to start the parsing.
      Returns:
      the date, or null if we failed to parse it.

    • parse

      public Date parse(String text) throws ParseException
      Parses the given text. This method accepts space as a separator between date and time.
      Overrides:
      parse in class DateFormat
      Parameters:
      text - the text to parse.
      Returns:
      the date (never null).
      Throws:
      ParseException - if the parsing failed.

    • getErrorIndex

      private static int getErrorIndex(RuntimeException e, ParsePosition position)
      Tries to infer the index where the parsing error occurred.

    • hashCode

      public int hashCode()
      Returns a hash code value for this format.
      Overrides:
      hashCode in class DateFormat
      Returns:
      a hash code value for this format.

    • equals

      public boolean equals(Object obj)
      Compares this format with the given object for equality.
      Overrides:
      equals in class DateFormat
      Parameters:
      obj - the object to compare with this format.
      Returns:
      if the two objects format in the same way.

    • clone

      public Object clone()
      Returns a clone of this format.
      Overrides:
      clone in class DateFormat
      Returns:
      a clone of this format.