Interface InstantProvider

All Known Implementing Classes:
Calendar, Date, GregorianCalendar, 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 an Instant.

The implementation of InstantProvider may be mutable. For example, Date is a mutable implementation of this interface. The result of calling toInstant() is always immutable.

When implementing an API that accepts an InstantProvider as a parameter, it is important to convert the input to a Instant 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 toInstant().

The recommended way to convert an InstantProvider to a Instant is using Instant.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.

This interface makes no overall guarantees about the thread-safety or immutability of implementations. However, the method itself has a specific thread-safe guarantee.

Michael Nascimento Santos, Stephen Colebourne

Method Summary
 Instant toInstant()
          Returns an instance of Instant initialized from the state of this object.

Method Detail


Instant toInstant()
Returns an instance of Instant 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 a Instant 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.

Implementations must ensure that calls to this method are thread-safe. An immutable implementation will naturally provide this guarantee.

the Instant equivalent to this object, not null
CalendricalException - if the time cannot be converted