com.programix.time
Class DateTime

java.lang.Object
  com.programix.time.DateTime

All Implemented Interfaces:

Serializable, Cloneable, Comparable<DateTime>

public final class DateTime
extends Object
implements Comparable<DateTime>, Serializable, Cloneable

Immutable encapsulation of a date and time as the number of milliseconds that has elapsed since January 1, 1970 00:00:00.000 in the UTC timezone. Although similar to java.util.Date, instances of this class are immutable.

DateTools has handy utilities for formatting and parsing DateTime instances to and from more human-readable Strings.

PlainDate v. DateTime
The DateTime class has some of the same uses as a PlainDate but DateTime represents a moment in time as the number of milliseconds since January 1, 1970 began in UTC (see the "Time Information" section in DateTools for links to all kinds of information about dates and times and time zones). To interpret a DateTime as a year, month, and day, a time zone must be supplied to properly calculate what day it is (even what month or what year it is!). For example, consider it to be 12:30AM on January 1, 2007 [2007-01-01 00:30] in New York City. That same moment in time is interpreted as 11:30PM on December 31, 2006 [2006-12-31 11:30] in Minneapolis, Minnesota. That's a different day, a different month, and even a different year! Clearly the time zone used to interpret a DateTime is critical.

The PlainDate class has some of the same uses as a DateTime but PlainDate represents a year, month, and day without regard to any time zone. Also, PlainDate does not contain any time of day information (like hours, minutes, seconds, etc.).

This class uses the Immutability pattern. That is, instances are not changeable after construction.

Author:

Paul Hyde

See Also:

PlainDate, DateTimeRange, PlainDateRange, DateTools, Serialized Form

Constructor Summary

DateTime()
Uses DateTools.getTime() as its source for the milliseconds (which may be different that System.currentTimeMillis()).

DateTime(Date utilDate)
Copies the time currently in the java.util.Date object via getTime().

DateTime(long time)
Primary constructor, based on the number of ms since Jan 1, 1970 UTC.

Method Summary

boolean	after(DateTime otherDateTime) Returns true if the this instance's time comes after the time passed as a parameter.
boolean	after(long otherTime) Returns true if the this instance's time comes after the time passed as a parameter.
boolean	afterOrEqualTo(DateTime otherDateTime) Returns true if the this instance's time comes after or is the same as the time passed as a parameter.
boolean	afterOrEqualTo(long otherTime) Returns true if the this instance's time comes after or is the same as the time passed as a parameter.
boolean	before(DateTime otherDateTime) Returns true if the this instance's time comes before the time passed as a parameter.
boolean	before(long otherTime) Returns true if the this instance's time comes before the time passed as a parameter.
boolean	beforeOrEqualTo(DateTime otherDateTime) Returns true if the this instance's time comes before or is the same as the time passed as a parameter.
boolean	beforeOrEqualTo(long otherTime) Returns true if the this instance's time comes before or is the same as the time passed as a parameter.
Object	clone() Simply returns a reference to this instance.
int	compareTo(DateTime otherDateTime) Returns -1 if this instance's time comes before the passed time, 0 if they are the same, and -1 if the passed time comes after.
int	compareTo(long otherTime) Returns -1 if this instance's time comes before the passed time, 0 if they are the same, and -1 if the passed time comes after.
boolean	equals(DateTime otherDateTime) Returns true if this instance's time matches the passed time exactly to the millisecond.
boolean	equals(Object obj) Returns true if this instance's time matches the passed time exactly to the millisecond.
Date	getAsSqlDate() Returns a new java.sql.Date object built from the time stored in this instance.
Timestamp	getAsSqlTimestamp() Returns a new java.sql.Timestamp object built from the time stored in this instance.
Date	getAsUtilDate() Returns a new java.util.Date object built from the time stored in this instance.
long	getTime() Returns the number of milliseconds since Jan 1, 1970 in the UTC timezone.
int	hashCode()
PlainDate	toPlainDate(TimeZone tz) Returns a PlainDate derived from the time stored in this instance interpreted in the specified time zone.
PlainDate	toPlainDateLocal() Returns a PlainDate derived from the time stored in this instance interpreted in the local VM time zone.
PlainDate	toPlainDateUTC() Returns a PlainDate derived from the time stored in this instance interpreted in the UTC time zone.
String	toString() Returns the time formatted for the UTC timezone as yyyy-mm-dd hh:mm:ss.fff UTC.

Methods inherited from class java.lang.Object

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

Constructor Detail

DateTime

public DateTime(long time)

