public interface DateTimeProvider extends DateProvider, TimeProvider
DateTimeProvider is a simple interface that provides uniform access to any object that can provide access to a date-time in the ISO-8601 calendar system.
The implementation of DateTimeProvider
may be mutable.
For example, GregorianCalendar
is a
mutable implementation of this interface.
The result of toLocalDateTime()
, however, is immutable.
When implementing an API that accepts a DateTimeProvider as a parameter, it is
important to convert the input to a LocalDateTime
once and once only.
It is recommended that this is done at the top of the method before other processing.
This is necessary to handle the case where the implementation of the provider is
mutable and changes in value between two calls to toLocalDateTime()
.
The recommended way to convert a DateTimeProvider to a LocalDateTime is using
LocalDateTime.of(DateTimeProvider)
as this method provides additional null checking.
It is recommended that this interface should only be implemented by classes that provide time information to at least minute precision.
The implementation of DateTimeProvider
may provide more
information than just a local date-time. For example, ZonedDateTime
,
implements this interface and also provides a time-zone.
DateTimeProvider makes no guarantees about the thread-safety or immutability of implementations.
Modifier and Type | Method and Description |
---|---|
LocalDateTime |
toLocalDateTime()
Returns an instance of
LocalDateTime initialized from the
state of this object. |
toLocalDate
toLocalTime
LocalDateTime toLocalDateTime()
LocalDateTime
initialized from the
state of this object.
This method will take the date-time represented by this object and return
a LocalDateTime
constructed using the year, month, day, hour,
minute, second and nanosecond. If this object is already a
LocalDateTime
then it is simply returned.
If this object does not support nanosecond precision, then all fields below the precision it does support must be set to zero. For example, if this instance only stores hours, minutes and seconds, then the nanoseconds part will be set to zero.
The result of this method is a LocalDateTime
which represents
a date in the ISO calendar system. Implementors may perform conversion
when implementing this method to convert from alternate calendar systems.
LocalDateTime
equivalent to this object, never nullCalendricalException
- if the date-time cannot be convertedCopyright © 2014. All rights reserved.