org.joda.time
Interface ReadableInstant

All Superinterfaces:

java.lang.Comparable

All Known Subinterfaces:

ReadableDateTime, ReadWritableInstant

All Known Implementing Classes:

AbstractDateTime, AbstractInstant, DateTime, Instant, MutableDateTime

public interface ReadableInstant

extends java.lang.Comparable

Readable interface for an instant in the datetime continuum.

This interface expresses the datetime as milliseconds from 1970-01-01T00:00:00Z.

Since:

1.0

Author:

Stephen Colebourne

Method Summary

int	compareTo(java.lang.Object readableInstant) Compares this object with the specified object for ascending millisecond instant order.
boolean	equals(java.lang.Object readableInstant) Compares this object with the specified object for equality based on the millisecond instant and the Chronology.
int	get(DateTimeField field) Get the value of one of the fields of a datetime.
Chronology	getChronology() Gets the chronology of the instant, null if not applicable.
DateTimeZone	getDateTimeZone() Gets the time zone of the instant, null if not applicable.
long	getMillis() Get the value as the number of miliseconds since the epoch, 1970-01-01T00:00:00Z.
int	hashCode() Gets a hash code for the instant that is compatable with the equals method.
boolean	isAfter(ReadableInstant readableInstant) Is the millisecond value after the millisecond passed in.
boolean	isBefore(ReadableInstant readableInstant) Is the millisecond value before the millisecond passed in.
boolean	isEqual(ReadableInstant readableInstant) Is the millisecond value equal to the millisecond passed in.
ReadableInstant	toCopy(Chronology newChronology) Gets a copy of this instant with a different chronology.
ReadableInstant	toCopy(long newMillis) Gets a copy of this instant with different millis.
Instant	toInstant() Get the value as a simple immutable Instant object.
java.lang.String	toString() Get the value as a String in a recognisable ISO8601 format.

Method Detail

getMillis

public long getMillis()

Get the value as the number of miliseconds since the epoch, 1970-01-01T00:00:00Z.

Returns:

the value as milliseconds

getChronology

public Chronology getChronology()

Gets the chronology of the instant, null if not applicable.

The Chronology provides conversion from the millisecond value to meaningful fields in a particular calendar system.

Returns:

the Chronology, null if not applicable

getDateTimeZone

public DateTimeZone getDateTimeZone()

Gets the time zone of the instant, null if not applicable.

Returns:

the DateTimeZone, null if not applicable

get

public int get(DateTimeField field)

Get the value of one of the fields of a datetime.

DateTimeField instances are generally obtained from a Chronology subclass. However, an application can create its own DateTimeField to manipulate the date time millis in new ways.

Parameters:

field - a DateTimeField instance, usually obtained from a Chronology

Returns:

the value of that field for the millis set in the implementation

Throws:

java.lang.IllegalArgumentException - if the field is null

toCopy

public ReadableInstant toCopy(long newMillis)

Gets a copy of this instant with different millis.

The returned object will be a new instance of the same implementation type. Only the millis will change, the chronology and time zone are kept. Immutable subclasses may return this if appropriate.

Parameters:

newMillis - the new millis, from 1970-01-01T00:00:00Z

Returns:

a copy of this instant with different millis

toCopy

public ReadableInstant toCopy(Chronology newChronology)

Gets a copy of this instant with a different chronology.

The returned object will be a new instance of the same implementation type. Only the chronology will change, the millis are kept. Immutable subclasses may return this if appropriate.

Parameters:

newChronology - the new chronology

Returns:

a copy of this instant with a different chronology

Throws:

java.lang.IllegalArgumentException - if the chronology is null

toInstant

public Instant toInstant()

Get the value as a simple immutable Instant object.

This can be useful if you don't trust the implementation of the interface to be well-behaved, or to get a guaranteed immutable object.

Returns:

the value as an Instant object

equals

public boolean equals(java.lang.Object readableInstant)

Compares this object with the specified object for equality based on the millisecond instant and the Chronology. All ReadableInstant instances are accepted.

To compare two instants for absolute time (ie. UTC milliseconds ignoring the chronology), use isEqual(ReadableInstant) or compareTo(Object).

Overrides:

equals in class java.lang.Object

Parameters:

readableInstant - a readable instant to check against

Returns:

true if millisecond and chronology are equal, false if not or the instant is null or of an incorrect type

hashCode

public int hashCode()

Gets a hash code for the instant that is compatable with the equals method.

The formula used must be as follows:

int result = 317;
 result = 59 * result + ((int) (getMillis() ^ (getMillis() >>> 32)));
 result = 59 * result + (getChronology() == null ? 0 : getChronology().hashCode());
 return result;

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code as defined above

compareTo

public int compareTo(java.lang.Object readableInstant)

Compares this object with the specified object for ascending millisecond instant order. This ordering is inconsistent with equals, as it ignores the Chronology.

All ReadableInstant instances are accepted.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

readableInstant - a readable instant to check against

Returns:

-1 if this is less, 0 if equal or +1 if greater

Throws:

java.lang.NullPointerException - if the object is null

java.lang.ClassCastException - if the object type is not supported

isAfter

public boolean isAfter(ReadableInstant readableInstant)

Is the millisecond value after the millisecond passed in.

Parameters:

readableInstant - an instant to check against

Returns:

true if the instant is after the instant passed in

Throws:

java.lang.IllegalArgumentException - if the instant is null

isBefore

public boolean isBefore(ReadableInstant readableInstant)

Is the millisecond value before the millisecond passed in.

Parameters:

readableInstant - an instant to check against

Returns:

true if the instant is before the instant passed in

Throws:

java.lang.IllegalArgumentException - if the instant is null

isEqual

public boolean isEqual(ReadableInstant readableInstant)

Is the millisecond value equal to the millisecond passed in.

Parameters:

readableInstant - an instant to check against

Returns:

true if the instant is equal to the instant passed in

Throws:

java.lang.IllegalArgumentException - if the instant is null

toString

public java.lang.String toString()

Get the value as a String in a recognisable ISO8601 format.

The string output is in ISO8601 format to enable the String constructor to correctly parse it.

Overrides:

toString in class java.lang.Object

Returns:

the value as an ISO8601 string