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
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
DateTime.Rfc3339ParseResult
Result of parsing an RFC 3339 string.static class
DateTime.SecondsAndNanos
A timestamp represented as the number of seconds and nanoseconds since Epoch.
-
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
private static java.lang.String
RFC3339_REGEX
Regular expression for parsing RFC3339 date/times.private static long
serialVersionUID
private int
tzShift
Time zone shift from UTC in minutes or0
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)
InstantiatesDateTime
, 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)
InstantiatesDateTime
from the number of milliseconds since the Unix epoch.DateTime(long value, int tzShift)
InstantiatesDateTime
from the number of milliseconds since the Unix epoch, and a shift from UTC in minutes.DateTime(java.lang.String value)
DateTime(java.util.Date value)
InstantiatesDateTime
from aDate
.DateTime(java.util.Date date, java.util.TimeZone zone)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods 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 or0
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.static DateTime.SecondsAndNanos
parseRfc3339ToSecondsAndNanos(java.lang.String str)
Parses an RFC3339 timestamp to a pair of seconds and nanoseconds since Unix Epoch.private static DateTime.Rfc3339ParseResult
parseRfc3339WithNanoSeconds(java.lang.String str)
java.lang.String
toString()
java.lang.String
toStringRfc3339()
Formats the value as an RFC 3339 date/time string.
-
-
-
Field Detail
-
serialVersionUID
private static final long serialVersionUID
- See Also:
- Constant Field Values
-
GMT
private static final java.util.TimeZone GMT
-
RFC3339_REGEX
private static final java.lang.String RFC3339_REGEX
Regular expression for parsing RFC3339 date/times.- See Also:
- Constant Field Values
-
RFC3339_PATTERN
private static final java.util.regex.Pattern RFC3339_PATTERN
-
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 or0
for date-only value.
-
-
Constructor Detail
-
DateTime
public DateTime(java.util.Date date, java.util.TimeZone zone)
- Parameters:
date
- date and timezone
- time zone; ifnull
, it is interpreted asTimeZone.getDefault()
.
-
DateTime
public DateTime(long value)
InstantiatesDateTime
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)
InstantiatesDateTime
from aDate
.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)
InstantiatesDateTime
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)
InstantiatesDateTime
, 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 valuevalue
- 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, ornull
forTimeZone.getDefault()
.
-
DateTime
public DateTime(java.lang.String value)
InstantiatesDateTime
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 or0
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 classjava.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 classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
parseRfc3339
public static DateTime parseRfc3339(java.lang.String str)
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.Any time information beyond millisecond precision is truncated.
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
- ifstr
doesn't match the RFC3339 standard format; an exception is thrown ifstr
doesn't matchRFC3339_REGEX
or if it contains a time zone shift but no time.
-
parseRfc3339ToSecondsAndNanos
public static DateTime.SecondsAndNanos parseRfc3339ToSecondsAndNanos(java.lang.String str)
Parses an RFC3339 timestamp to a pair of seconds and nanoseconds since Unix Epoch.- Parameters:
str
- Date/time string in RFC3339 format- Throws:
java.lang.IllegalArgumentException
- ifstr
doesn't match the RFC3339 standard format; an exception is thrown ifstr
doesn't matchRFC3339_REGEX
or if it contains a time zone shift but no time.
-
parseRfc3339WithNanoSeconds
private static DateTime.Rfc3339ParseResult parseRfc3339WithNanoSeconds(java.lang.String str) throws java.lang.NumberFormatException
- Throws:
java.lang.NumberFormatException
-
appendInt
private static void appendInt(java.lang.StringBuilder sb, int num, int numDigits)
Appends a zero-padded number to a string builder.
-
-