Primary constructor, based on the number of ms since Jan 1, 1970 UTC.

Parameters:

time - number of milliseconds since Jan 1, 1970 in the UTC timezone.

DateTime

public DateTime(Date utilDate)
         throws IllegalArgumentException

Copies the time currently in the java.util.Date object via getTime(). Note that the java.sql types of java.sql.Timestamp, java.sql.Date, and java.sql.Time are all subclasses of java.util.Date.

Throws:

IllegalArgumentException - if null if passed.

DateTime

public DateTime()

Uses DateTools.getTime() as its source for the milliseconds (which may be different that System.currentTimeMillis()). If you want to be sure that System.currentTimeMillis() is being used as the source of milliseconds, then call the other DateTime(long) constructor passing in the long value yourself.

Method Detail

getTime

public long getTime()

Returns the number of milliseconds since Jan 1, 1970 in the UTC timezone.

getAsUtilDate

public Date getAsUtilDate()

Returns a new java.util.Date object built from the time stored in this instance.

getAsSqlDate

public Date getAsSqlDate()

Returns a new java.sql.Date object built from the time stored in this instance.

getAsSqlTimestamp

public Timestamp getAsSqlTimestamp()

Returns a new java.sql.Timestamp object built from the time stored in this instance.

toPlainDate

public PlainDate toPlainDate(TimeZone tz)

Returns a PlainDate derived from the time stored in this instance interpreted in the specified time zone.

toPlainDateLocal

public PlainDate toPlainDateLocal()

Returns a PlainDate derived from the time stored in this instance interpreted in the local VM time zone.

toPlainDateUTC

public PlainDate toPlainDateUTC()

Returns a PlainDate derived from the time stored in this instance interpreted in the UTC time zone.

before

public boolean before(DateTime otherDateTime)
               throws IllegalArgumentException

Returns true if the this instance's time comes before the time passed as a parameter. If they are equal, false is returned.

Throws:

IllegalArgumentException - if null if passed.

See Also:

before(long)

before

public boolean before(long otherTime)

Returns true if the this instance's time comes before the time passed as a parameter. If they are equal, false is returned.

See Also:

before(DateTime)

beforeOrEqualTo

public boolean beforeOrEqualTo(DateTime otherDateTime)
                        throws IllegalArgumentException

Returns true if the this instance's time comes before or is the same as the time passed as a parameter.

Throws:

IllegalArgumentException - if null if passed.

beforeOrEqualTo

public boolean beforeOrEqualTo(long otherTime)

Returns true if the this instance's time comes before or is the same as the time passed as a parameter.

See Also:

before(DateTime)

after

public boolean after(DateTime otherDateTime)
              throws IllegalArgumentException

Returns true if the this instance's time comes after the time passed as a parameter. If they are equal, false is returned.

Throws:

IllegalArgumentException - if null if passed.

See Also:

after(long)

after

public boolean after(long otherTime)

Returns true if the this instance's time comes after the time passed as a parameter. If they are equal, false is returned.

See Also:

after(DateTime)

afterOrEqualTo

public boolean afterOrEqualTo(DateTime otherDateTime)
                       throws IllegalArgumentException

Returns true if the this instance's time comes after or is the same as the time passed as a parameter.

Throws:

IllegalArgumentException - if null if passed.

afterOrEqualTo

public boolean afterOrEqualTo(long otherTime)

Returns true if the this instance's time comes after or is the same as the time passed as a parameter.

compareTo

public int compareTo(DateTime otherDateTime)
              throws IllegalArgumentException

Returns -1 if this instance's time comes before the passed time, 0 if they are the same, and -1 if the passed time comes after.

Specified by:

compareTo in interface Comparable<DateTime>

Throws:

IllegalArgumentException - if null if passed.

compareTo

public int compareTo(long otherTime)

Returns -1 if this instance's time comes before the passed time, 0 if they are the same, and -1 if the passed time comes after.

equals

public boolean equals(DateTime otherDateTime)

Returns true if this instance's time matches the passed time exactly to the millisecond. If null is passed, false is returned.

equals

public boolean equals(Object obj)

Returns true if this instance's time matches the passed time exactly to the millisecond. If null is passed in, false is returned. If a type other than DateTime is passed in, false is returned (ClassCastException is not thrown).

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Returns the time formatted for the UTC timezone as yyyy-mm-dd hh:mm:ss.fff UTC.

Overrides:

toString in class Object

clone

public Object clone()

Simply returns a reference to this instance. No need to actually clone since objects of this type are immutable.

Overrides:

clone in class Object