Interface InstantProvider
-
- All Known Implementing Classes:
Instant
,OffsetDateTime
,ZonedDateTime
public interface InstantProvider
Provides access to an instant on the time-line.InstantProvider
is a simple interface that provides uniform access to any object that can provide access to anInstant
.The implementation of
InstantProvider
may be mutable. For example,Date
is a mutable implementation of this interface. The result of callingtoInstant()
is always immutable.When implementing an API that accepts an
InstantProvider
as a parameter, it is important to convert the input to aInstant
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 totoInstant()
.The recommended way to convert an
InstantProvider
to aInstant
is usingInstant.of(InstantProvider)
as this method provides additional null checking.The implementation of
InstantProvider
may provide more information than just an instant. For example,ZonedDateTime
, implements this interface and also provides full date, time and time-zone information.InstantProvider makes no overall guarantees about the thread-safety or immutability of implementations. However, the method itself has a specific thread-safe guarantee.
- Author:
- Michael Nascimento Santos, Stephen Colebourne
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description Instant
toInstant()
Returns an instance ofInstant
initialized from the state of this object.
-
-
-
Method Detail
-
toInstant
Instant toInstant()
Returns an instance ofInstant
initialized from the state of this object.This method will take the instant represented by this object and return an
Instant
. If this object is already aInstant
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 millisecond precision, then the nanoseconds part of the
Instant
will be set to zero. It is recommended that this interface should only be implemented by classes that provide time information to at least minute precision.InstantProvider makes no overall guarantees about the thread-safety. However, this method must return a fully consistent result. For example, if the implementation is mutable and contains two fields, then the result of this method must refer to a valid snapshot of both fields, and not a snapshot where one field has been updated and not the other.
- Returns:
- the
Instant
equivalent to this object, never null - Throws:
CalendricalException
- if the time cannot be converted
-
-