tl;dr
Convert your obsolete java.util.Date
objects to their replacement, java.time.Instant
. Then calculate the elapsed time as a Duration
.
Duration d =
Duration.between( // Calculate the span of time between two moments as a number of hours, minutes, and seconds.
myJavaUtilDate.toInstant() , // Convert legacy class to modern class by calling new method added to the old class.
Instant.now() // Capture the current moment in UTC. About two and a half hours later in this example.
)
;
d.toString(): PT2H34M56S
d.toMinutes(): 154
d.toMinutesPart(): 34
ISO 8601 Format: PnYnMnDTnHnMnS
The sensible standard ISO 8601 defines a concise textual representation of a span of time as a number of years, months, days, hours, etc. The standard calls such such a span a duration. The format is PnYnMnDTnHnMnS
where the P
means "Period", the T
separates the date portion from the time portion, and in between are numbers followed by a letter.
Examples:
P3Y6M4DT12H30M5S
three years, six months, four days, twelve hours, thirty minutes, and five seconds
PT4H30M
Four and a half hours
java.time
The java.time framework built into Java 8 and later supplants the troublesome old java.util.Date
/java.util.Calendar
classes. The new classes are inspired by the highly successful Joda-Time framework, intended as its successor, similar in concept but re-architected. Defined by JSR 310. Extended by the ThreeTen-Extra project. See the Tutorial.
Moment
The Instant
class represents a moment on the timeline in UTC with a resolution of nanoseconds (up to nine (9) digits of a decimal fraction).
Instant instant = Instant.now() ; // Capture current moment in UTC.
Best to avoid the legacy classes such as Date
/Calendar
. But if you must inter-operate with old code not yet updated to java.time, convert back and forth. Call new conversion methods added to the old classes. For moving from a java.util.Date
to an Instant
, call Date::toInstant
.
Instant instant = myJavaUtilDate.toInstant() ; // Convert from legacy `java.util.Date` class to modern `java.time.Instant` class.
Span of time
The java.time classes have split this idea of representing a span of time as a number of years, months, days, hours, minutes, seconds into two halves:
Period
for years, months, days
Duration
for days, hours, minutes, seconds
Here is an example.
ZoneId zoneId = ZoneId.of ( "America/Montreal" );
ZonedDateTime now = ZonedDateTime.now ( zoneId );
ZonedDateTime future = now.plusMinutes ( 63 );
Duration duration = Duration.between ( now , future );
Dump to console.
Both Period
and Duration
use the ISO 8601 standard for generating a String representation of their value.
System.out.println ( "now: " + now + " to future: " + now + " = " + duration );
now: 2015-11-26T00:46:48.016-05:00[America/Montreal] to future: 2015-11-26T00:46:48.016-05:00[America/Montreal] = PT1H3M
Java 9 adds methods to Duration
to get the days part, hours part, minutes part, and seconds part.
You can get the total number of days or hours or minutes or seconds or milliseconds or nanoseconds in the entire Duration.
long totalHours = duration.toHours();
In Java 9 the Duration
class gets new methods for returning the various parts of days, hours, minutes, seconds, milliseconds/nanoseconds. Call the to…Part
methods: toDaysPart()
, toHoursPart()
, and so on.
ChronoUnit
If you only care about a simpler larger granularity of time, such as “number of days elapsed”, use the ChronoUnit
enum.
long daysElapsed = ChronoUnit.DAYS.between( earlier , later );
Another example.
Instant now = Instant.now();
Instant later = now.plus( Duration.ofHours( 2 ) );
…
long minutesElapsed = ChronoUnit.MINUTES.between( now , later );
120
About java.time
The java.time framework is built into Java 8 and later. These classes supplant the troublesome old legacy date-time classes such as java.util.Date
, Calendar
, & SimpleDateFormat
.
The Joda-Time project, now in maintenance mode, advises migration to java.time.
To learn more, see the Oracle Tutorial. And search Stack Overflow for many examples and explanations. Specification is JSR 310.
Where to obtain the java.time classes?
- Java SE 8 and SE 9 and later
- Built-in.
- Part of the standard Java API with a bundled implementation.
- Java 9 adds some minor features and fixes.
- Java SE 6 and SE 7
- Much of the java.time functionality is back-ported to Java 6 & 7 in ThreeTen-Backport.
- Android
The ThreeTen-Extra project extends java.time with additional classes. This project is a proving ground for possible future additions to java.time. You may find some useful classes here such as Interval
, YearWeek
, YearQuarter
, and more.
Joda-Time
UPDATE: The Joda-Time project is now in maintenance mode, with the team advising migration to the java.time classes. I leave this section intact for history.
The Joda-Time library uses ISO 8601 for its defaults. Its Period
class parses and generates these PnYnMnDTnHnMnS strings.
DateTime now = DateTime.now(); // Caveat: Ignoring the important issue of time zones.
Period period = new Period( now, now.plusHours( 4 ).plusMinutes( 30));
System.out.println( "period: " + period );
Renders:
period: PT4H30M
Date
,Calendar
, andSimpleDateFormat
”. – Basil Bourquejava.time.Period
and/orDuration
. See Basil Bourque’s answer below. – Ole V.V.