org.pojava.datetime

Class DateTime

java.lang.Object

org.pojava.datetime.DateTime

All Implemented Interfaces:

Serializable, Comparable<DateTime>

public class DateTime
extends Object
implements Serializable, 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 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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
DateTime() Default constructor gives current time to millisecond.
DateTime(IDateTimeConfig config) DateTime with a specified config
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, String tzId) Construct a DateTime from seconds and fractional seconds.
DateTime(long seconds, int nanos, TimeZone tz) Construct a DateTime from seconds and fractional seconds.
DateTime(long millis, String tzId) DateTime constructed from time in milliseconds since epoch.
DateTime(long millis, TimeZone tz) DateTime constructed from time in milliseconds since epoch.
DateTime(String str) DateTime constructed from a string using global defaults.
DateTime(String str, IDateTimeConfig config) DateTime constructed from a string using specified defaults.
DateTime(String str, TimeZone tz) DateTime parsed from a string at a specified time zone
DateTime(String str, TimeZone inputTz, TimeZone outputTz) DateTime parsed from a string at a specified time zone
DateTime(Timestamp ts) DateTime constructed from a Timestamp includes nanos.

Method Summary

Methods

Modifier and Type	Method and Description
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.
static void	assignIntegersToRemainingSlots(IDateTimeConfig config, org.pojava.datetime.DateTime.HasDatepart hasDatepart, org.pojava.datetime.DateTime.DateState dateState)
int	compareTo(DateTime other) Compare two DateTime objects to determine ordering.
IDateTimeConfig	config() Return the global configuration used by DateTime.
boolean	equals(Object dateTime) This compares a DateTime with another DateTime.
int	getNanos() Positive nanosecond offset from Seconds.
long	getSeconds() Whole seconds offset from epoch.
int	hashCode()
static DateTime	parse(String str) Interpret a DateTime from a String using global defaults.
static DateTime	parse(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(String iso8601) Shift this DateTime +/- a Shift offset specified as an ISO 8601 string.
TimeZone	timeZone() Get the TimeZone used for formatted string output
Date	toDate() Get Date/Time as a Java Date object.
long	toMillis() Whole milliseconds offset from epoch.
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.
String	toString(String format) Return a String according to the provided format.
String	toString(String format, Locale locale) Return a String according to the provided format.
String	toString(String format, TimeZone tz) Return a String according to the provided format.
String	toString(String format, TimeZone tz, Locale locale) Return a String according to the provided format.
String	toString(TimeZone tz) Return a String according to the provided format.
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(IDateTimeConfig config)

DateTime with a specified config

DateTime

public DateTime(long millis)

DateTime constructed from time in milliseconds since epoch.

Parameters:

millis - time since epoch

DateTime

public DateTime(long millis,
        IDateTimeConfig config)

DateTime constructed from time in milliseconds since epoch.

Parameters:

millis - time since epoch

config - configuration defaults

DateTime

public DateTime(long millis,
        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,
        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,
        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,
        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(String str)

DateTime constructed from a string using global defaults.

Parameters:

str - String holding date to parse

DateTime

public DateTime(String str,
        IDateTimeConfig config)

DateTime constructed from a string using specified defaults.

Parameters:

str - String to parse

config - Custom configuration options

DateTime

public DateTime(String str,
        TimeZone tz)

DateTime parsed from a string at a specified time zone

Parameters:

str - Date string to parse

tz - Time zone used for both parsing input and formatting output

DateTime

public DateTime(String str,
        TimeZone inputTz,
        TimeZone outputTz)

DateTime parsed from a string at a specified time zone

Parameters:

str - Date string to parse

inputTz - Time Zone of the date being parsed

outputTz - Time Zone under which toString will format dates

DateTime

public DateTime(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 Comparable<DateTime>

Parameters:

other - DateTime to compare to this

Returns:

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

toTimestamp

public Timestamp toTimestamp()

Get a timestamp useful for JDBC

Returns:

This DateTime as a Timestamp object.

toDate

public Date toDate()

Get Date/Time as a Java Date object.

Returns:

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

timeZone

public TimeZone timeZone()

Get the TimeZone used for formatted string output

Returns:

this TimeZone.

toString

public 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 Object

Returns:

DateTime using the default config options

toString

public String toString(String format)

Return a String according to the provided format.

Parameters:

format - Date format specifier

Returns:

A formatted string version of the current DateTime.

toString

public String toString(String format,
              TimeZone tz)

Return a String according to the provided format.

Parameters:

format - Date format specifier

tz - Show formatted date & time at the given TimeZone

Returns:

A formatted string version of the current DateTime.

toString

public String toString(String format,
              Locale locale)

Return a String according to the provided format.

Parameters:

format - Date format specifier

locale - Show formatted date & time at the given TimeZone

Returns:

A formatted string version of the current DateTime.

toString

public String toString(TimeZone tz)

Return a String according to the provided format.

Parameters:

tz - Show formatted date & time at the given TimeZone

Returns:

A formatted string version of the current DateTime.

toString

public String toString(String format,
              TimeZone tz,
              Locale locale)

Return a String according to the provided format.

Parameters:

format - Date format specifier

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.

add

public DateTime add(Duration dur)

Add a fixed duration of time

Parameters:

dur - Duration

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 - Duration in 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 - CalendarUnit (MINUTE, DAY, WEEK, MONTH, etc)

qty - May be positive or negative.

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 variables such as daylight saving or day-of-month offsets.

Parameters:

calUnit - CalendarUnit (MINUTE, DAY, WEEK, MONTH, etc)

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(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(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.

assignIntegersToRemainingSlots

public static void assignIntegersToRemainingSlots(IDateTimeConfig config,
                                  org.pojava.datetime.DateTime.HasDatepart hasDatepart,
                                  org.pojava.datetime.DateTime.DateState dateState)

parse

public static DateTime parse(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(Object dateTime)

This compares a DateTime with another DateTime.

Overrides:

equals in class 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 Object

config

public IDateTimeConfig config()

Return the global configuration used by DateTime.

Returns:

the global DateTimeConfig object used by DateTime.