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
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:
-
Nested Class Summary
Nested classes/interfaces inherited from class java.text.DateFormat
DateFormat.Field
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate DateTimeFormatter
Thejava.time
parser and formatter.static final DateTimeFormatter
The thread-safe instance to use for reading and formatting dates.private static final OffsetTime
Midnight (00:00) UTC.static final int
Number of milliseconds in one second.static final int
The length of a day in number of milliseconds.static final int
Number of nanoseconds in one millisecond.static final int
Number of nanoseconds in one second.private static TemporalQuery<?>[]
The kinds of objects to get from calls toparseBest(CharSequence)
, in preference order.private static final long
For cross-version compatibility.static final String
The "UTC" timezone ID.Fields inherited from class java.text.DateFormat
AM_PM_FIELD, calendar, DATE_FIELD, DAY_OF_WEEK_FIELD, DAY_OF_WEEK_IN_MONTH_FIELD, DAY_OF_YEAR_FIELD, DEFAULT, ERA_FIELD, FULL, HOUR_OF_DAY0_FIELD, HOUR_OF_DAY1_FIELD, HOUR0_FIELD, HOUR1_FIELD, LONG, MEDIUM, MILLISECOND_FIELD, MINUTE_FIELD, MONTH_FIELD, numberFormat, SECOND_FIELD, SHORT, TIMEZONE_FIELD, WEEK_OF_MONTH_FIELD, WEEK_OF_YEAR_FIELD, YEAR_FIELD
-
Constructor Summary
ConstructorsConstructorDescriptionCreates a new format for a default locale in the UTC timezone.StandardDateFormat
(Locale locale) Creates a new format for the given locale in the UTC timezone.StandardDateFormat
(Locale locale, TimeZone zone) Creates a new format for the given locale. -
Method Summary
Modifier and TypeMethodDescriptionclone()
Returns a clone of this format.boolean
Compares this format with the given object for equality.format
(Date date, StringBuffer toAppendTo, FieldPosition pos) Formats the given date.final Calendar
Returns the calendar, creating it when first needed.private static int
getErrorIndex
(RuntimeException e, ParsePosition position) Tries to infer the index where the parsing error occurred.final NumberFormat
Returns the number format, creating it when first needed.final TimeZone
Returns the timezone used for formatting instants.static boolean
hasDateFields
(Class<?> date) Returnstrue
if objects of the given class have day, month and hour fields.int
hashCode()
Returns a hash code value for this format.static boolean
hasTimeFields
(Class<?> date) Returnstrue
if objects of the given class have time fields.final boolean
Overridden for compliance withDateFormat
contract, but has no incidence on this format.Parses the given text.parse
(String text, ParsePosition position) Parses the given text starting at the given position.static Temporal
parseBest
(CharSequence text) Parses the given date and/or time, which may have an optional timezone.static Instant
parseInstantUTC
(CharSequence text) Parses the given date as an instant, assuming UTC timezone if unspecified.static Instant
parseInstantUTC
(CharSequence text, int lower, int upper) Parses the given date as an instant, assuming UTC timezone if unspecified.final void
setLenient
(boolean lenient) Overridden for compliance withDateFormat
contract, but has no incidence on this format.final void
setTimeZone
(TimeZone zone) Sets the timezone.static Date
toDate
(TemporalAccessor temporal) Converts the given temporal object into a date.static Temporal
toHeuristicTemporal
(Date date, ZoneId zone) Converts the given legacyDate
object into ajava.time
implementation in given timezone.(package private) static CharSequence
toISO
(CharSequence text, int lower, int upper) Modifies the given date and time string for making it more compliant to ISO syntax.Methods inherited from class java.text.DateFormat
format, format, getAvailableLocales, getDateInstance, getDateInstance, getDateInstance, getDateTimeInstance, getDateTimeInstance, getDateTimeInstance, getInstance, getTimeInstance, getTimeInstance, getTimeInstance, parseObject, setCalendar, setNumberFormat
Methods inherited from class java.text.Format
format, formatToCharacterIterator, parseObject
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
UTC
The "UTC" timezone ID.- See Also:
-
MIDNIGHT
Midnight (00:00) UTC. -
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
The kinds of objects to get from calls toparseBest(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 replacingInstant::from
byZonedDateTime::from, OffsetDateTime::from
.- See Also:
-
MILLISECONDS_PER_DAY
public static final int MILLISECONDS_PER_DAYThe length of a day in number of milliseconds. Can be casted tofloat
with exact precision.- See Also:
-
MILLIS_PER_SECOND
public static final int MILLIS_PER_SECONDNumber of milliseconds in one second. Can be casted tofloat
with exact precision.- See Also:
-
NANOS_PER_MILLISECOND
public static final int NANOS_PER_MILLISECONDNumber of nanoseconds in one millisecond. Can be casted tofloat
with exact precision.- See Also:
-
NANOS_PER_SECOND
public static final int NANOS_PER_SECONDNumber of nanoseconds in one second. Can be casted tofloat
with exact precision.- See Also:
-
format
Thejava.time
parser and formatter. This is usually theFORMAT
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
Creates a new format for the given locale in the UTC timezone.- Parameters:
locale
- the locale of the format to create.
-
StandardDateFormat
Creates a new format for the given locale.- Parameters:
locale
- the locale of the format to create.zone
- the timezone.
-
-
Method Details
-
parseBest
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, ornull
.- 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
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, ornull
.- 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
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
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
fromlower
toupper
, potentially modified.
-
toHeuristicTemporal
Converts the given legacyDate
object into ajava.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 anOffsetDateTime
. - Otherwise this method returns a
LocalDateTime
in the given timezone.
- Parameters:
date
- the date to convert, ornull
.zone
- the timezone of the temporal object to obtain, ornull
for UTC.- Returns:
- the temporal object for the given date, or
null
if the given argument was null.
- If the given date has zero values in hours, minutes, seconds and milliseconds fields in UTC timezone,
then the returned implementation will be a
-
toDate
Converts the given temporal object into a date. The given temporal object is typically the value parsed byFORMAT
.- Parameters:
temporal
- the temporal object to convert, ornull
.- 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
Returnstrue
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 thatInstant
does not have date fields.- Parameters:
date
- class of object to test (may benull
).- Returns:
- whether the given class is
LocalDate
or one of the classes with date + time. This list may be expanded in future versions.
-
hasTimeFields
Returnstrue
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 thatInstant
does not have hour fields.- Parameters:
date
- class of object to test (may benull
).- 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
Returns the calendar, creating it when first needed. ThisStandardDateFormat
class does not use the calendar, but we nevertheless create it if requested in order to comply withDateFormat
contract.- Overrides:
getCalendar
in classDateFormat
- Returns:
- a calendar, created when first needed.
-
getNumberFormat
Returns the number format, creating it when first needed. ThisStandardDateFormat
class does not use the number format, but we nevertheless create it if requested in order to comply withDateFormat
contract.- Overrides:
getNumberFormat
in classDateFormat
- Returns:
- a number format, created when first needed.
-
getTimeZone
Returns the timezone used for formatting instants.- Overrides:
getTimeZone
in classDateFormat
- Returns:
- the timezone.
-
setTimeZone
Sets the timezone.- Overrides:
setTimeZone
in classDateFormat
- Parameters:
zone
- the new timezone.
-
setLenient
public final void setLenient(boolean lenient) Overridden for compliance withDateFormat
contract, but has no incidence on this format.- Overrides:
setLenient
in classDateFormat
- Parameters:
lenient
- value forwarded toCalendar.setLenient(boolean)
.
-
isLenient
public final boolean isLenient()Overridden for compliance withDateFormat
contract, but has no incidence on this format.- Overrides:
isLenient
in classDateFormat
- Returns:
- value fetched
Calendar.isLenient()
.
-
format
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 classDateFormat
- Parameters:
date
- the date to format.toAppendTo
- where to format the date.pos
- ignored.- Returns:
- the given buffer, for method calls chaining.
-
parse
Parses the given text starting at the given position. Contrarily toparse(String)
, this method does not accept spaces as a separator between date and time.- Specified by:
parse
in classDateFormat
- 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
Parses the given text. This method accepts space as a separator between date and time.- Overrides:
parse
in classDateFormat
- Parameters:
text
- the text to parse.- Returns:
- the date (never null).
- Throws:
ParseException
- if the parsing failed.
-
getErrorIndex
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 classDateFormat
- Returns:
- a hash code value for this format.
-
equals
Compares this format with the given object for equality.- Overrides:
equals
in classDateFormat
- Parameters:
obj
- the object to compare with this format.- Returns:
- if the two objects format in the same way.
-
clone
Returns a clone of this format.- Overrides:
clone
in classDateFormat
- Returns:
- a clone of this format.
-