org.pojava.datetime
Class DateTime

java.lang.Object
  org.pojava.datetime.DateTime

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<DateTime>

public class DateTime
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<DateTime>

DateTime provides an immutable representation of Date and Time to the nearest nanosecond. You can access DateTime properties either in milliseconds or in seconds and nanoseconds. Both the seconds and milliseconds values can be understood as being truncated to their respective precisions. Nanos holds the fractional portion of a second in the range 0-999999999. Note that whether seconds is positive or negative, the internal values will be adjusted if necessary to support a positive value for nanos.

You may think of a DateTime object as a fixed offset of System time measured from the Unix epoch in non-leap milliseconds or non-leap seconds and nanoseconds. Leap years are calculated according to the Gregorian Calendar, matching the same interpretation as the java.util.Date object (every 4th year is a leap year, except for years divisible by 100 but not divisible by 400). The times are stored according to the UTC (aka GMT) time zone, and a TimeZone object is referenced to translate to a local time zone.

DateTime includes a robust parser for interpreting date and time from a String. It parses a date and time using heuristics rather than comparing against preset formats, so it is point-and-shoot simple. The following, for example, are interpreted the same:

• 3:21pm on January 26, 1969
• 26-Jan-1969 03:21 PM
• 1/26/69 15:21
• 1969.01.26 15.21
• el 26 de enero de 1969 15.21

Some notes on the date interpretations:

All dates are interpreted in your local time zone, unless a time zone is specified in the String. Time zones are configurable in the DateTimeConfig object, so you can determine for your own application whether CST, for example, would adjust to Central Standard Time or Chinese Standard Time.

A two-digit year will assume up to 80 years in the past and 20 years in the future. It is prudent in many cases to follow this with a check based on whether you know the date to represent a past or future date. If you know you parsed a birthday, you can compare with today's date and subtract 100 yrs if needed (references to birthdays 20 years in the future are rare). Similarly, if you're dealing with an annuity date, you can add 100 years if the parsed date occurred in the past.

If you're parsing European dates expecting DD/MM/YYYY instead of MM/DD/YYYY, then you can alter the global DateTimeConfig setting by first calling, " DateTimeConfig.globalEuropeanDateFormat();".

Author:

John Pile

See Also:

Serialized Form

Field Summary

protected IDateTimeConfig	config Config contains info specific to zoning and formatting.
protected Duration	systemDur System time is a lazy calculation of milliseconds from Unix epoch 1970-01-01 00:00:00, assuming no leap seconds and a leap year every year evenly divisible by 4, except for years divisible by 100 but not divisible by 400.

Constructor Summary

DateTime()
Default constructor gives current time to millisecond.

DateTime(long millis)
DateTime constructed from time in milliseconds since epoch.

DateTime(long millis, IDateTimeConfig config)
DateTime constructed from time in milliseconds since epoch.

DateTime(long seconds, int nanos)
Construct a DateTime from seconds and fractional seconds.

DateTime(long seconds, int nanos, IDateTimeConfig config)
Construct a DateTime from seconds and fractional seconds.

DateTime(long seconds, int nanos, java.lang.String tzId)
Construct a DateTime from seconds and fractional seconds.

DateTime(long seconds, int nanos, java.util.TimeZone tz)
Construct a DateTime from seconds and fractional seconds.

DateTime(long millis, java.lang.String tzId)
DateTime constructed from time in milliseconds since epoch.

DateTime(long millis, java.util.TimeZone tz)
DateTime constructed from time in milliseconds since epoch.

DateTime(java.lang.String str)
DateTime constructed from a string using global defaults.

DateTime(java.lang.String str, IDateTimeConfig config)
DateTime constructed from a string using global defaults.

DateTime(java.sql.Timestamp ts)
DateTime constructed from a Timestamp includes nanos.

Method Summary

DateTime	add(CalendarUnit calUnit, int qty) Add +/- a block of time to a date in it's OutputTimeZone.
DateTime	add(Duration dur) Add a fixed duration of time
DateTime	add(long milliseconds) Add a fixed duration in milliseconds.
int	compareTo(DateTime other) Compare two DateTime objects to determine ordering.
IDateTimeConfig	config() Return the global configuration used by DateTime.
boolean	equals(java.lang.Object dateTime) This compares a DateTime with another DateTime.
int	getNanos() Positive nanosecond offset from Seconds.
long	getSeconds() Whole seconds offset from epoch.
java.lang.String	getTimeZoneId() Deprecated. After parse, only config determines output.
int	hashCode()
static DateTime	parse(java.lang.String str) Interpret a DateTime from a String using global defaults.
static DateTime	parse(java.lang.String str, IDateTimeConfig config) Interpret a DateTime from a String.
DateTime	shift(CalendarUnit calUnit, int qty) Add increments of any calendar time unit from a nanosecond to a century.
DateTime	shift(Shift shift) Shift this DateTime +/- a Shift offset.
DateTime	shift(java.lang.String iso8601) Shift this DateTime +/- a Shift offset specified as an ISO 8601 string.
java.util.TimeZone	timeZone() Get the TimeZone
java.util.Date	toDate() Get Date/Time as a Java Date object.
java.lang.String	toLocalString() Deprecated.
java.lang.String	toLocalString(java.lang.String format) Deprecated.
long	toMillis() Whole milliseconds offset from epoch.
java.lang.String	toString() By default, the toString method gives a sortable ISO 8601 date and time to nearest second in the same time zone as the system.
java.lang.String	toString(java.lang.String format) Return a String according to the provided format.
java.lang.String	toString(java.lang.String format, java.util.TimeZone tz) Return a String according to the provided format.
java.lang.String	toString(java.lang.String format, java.util.TimeZone tz, java.util.Locale locale) Return a String according to the provided format.
java.sql.Timestamp	toTimestamp() Get a timestamp useful for JDBC
DateTime	truncate(CalendarUnit unit) Truncate DateTime down to its nearest time unit as a time.
int	weekday() Return numeric day of week, usually Sun=1, Mon=2, ...

