time
Class Instant

java.lang.Object
  time.Instant

All Implemented Interfaces:

java.lang.Comparable<Instant>

public final class Instant
extends java.lang.Object
implements java.lang.Comparable<Instant>

Instant is the implementation of a fully immutable instant in time. An instant in time represents an event that have theorically no duration.

An Instant represents a point in the universal line of time, which is supposed to be the same everywhere in the whole Universe. (This is a Newtonian vision of the Time which is known as approximated since Einstein's Theory of Relativity, which shows that space and time are linked, but this approximation is fine for us).

Here some examples of famous instants:

• the revolt of Spartacus,
• the supernovae of the Crab Nebula, observed by Chinese astronomers almost 1000 years ago,
• the birth of Beethoven,
• the first man on Moon.

Instant are conceptualy independant from Human representations of Time (calendar...). They simply exists by themself.

To ensure compatibility with existing classes in Java, Instant are implemented as milliseconds since the Java Epoch of 1970-01-01 00:00:00 GMT, but please note that this is only an implementation detail. The current implementation is then milliseconds accurate, but future implementation may offer finer accuracy (nanoseconds).

Instants are Comparable, and their natural order is the chronological order.

Two Instants are equals if they represent the same instant in time (they occur at exactly the same moment).

As Instant are immutable, they are fully thread-safe.

Note:

Technically, an Instant looks like a immutable java.util.Date. But you should be aware that conceptually, they are very different, since a java.util.Date is supposed to be a date.

Author:

Arnaud Roques

Field Summary

static Instant	APOCALYPSE The maximum value of an Instant, which will happen about 292 millions of years after the Epoch.
static Instant	BIG_BANG The minimum value of an Instant, about 292 millions of years before the Epoch.
static Instant	EPOCH The famous Epoch. (1970-01-01 00:00:00)

Constructor Summary

Instant()
Create a new Instant, which represents the current time (now).

Instant(java.util.Date date)
Create a new Instant.

Instant(long millis)
Create a new Instant.

Method Summary

java.util.Date	asImmutableDate() Return a java.util.Date view of this Instant.
int	compareTo(Instant otherInstant) Compare two instants chronogically.
boolean	equals(java.lang.Object obj) Compare two instants for equality.
long	getMillis() Returns the number of milliseconds since the Epoch represented by this Instant object.
long	getNanos() Returns 0L in this current implementation..
int	hashCode() Returns a hash code value for this object.
long	millisBetween(Instant otherInstant) Compute the number of milliseconds between this instant and another instant.
java.lang.String	toString() Convert this Instant to a String.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EPOCH

public static final Instant EPOCH

The famous Epoch. (1970-01-01 00:00:00)

BIG_BANG

public static final Instant BIG_BANG

The minimum value of an Instant, about 292 millions of years before the Epoch. We cannot have instant before this BIG_BANG. (This is not the real astrophysical BigBang, which have occured between 10 and 20 billions of years before the Epoch).

APOCALYPSE

public static final Instant APOCALYPSE

The maximum value of an Instant, which will happen about 292 millions of years after the Epoch. This is not the real Apocalypse.

Constructor Detail

Instant

public Instant()

Create a new Instant, which represents the current time (now).

Instant

public Instant(long millis)

Create a new Instant. This constructor is provided for compatibility with existing code.

Parameters:

millis - number of milliseconds since the Epoch of the Instant to create

Instant

public Instant(java.util.Date date)

Create a new Instant. This constructor is provided for compatibility with existing java.util.Date.

Parameters:

date - Date of the Instant to create.

Throws:

java.lang.NullPointerException - if date is null.

Method Detail

compareTo

public int compareTo(Instant otherInstant)

Compare two instants chronogically.

Specified by:

compareTo in interface java.lang.Comparable<Instant>

Parameters:

otherInstant - the instant to be compared.

Returns:

the value 0 if the argument instant is equal to this instant; a value less than 0 if this instant occurs before the instant argument; and a value greater than 0 if this instant occurs after than the instant argument.

Throws:

java.lang.NullPointerException - if otherInstant is null.

millisBetween

public long millisBetween(Instant otherInstant)

Compute the number of milliseconds between this instant and another instant.

If this instant occurs after the other instant, the result is positive. If this instant occurs before the other instant, the result is negative.

Returns:

the number of milliseconds between this instant and another instant.

Throws:

java.lang.NullPointerException - if otherInstant is null.

equals

public boolean equals(java.lang.Object obj)

Compare two instants for equality. The result is true if and only if the argument is not null and is a Instant object that represents the same point in time, (with a millisecond accuracy in this implementation) , than this object.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare with.

Returns:

true if the objects are the same; false otherwise.

hashCode

public int hashCode()

Returns a hash code value for this object.

Overrides:

hashCode in class java.lang.Object

asImmutableDate

public java.util.Date asImmutableDate()

Return a java.util.Date view of this Instant.

The returned date is immutable, as the returned class is a subclass of java.util.Date which all mutating methods have been overidden to throw a UnsupportedOperationException.

Returns:

the immutable date representing the same instant as this object.

getMillis

public long getMillis()

Returns the number of milliseconds since the Epoch represented by this Instant object.

Returns:

the number of milliseconds since the Epoch represented by this Instant object.

getNanos

public long getNanos()

Returns 0L in this current implementation..

Returns:

0L.

toString

public java.lang.String toString()

Convert this Instant to a String.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this instant