The Highly Useful Java ChronoUnit Enum

Several years ago, I published the blog post "The Highly Useful Java TimeUnit Enum" that looked at the TimeUnit enum introduced with JDK 5. JDK 8 introduced a newer enum, ChronoUnit, that is better suited than TimeUnit for contexts other than concurrency such as date/time manipulations.

Located in the java.time.temporal package, the ChronoUnit class implements the TemporalUnit interface, an interface used extensively in the highly desired JDK 8-introduced Date/Time API. The blog post "Days Between Dates in Java 8" demonstrates use of this class to calculate periods of time between two instances of Temporal.

The blog post "Java 9. Where 'forever' is hard coded." looks at "two new methods in the TimeUnit class" for JDK 9. These methods, toChronoUnit() and of(ChronoUnit), support translation of TimeUnit to a ChronoUnit and translation of ChronoUnit to TimeUnit. Not all values in ChronoUnit can be translated to an equivalent in TimeUnit, in which cases an IllegalArgumentException is thrown.

The Javadoc comments on each value in ChronoUnit describe what unit of time each value represents. However, it's interesting to me to see what Duration is returned for each value in ChronoUnit. The following code snippet will write these Duration's toString() representations to standard output for all values in the ChronoUnit enum.

Displaying Durations of ChronoUnits

for (final ChronoUnit unit : ChronoUnit.values())
{
   final Duration duration = unit.getDuration();
   out.println(unit + ": " + duration + " (" + duration.getSeconds() + " seconds)");
}

When executed, the above code produces the following output:

Nanos: PT0.000000001S (0 seconds)
Micros: PT0.000001S (0 seconds)
Millis: PT0.001S (0 seconds)
Seconds: PT1S (1 seconds)
Minutes: PT1M (60 seconds)
Hours: PT1H (3600 seconds)
HalfDays: PT12H (43200 seconds)
Days: PT24H (86400 seconds)
Weeks: PT168H (604800 seconds)
Months: PT730H29M6S (2629746 seconds)
Years: PT8765H49M12S (31556952 seconds)
Decades: PT87658H12M (315569520 seconds)
Centuries: PT876582H (3155695200 seconds)
Millennia: PT8765820H (31556952000 seconds)
Eras: PT8765820000000H (31556952000000000 seconds)
Forever: PT2562047788015215H30M7.999999999S (9223372036854775807 seconds)

The "PT" prefix on each of the Duration's string representations shown above indicates that the representation is a "period" duration designation ("P") and a "time" designation ("T") per the ISO-8601 standard. The "S", "M", and "H" are seconds, minutes, and hours respectively. The values of ChronoUnit that represent time units less than a second (NANOS, MICROS, and MILLIS) show "0 seconds" because they are less than 1 second and the returned value is an integral long.

The Javadoc comments on each value defined in the ChronoUnit class are well written. They follow what in my mind is a Javadoc "best practice": place a concise but informative initial sentence in the Javadoc to show up in the "Method Summary" section of the generated HTML page and place additional useful details in sentences after that initial summary sentence. For example, the Javadoc comment for ChronoUnit.ERAS states, "Unit that represents the concept of an era. The ISO calendar system doesn't have eras thus it is impossible to add an era to a date or date-time. The estimated duration of the era is artificially defined as 1,000,000,000 Years. When used with other calendar systems there are no restrictions on the unit." The bolded sentence (I added that emphasis) is what shows up in the "Method Summary" and the entire text shown here is displayed above the method in its complete explanation.

One of the more interesting values in the ChronoUnit enum is FOREVER. As the output of the code listing above demonstrated, the FOREVER value has a Duration of "PT2562047788015215H30M7.999999999S", corresponding to 2562047788015215 hours, 30 minutes, and 7.999999999 seconds. Or, as Grzegorz Gajos expresses it, "Java defines forever as 9 223 372 036 854 775 807 seconds. Which is 2.92277266 × 10¹¹ years. Better be sure to schedule Java upgrade in your application before times run out."

When would ChronoUnit.FOREVER be useful? Its Javadoc-based description explains its primary reason for existence: "Artificial unit that represents the concept of forever. This is primarily used with TemporalField to represent unbounded fields such as the year or era. The estimated duration of the era is artificially defined as the largest duration supported by Duration."

TimeUnit is a useful enum for working with Java's concurrency constructs and could be used in contexts other than concurrency as long as some severe limitations for these other contexts were considered. The JDK 8-introduced ChronoUnit is a better enum for these non-concurrency contexts and is especially designed for use with the JDK 8 Date/Time API.