Methods inherited from class java.lang.Object

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

Field Detail

config

protected IDateTimeConfig config

Config contains info specific to zoning and formatting.

systemDur

protected Duration systemDur

System time is a lazy calculation of milliseconds from Unix epoch 1970-01-01 00:00:00, assuming no leap seconds and a leap year every year evenly divisible by 4, except for years divisible by 100 but not divisible by 400.

Constructor Detail

DateTime

public DateTime()

Default constructor gives current time to millisecond.

DateTime

public DateTime(long millis)

DateTime constructed from time in milliseconds since epoch.

Parameters:

millis - time

DateTime

public DateTime(long millis,
                IDateTimeConfig config)

DateTime constructed from time in milliseconds since epoch.

Parameters:

millis -

config - time

DateTime

public DateTime(long millis,
                java.util.TimeZone tz)

DateTime constructed from time in milliseconds since epoch.

Parameters:

millis - Number of milliseconds since epoch

tz - Override the output Time Zone

DateTime

public DateTime(long millis,
                java.lang.String tzId)

DateTime constructed from time in milliseconds since epoch.

Parameters:

millis - Number of milliseconds since epoch

tzId - Override the output time zone

DateTime

public DateTime(long seconds,
                int nanos)

Construct a DateTime from seconds and fractional seconds.

Parameters:

seconds - Number of seconds since epoch (typically 1970-01-01)

nanos - Nanosecond offset in range +/- 999999999

DateTime

public DateTime(long seconds,
                int nanos,
                java.util.TimeZone tz)

Construct a DateTime from seconds and fractional seconds.

Parameters:

seconds - Number of seconds since epoch (typically 1970-01-01)

nanos - Nanosecond offset in range +/- 999999999

tz - Override the output time zone

DateTime

public DateTime(long seconds,
                int nanos,
                java.lang.String tzId)

Construct a DateTime from seconds and fractional seconds.

Parameters:

seconds - Number of seconds since epoch (typically 1970-01-01)

nanos - Nanosecond offset in range +/- 999999999

tzId - Override the output time zone

DateTime

public DateTime(long seconds,
                int nanos,
                IDateTimeConfig config)

Construct a DateTime from seconds and fractional seconds.

Parameters:

seconds - Number of seconds since epoch (typically 1970-01-01)

nanos - Nanosecond offset in range +/- 999999999

config - Provide custom configuration options

DateTime

public DateTime(java.lang.String str)

DateTime constructed from a string using global defaults.

Parameters:

str -

DateTime

public DateTime(java.lang.String str,
                IDateTimeConfig config)

DateTime constructed from a string using global defaults.

Parameters:

str - String to parse

config - Custom configuration options

DateTime

public DateTime(java.sql.Timestamp ts)

DateTime constructed from a Timestamp includes nanos.

Parameters:

ts - Timestamp

Method Detail

compareTo

public int compareTo(DateTime other)

Compare two DateTime objects to determine ordering.

Specified by:

compareTo in interface java.lang.Comparable<DateTime>

Parameters:

other - DateTime to compare to this

Returns:

-1, 0, or 1 based on comparison to another DateTime.

toTimestamp

public java.sql.Timestamp toTimestamp()

Get a timestamp useful for JDBC

Returns:

This DateTime as a Timestamp object.

toDate

public java.util.Date toDate()

Get Date/Time as a Java Date object.

Returns:

this DateTime truncated and converted to a java.util.Date object.

timeZone

public java.util.TimeZone timeZone()

Get the TimeZone

Returns:

this TimeZone.

toString

public java.lang.String toString()

By default, the toString method gives a sortable ISO 8601 date and time to nearest second in the same time zone as the system. The default format can be redefined in DateTimeConfig.

Overrides:

toString in class java.lang.Object

Returns:

DateTime using the default config options

toString

