Package com.google.api.client.util

Class DateTime

java.lang.Object

com.google.api.client.util.DateTime

All Implemented Interfaces:

java.io.Serializable

public final class DateTime
extends java.lang.Object
implements java.io.Serializable

Immutable representation of a date with an optional time and an optional time zone based on RFC 3339.

Implementation is immutable and therefore thread-safe.

Since:

1.0

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
private boolean	dateOnly	Specifies whether this is a date-only value.
private static java.util.TimeZone	GMT
private static java.util.regex.Pattern	RFC3339_PATTERN	Regular expression for parsing RFC3339 date/times.
private static long	serialVersionUID
private int	tzShift	Time zone shift from UTC in minutes or 0 for date-only value.
private long	value	Date/time value expressed as the number of ms since the Unix epoch.

Constructor Summary

Constructors

Constructor	Description
DateTime(boolean dateOnly, long value, java.lang.Integer tzShift)	Instantiates DateTime, which may represent a date-only value, from the number of milliseconds since the Unix epoch, and a shift from UTC in minutes.
DateTime(long value)	Instantiates DateTime from the number of milliseconds since the Unix epoch.
DateTime(long value, int tzShift)	Instantiates DateTime from the number of milliseconds since the Unix epoch, and a shift from UTC in minutes.
DateTime(java.lang.String value)	Instantiates DateTime from an RFC 3339 date/time value.
DateTime(java.util.Date value)	Instantiates DateTime from a Date.
DateTime(java.util.Date date, java.util.TimeZone zone)	Instantiates DateTime from a Date and TimeZone.

Method Summary

Modifier and Type	Method	Description
private static void	appendInt(java.lang.StringBuilder sb, int num, int numDigits)	Appends a zero-padded number to a string builder.
boolean	equals(java.lang.Object o)
int	getTimeZoneShift()	Returns the time zone shift from UTC in minutes or 0 for date-only value.
long	getValue()	Returns the date/time value expressed as the number of milliseconds since the Unix epoch.
int	hashCode()
boolean	isDateOnly()	Returns whether this is a date-only value.
static DateTime	parseRfc3339(java.lang.String str)	Parses an RFC3339 date/time value.
java.lang.String	toString()
java.lang.String	toStringRfc3339()	Formats the value as an RFC 3339 date/time string.

Methods inherited from class java.lang.Object

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

Field Detail

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

GMT

private static final java.util.TimeZone GMT

RFC3339_PATTERN

private static final java.util.regex.Pattern RFC3339_PATTERN

Regular expression for parsing RFC3339 date/times.

value

private final long value

Date/time value expressed as the number of ms since the Unix epoch.

If the time zone is specified, this value is normalized to UTC, so to format this date/time value, the time zone shift has to be applied.

dateOnly

private final boolean dateOnly

Specifies whether this is a date-only value.

tzShift

private final int tzShift

Time zone shift from UTC in minutes or 0 for date-only value.

Constructor Detail

DateTime

public DateTime(java.util.Date date,
                java.util.TimeZone zone)

Instantiates DateTime from a Date and TimeZone.

Parameters:

date - date and time

zone - time zone; if null, it is interpreted as TimeZone.getDefault().

DateTime

public DateTime(long value)

Instantiates DateTime from the number of milliseconds since the Unix epoch.

The time zone is interpreted as TimeZone.getDefault(), which may vary with implementation.

Parameters:

value - number of milliseconds since the Unix epoch (January 1, 1970, 00:00:00 GMT)

DateTime

public DateTime(java.util.Date value)

Instantiates DateTime from a Date.

The time zone is interpreted as TimeZone.getDefault(), which may vary with implementation.

Parameters:

value - date and time

DateTime

public DateTime(long value,
                int tzShift)

Instantiates DateTime from the number of milliseconds since the Unix epoch, and a shift from UTC in minutes.

Parameters:

value - number of milliseconds since the Unix epoch (January 1, 1970, 00:00:00 GMT)

tzShift - time zone, represented by the number of minutes off of UTC.

DateTime

public DateTime(boolean dateOnly,
                long value,
                java.lang.Integer tzShift)

Instantiates DateTime, which may represent a date-only value, from the number of milliseconds since the Unix epoch, and a shift from UTC in minutes.

Parameters:

dateOnly - specifies if this should represent a date-only value

value - number of milliseconds since the Unix epoch (January 1, 1970, 00:00:00 GMT)

tzShift - time zone, represented by the number of minutes off of UTC, or null for TimeZone.getDefault().

DateTime

public DateTime(java.lang.String value)

Instantiates DateTime from an RFC 3339 date/time value.

Upgrade warning: in prior version 1.17, this method required milliseconds to be exactly 3 digits (if included), and did not throw an exception for all types of invalid input values, but starting in version 1.18, the parsing done by this method has become more strict to enforce that only valid RFC3339 strings are entered, and if not, it throws a NumberFormatException. Also, in accordance with the RFC3339 standard, any number of milliseconds digits is now allowed.

Parameters:

value - an RFC 3339 date/time value.

Since:

1.11

Method Detail

getValue

public long getValue()

Returns the date/time value expressed as the number of milliseconds since the Unix epoch.

If the time zone is specified, this value is normalized to UTC, so to format this date/time value, the time zone shift has to be applied.

Since:

1.5

isDateOnly

public boolean isDateOnly()

Returns whether this is a date-only value.

Since:

1.5

getTimeZoneShift

public int getTimeZoneShift()

Returns the time zone shift from UTC in minutes or 0 for date-only value.

Since:

1.5

toStringRfc3339

public java.lang.String toStringRfc3339()

Formats the value as an RFC 3339 date/time string.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

A check is added that the time zone is the same. If you ONLY want to check equality of time value, check equality on the getValue().

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

parseRfc3339

public static DateTime parseRfc3339(java.lang.String str)
                             throws java.lang.NumberFormatException

Parses an RFC3339 date/time value.

Upgrade warning: in prior version 1.17, this method required milliseconds to be exactly 3 digits (if included), and did not throw an exception for all types of invalid input values, but starting in version 1.18, the parsing done by this method has become more strict to enforce that only valid RFC3339 strings are entered, and if not, it throws a NumberFormatException. Also, in accordance with the RFC3339 standard, any number of milliseconds digits is now allowed.

For the date-only case, the time zone is ignored and the hourOfDay, minute, second, and millisecond parameters are set to zero.

Parameters:

str - Date/time string in RFC3339 format

Throws:

java.lang.NumberFormatException - if str doesn't match the RFC3339 standard format; an exception is thrown if str doesn't match RFC3339_REGEX or if it contains a time zone shift but no time.

appendInt

private static void appendInt(java.lang.StringBuilder sb,
                              int num,
                              int numDigits)

Appends a zero-padded number to a string builder.