Format a Milliseconds Duration to HH:MM:SS

1. Overview

Duration is an amount of time expressed in terms of hours, minutes, seconds, milliseconds, and so on. We may wish to format a duration into some particular time pattern.

We can achieve this either by writing custom code with the help of some JDK libraries or by making use of third-party libraries.

In this quick tutorial, we'll look at how to write simple code to format a given duration to HH:MM:SS format.

2. Java Solutions

There are multiple ways a duration can be expressed — for example, in minutes, seconds, and milliseconds, or as a Java Duration, which has its own specific format.

This section and subsequent sections will focus on formatting intervals (elapsed time), specified in milliseconds, to HH:MM:SS using some JDK libraries. For the sake of our examples, we'll be formatting 38114000ms as 10:35:14 (HH:MM:SS).

2.1. Duration

As of Java 8, the Duration class was introduced to handle intervals of time in various units. The Duration class comes with a lot of helper methods to get the hours, minutes, and seconds from a duration.

To format an interval to HH:MM:SS using the Duration class, we need to initialize the Duration object from our interval using the factory method ofMillis found in the Duration class. This converts the interval to a Duration object that we can work with:

Duration duration = Duration.ofMillis(38114000);

For ease of calculation from seconds to our desired units, we need to get the total number seconds in our duration or interval:

long seconds = duration.getSeconds();

Then, once we have the number of seconds, we generate the corresponding hours, minutes, and seconds for our desired format:

long HH = seconds / 3600;
long MM = (seconds % 3600) / 60;
long SS = seconds % 60;

Finally, we format our generated values:

String timeInHHMMSS = String.format("%02d:%02d:%02d", HH, MM, SS);

Let's try this solution out:

assertThat(timeInHHMMSS).isEqualTo("10:35:14");

If we're using Java 9 or later, we can use some helper methods to get the units directly without having to perform any calculations:

long HH = duration.toHours();
long MM = duration.toMinutesPart();
long SS = duration.toSecondsPart();
String timeInHHMMSS = String.format("%02d:%02d:%02d", HH, MM, SS);

The above snippet will give us the same result as tested above:

assertThat(timeInHHMMSS).isEqualTo("10:35:14");

2.2. TimeUnit

Just like the Duration class discussed in the previous section, TimeUnit represents a time at a given granularity. It provides some helper methods to convert across units – which in our case would be hours, minutes, and seconds – and to perform timing and delay operations in these units.

To format a duration in milliseconds to the format HH:MM:SS, all we need to do is to use the corresponding helper methods in TimeUnit:

long HH = TimeUnit.MILLISECONDS.toHours(38114000);
long MM = TimeUnit.MILLISECONDS.toMinutes(38114000) % 60;
long SS = TimeUnit.MILLISECONDS.toSeconds(38114000) % 60;

Then, format the duration based on generated units above:

String timeInHHMMSS = String.format("%02d:%02d:%02d", HH, MM, SS);
assertThat(timeInHHMMSS).isEqualTo("10:35:14");

3. Using Third-Party Libraries

We may choose to try a different route by using third-party library methods rather than writing our own.

3.1. Apache Commons

To use Apache Commons, we need to add commons-lang3 to our project:

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.12.0</version>
</dependency>

As expected, this library has formatDuration as well as other unit formatting methods in its DurationFormatUtils class:

String timeInHHMMSS = DurationFormatUtils.formatDuration(38114000, "HH:MM:SS", true);
assertThat(timeInHHMMSS).isEqualTo("10:35:14");

3.2. Joda Time

The Joda Time library comes in handy when we're using a Java version prior to Java 8 because of its handy helper methods to represent and format units of time. To use Joda Time, let's add the joda-time dependency to our project:

<dependency>
    <groupId>joda-time</groupId>
    <artifactId>joda-time</artifactId>
    <version>2.10.10</version>
</dependency>

Joda Time has a Duration class to represent time. First, we convert the interval in milliseconds to an instance of the Joda Time Duration object:

Duration duration = new Duration(38114000);

Then, we get the period from the duration above using the toPeriod method in Duration, which converts or initializes it to an instance of the Period class in Joda Time:

Period period = duration.toPeriod();

We get the units (hours, minutes, and seconds) from Period using its corresponding helper methods:

long HH = period.getHours();
long MM = period.getMinutes();
long SS = period.getSeconds();

Finally, we can format the duration and test the result:

String timeInHHMMSS = String.format("%02d:%02d:%02d", HH, MM, SS);
assertThat(timeInHHMMSS).isEqualTo("10:35:14");

4. Conclusion

In this tutorial, we've learned how to format a duration to a specific format (HH:MM:SS, in our case).

First, we used Duration and TimeUnit classes that come with Java to get the required units and format them with the help of Formatter.

Finally, we looked at how to use some third-party libraries to achieve the result.

As usual, the complete source code is available over on GitHub.