public java.lang.String toString(java.lang.String format)

Return a String according to the provided format.

Parameters:

format -

Returns:

A formatted string version of the current DateTime.

toString

public java.lang.String toString(java.lang.String format,
                                 java.util.TimeZone tz)

Return a String according to the provided format.

Parameters:

format -

tz - Show formatted date & time at the given TimeZone

Returns:

A formatted string version of the current DateTime.

toString

public java.lang.String toString(java.lang.String format,
                                 java.util.TimeZone tz,
                                 java.util.Locale locale)

Return a String according to the provided format.

Parameters:

format -

tz - Show formatted date & time at the given TimeZone

locale - Display date words like month or day of week in a given language.

Returns:

A formatted string version of the current DateTime.

toLocalString

public java.lang.String toLocalString()

Deprecated.

The toLocalString method provides a sortable ISO 8601 date and time to the nearest second, but is rendered from the perspective of the time zone ascribed to the DateTime object, regardless of the system's time zone.

Returns:

A string version of the this DateTime specified in local time.

toLocalString

public java.lang.String toLocalString(java.lang.String format)

Deprecated.

The toLocalString method provides a sortable ISO 8601 date and time to the nearest second, but is rendered from the perspective of the time zone ascribed to the DateTime object, regardless of the system's time zone.

Parameters:

format -

Returns:

A string version of the this DateTime specified in local time.

add

public DateTime add(Duration dur)

Add a fixed duration of time

Parameters:

dur -

Returns:

Newly calculated DateTime object.

add

public DateTime add(long milliseconds)

Add a fixed duration in milliseconds. The Duration object provides fixed multipliers such as SECOND or HOUR.

Parameters:

milliseconds -

Returns:

Newly calculated DateTime object.

add

public DateTime add(CalendarUnit calUnit,
                    int qty)

Add +/- a block of time to a date in it's OutputTimeZone.

Parameters:

calUnit -

qty -

Returns:

recalculated DateTime

shift

public DateTime shift(CalendarUnit calUnit,
                      int qty)

Add increments of any calendar time unit from a nanosecond to a century. This is different from a Duration in that it will make adjustments to preserve non-linear values such as daylight saving or day-of-month offsets.

Parameters:

calUnit -

qty - May be positive or negative.

Returns:

Newly calculated DateTime object.

shift

public DateTime shift(Shift shift)

Shift this DateTime +/- a Shift offset.

Parameters:

shift - a pre-defined shift of various calendar time increments.

Returns:

a new DateTime offset by the values specified.

shift

public DateTime shift(java.lang.String iso8601)

Shift this DateTime +/- a Shift offset specified as an ISO 8601 string.

Parameters:

iso8601 - A string of format "P[#Y][#M][#D][T[#H][#M][#S[.#]]" holding a list of offsets.

Returns:

a new DateTime shifted by the specified amounts.

weekday

public int weekday()

Return numeric day of week, usually Sun=1, Mon=2, ... , Sat=7;

Returns:

Numeric day of week, usually Sun=1, Mon=2, ... , Sat=7. See DateTimeConfig.

parse

public static DateTime parse(java.lang.String str)

Interpret a DateTime from a String using global defaults.

Parameters:

str - Date/Time string to be parsed.

Returns:

New DateTime interpreted from string.

parse

public static DateTime parse(java.lang.String str,
                             IDateTimeConfig config)

Interpret a DateTime from a String.

Parameters:

str - Date/Time string to be parsed.

config - Configuration parameters governing parsing and presentation.

Returns:

New DateTime interpreted from string according to alternate rules.

truncate

public DateTime truncate(CalendarUnit unit)

Truncate DateTime down to its nearest time unit as a time. CalendarUnit.(WEEK|DAY|HOUR|MINUTE|SECOND|MILLISECOND)

Parameters:

unit - Unit of time to which new DateTime will be truncated.

Returns:

A newly calculated DateTime.

getSeconds

public long getSeconds()

Whole seconds offset from epoch.

Returns:

Whole seconds offset from epoch (1970-01-01 00:00:00).

toMillis

public long toMillis()

Whole milliseconds offset from epoch.

Returns:

Milliseconds offset from epoch (1970-01-01 00:00:00).

getNanos

public int getNanos()

Positive nanosecond offset from Seconds.

Returns:

Fractional second in nanoseconds for the given time.

equals

public boolean equals(java.lang.Object dateTime)

This compares a DateTime with another DateTime.

Overrides:

equals in class java.lang.Object

Parameters:

dateTime - DateTime to which this DateTime will be compared.

Returns:

True if DateTime values represent the same point in time.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

config

public IDateTimeConfig config()

Return the global configuration used by DateTime.

Returns:

the global DateTimeConfig object used by DateTime.

getTimeZoneId

public java.lang.String getTimeZoneId()

Deprecated. After parse, only config determines output.

The TimeZoneId tells what time zone the toString output will present.

Returns:

ID of this DateTime object's original time zone.