javax.time
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.

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
 Instant toInstant()
          Returns an instance of Instant initialized from the state of this object.
 

Method Detail

toInstant

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.

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