Java Time

Internal

• Java
• Time

java.util.Date

The timestamp contained by the Date() instances, as well as the timestamp returned by System.currentTimeMillis() represent an UTC timestamp - they do not have time zone and daylight saving time offsets applied.

Time Zone

The JVM obtains the default time zone from the system. For more details, see time zone. If JVM fails to identify the time zone set externally, it defaults to GMT.

The default time zone in the JVM can be obtained by the Java programs with the following API:

TimeZone dt = TimeZone.getDefault();

A TimeZone instance for a specific time zone can be built by specifying a time zone identifier as String. The "GMT-0800" time one can be built with:

TimeZone tz = TimeZone.getTimeZone("GMT-0800");
TimeZone tz2 = TimeZone.getTimeZone("GMT-08:00");

The timezone instance can be queried for its standard name ("Eastern Standard Time") and ID ("America/New_York").

The UTC TimeZone'" can be obtained with:

TimeZone tz = TimeZone.getTimeZone("UTC");

"UTC" exists in the 'aliases' map of the ZoneInfoFile.

Raw Time Zone Offset

We can get the amount of milliseconds to apply to UTC to get the standard time in a certain time zone (the standard time offset) with TimeZone.getRawOffset().

This value is not affected by daylight saving time.

TimeZone tz = ...
tz.getRawOffset()

Daylight Saving Time Offset

We can get the amount of time to be added to local standard time to get local wall clock time correctly adjusted for daylight time saving.

TimeZone tz = ...
tz.getDSTSavings();

The method implementation checks for whether the daylight savings time is in effect and returns 1 hour or 0:

public int getDSTSavings() {
    if (useDaylightTime()) {
        return 3600000;
    }
    return 0;
}

Figuring Out Whether Daylight Saving is in Effect for a Certain Date

Date d = ...
inDaylightTime(d); 

Figuring the Time Offset of a Certain Time Zone on a Certain Date

Given a TimeZone instance, we can get the time offset to UTC at a certain date (specified as a UTC timestamp). The date is important because the daylight savings may or may not be in effect, and that influences the effective offset:

TimeZone tz = ...
Date date = new Date()
tz.getOffset(date.getTime());

Time Zone and DateFormat

DateFormat.parse()

DateFormat.parse() returns a Date instance whose getTime() is always an UTC value, regardless of whether a time offset was specified or not in the date string. If a time offset is not explicitly specified in the date string, the default time offset, obtained from the default time zone, is assumed. If the time offset is specified in the string, it is considered to be the effective offset (standard time zone offset adjusted, if necessary, with the daylight savings offset value).

Parsing the same time string with no explicit time offset, in two different time zones, will return two different results, because those timestamps correspond to two different UTC times. Note that the DateFormat instance is initialized with a TimeZone instance when it is constructed, and changing the default time zone of the JVM has no effect on the DateFormat after it was constructed.

DateFormat.format()

By default, a DateFormat instance accounts for the local time zone when formatting Date() instances. The Date() instance itself does not contain timezone information, it is an UTC timestamp, but in the process of formatting it, the DateFormat learns about the time zone and applies it in the formatted result:

SimpleDateFormat LOCAL_TIME_ZONE_DATE_FORMAT = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssX");
LOCAL_TIME_ZONE_DATE_FORMAT.format(new Date());

produces:

2018-11-12T13:34:45-08

To display the same timestamp as UTC, set the UTC timezone on the DateFormat instance:

SimpleDateFormat UTC_DATE_FORMAT = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssX");
UTC_DATE_FORMAT.setTimeZone(TimeZone.getTimeZone("UTC"));
UTC_DATE_FORMAT.format(new Date());

This produces:

2018-11-12T21:34:45Z

Example:

Playground Java Time ISO 8601 Example

Access to TimeZone Format Specification

Access to time zone information in the format instance (when specified in the format string): there is no obvious way to get what kind of time zone format was requested when building the DateFormat – no typed access to the internal state.

Time Zone and Time Zone Offset Format Specifications

Java SimpleDateFormat

z

General time zone: “Pacific Standard Time” “PST” “GMT-08:00”

Z

This indicates that the RFC 822 time zone format is being used.

A single "Z" is sufficient, there is no need for four or five.

This is PDT - the Pacific Daylight Time, which is PST (-0800) with daylight saving in effect (+0100).

15/01/01 01:01:01-0700
15/01/01 01:01:01 -0700

Note that time zone in the Pacific time zone can be -7 or -8 depending on whether the daylight saving time is in effect.

X

This indicates that ISO 8601 time zone format is being used: -08 -0800 -08:00. More details:

ISO 8601 Time Zone Designators

Example: "2015-09-22T18:03:46Z" is an ISO-8601 timestamp and can be parsed by:

new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssX")

Calendar

https://docs.oracle.com/javase/10/docs/api/java/util/Calendar.html

The Calendar class is an abstract class that provides methods for converting between a specific instant in time, represented as a millisecond value counted from the Epoch to a set of calendar fields such as YEAR, MONTH, DAY_OF_MONTH, HOUR, etc. The Calendar instance can also be used for manipulating the calendar fields, such as getting the date of the next week. The millisecond POSIX time can be obtained from the Calendar instance with Calendar.getTime() or Calendar.getTimeInMillis().

GregorianCalendar

https://docs.oracle.com/javase/10/docs/api/java/util/GregorianCalendar.html

Also see

Gregorian Calendar