How to Calculate “Time Ago” in Java

1. Overview

Calculating relative time and the duration between two points in time is a common use case in software systems. For instance, we might want to show the user how much time has passed since an event like posting a new picture on a social media platform. Examples of such “time ago” text are ” “5 minutes ago”, “1 year ago” etc.

While the semantics and choosing of the words are completely context-dependent, the overall idea is the same.

In this tutorial, we’ll explore several solutions for calculating time ago in Java. Due to the introduction of new Date and Time API in Java 8, we’ll discuss the solutions for version 7 and version 8 separately.

2. Java Version 7

There are several classes related to time in Java 7. Moreover, due to the shortcomings of Java 7 Date API, several third-party time and date libraries are also available.

First, let’s use pure Java 7 to calculate “time ago”.

2.1. Pure Java 7

We define an enum that holds different time granularities and converts them to milliseconds:

public enum TimeGranularity {
    SECONDS {
        public long toMillis() {
            return TimeUnit.SECONDS.toMillis(1);
        }
    }, MINUTES {
        public long toMillis() {
            return TimeUnit.MINUTES.toMillis(1);
        }
    }, HOURS {
        public long toMillis() {
            return TimeUnit.HOURS.toMillis(1);
        }
    }, DAYS {
        public long toMillis() {
            return TimeUnit.DAYS.toMillis(1);
        }
    }, WEEKS {
        public long toMillis() {
            return TimeUnit.DAYS.toMillis(7);
        }
    }, MONTHS {
        public long toMillis() {
            return TimeUnit.DAYS.toMillis(30);
        }
    }, YEARS {
        public long toMillis() {
            return TimeUnit.DAYS.toMillis(365);
        }
    }, DECADES {
        public long toMillis() {
            return TimeUnit.DAYS.toMillis(365 * 10);
        }
    };

    public abstract long toMillis();
}

We’ve used java.util.concurrent.TimeUnit enum which is a powerful tool for time conversion. Using TimeUnit enum, we override the toMillis() abstract method for each value of the TimeGranularity enum so that it returns the number of milliseconds equivalent to each value. For example, for “decade”, it returns the number of milliseconds for 3650 days.

As a result of defining TimeGranularity enum, we can define two methods. The first one takes a java.util.Date object and an instance of TimeGranularity and returns a “time ago” string:

static String calculateTimeAgoByTimeGranularity(Date pastTime, TimeGranularity granularity) {
    long timeDifferenceInMillis = getCurrentTime() - pastTime.getTime();
    return timeDifferenceInMillis / granularity.toMillis() + " " + 
      granularity.name().toLowerCase() + " ago";
}

This method divides the difference of current time and the given time by the TimeGranularity value in milliseconds. Consequently, we can roughly calculate the amount of time that has passed since the given time in the specified time granularity.

We used the getCurrentTime() method in order to get the current time. For testing, we return a fixed point of time and avoid reading time from the local machine. In practice, this method would return the real value of current time using System.currentTimeMillis() or LocalDateTime.now().

Let’s test the method:

Assert.assertEquals("5 hours ago", 
  TimeAgoCalculator.calculateTimeAgoByTimeGranularity(
    new Date(getCurrentTime() - (5 * 60 * 60 * 1000)), TimeGranularity.HOURS));

Furthermore, we can also write a method that automatically detects the largest suitable time granularity and returns a more human-friendly output:

static String calculateHumanFriendlyTimeAgo(Date pastTime) {
    long timeDifferenceInMillis = getCurrentTime() - pastTime.getTime();
    if (timeDifferenceInMillis / TimeGranularity.DECADES.toMillis() > 0) {
        return "several decades ago";
    } else if (timeDifferenceInMillis / TimeGranularity.YEARS.toMillis() > 0) {
        return "several years ago";
    } else if (timeDifferenceInMillis / TimeGranularity.MONTHS.toMillis() > 0) {
        return "several months ago";
    } else if (timeDifferenceInMillis / TimeGranularity.WEEKS.toMillis() > 0) {
        return "several weeks ago";
    } else if (timeDifferenceInMillis / TimeGranularity.DAYS.toMillis() > 0) {
        return "several days ago";
    } else if (timeDifferenceInMillis / TimeGranularity.HOURS.toMillis() > 0) {
        return "several hours ago";
    } else if (timeDifferenceInMillis / TimeGranularity.MINUTES.toMillis() > 0) {
        return "several minutes ago";
    } else {
        return "moments ago";
    }
}

Now, let’s look at a test to see an example usage:

Assert.assertEquals("several hours ago", 
  TimeAgoCalculator.calculateHumanFriendlyTimeAgo(new Date(getCurrentTime() - (5 * 60 * 60 * 1000))));

According to the context, we can use different words such as “few”, “several”, “many”, or even the exact value.

2.2. Joda-Time Library

Before the release of Java 8, Joda-Time was the de facto standard for various time and date-related operations in Java. We can use three classes of the Joda-Time library to calculate “time ago”:

• org.joda.time.Period which takes two objects of org.joda.time.DateTime and calculates the difference between these two points of time
• org.joda.time.format.PeriodFormatter which defines the format for printing the Period object
• org.joda.time.format.PeriodFormatuilder which is a builder class to create a custom PeriodFormatter

We can use these three classes to easily get the exact time between now and a time in the past:

static String calculateExactTimeAgoWithJodaTime(Date pastTime) {
    Period period = new Period(new DateTime(pastTime.getTime()), new DateTime(getCurrentTime()));
    PeriodFormatter formatter = new PeriodFormatterBuilder().appendYears()
      .appendSuffix(" year ", " years ")
      .appendSeparator("and ")
      .appendMonths()
      .appendSuffix(" month ", " months ")
      .appendSeparator("and ")
      .appendWeeks()
      .appendSuffix(" week ", " weeks ")
      .appendSeparator("and ")
      .appendDays()
      .appendSuffix(" day ", " days ")
      .appendSeparator("and ")
      .appendHours()
      .appendSuffix(" hour ", " hours ")
      .appendSeparator("and ")
      .appendMinutes()
      .appendSuffix(" minute ", " minutes ")
      .appendSeparator("and ")
      .appendSeconds()
      .appendSuffix(" second", " seconds")
      .toFormatter();
    return formatter.print(period);
}

Let’s see a sample usage:

Assert.assertEquals("5 hours and 1 minute and 1 second", 
  TimeAgoCalculator.calculateExactTimeAgoWithJodaTime(new Date(getCurrentTime() - (5 * 60 * 60 * 1000 + 1 * 60 * 1000 + 1 * 1000))));

It’s also possible to generate a more human-friendly output:

static String calculateHumanFriendlyTimeAgoWithJodaTime(Date pastTime) {
    Period period = new Period(new DateTime(pastTime.getTime()), new DateTime(getCurrentTime()));
    if (period.getYears() != 0) {
        return "several years ago";
    } else if (period.getMonths() != 0) {
        return "several months ago";
    } else if (period.getWeeks() != 0) {
        return "several weeks ago";
    } else if (period.getDays() != 0) {
        return "several days ago";
    } else if (period.getHours() != 0) {
        return "several hours ago";
    } else if (period.getMinutes() != 0) {
        return "several minutes ago";
    } else {
        return "moments ago";
    }
}

We can run a test to see that this method returns a more human-friendly “time ago” string:

Assert.assertEquals("several hours ago", 
  TimeAgoCalculator.calculateHumanFriendlyTimeAgoWithJodaTime(new Date(getCurrentTime() - (5 * 60 * 60 * 1000))));

Again, we can use different terms such as “one”, “few”, or “several”, depending on the use case.

2.3. Joda-Time TimeZone

It’s pretty straightforward to add a time zone in the calculation of “time ago” using the Joda-Time library:

String calculateZonedTimeAgoWithJodaTime(Date pastTime, TimeZone zone) {
    DateTimeZone dateTimeZone = DateTimeZone.forID(zone.getID());
    Period period = new Period(new DateTime(pastTime.getTime(), dateTimeZone), new DateTime(getCurrentTimeByTimeZone(zone)));
    return PeriodFormat.getDefault().print(period);
}

The getCurrentTimeByTimeZone() method returns the value of the current time in the specified timezone. For testing, this method returns a fixed point of time, but in practice, this should return the real value of the current time using Calendar.getInstance(zone).getTimeInMillis() or LocalDateTime.now(zone).

3. Java 8

Java 8 introduced a new improved Date and Time API, which adopted many ideas from the Joda-Time library. We can use native java.time.Duration and java.time.Period classes to calculate “time ago”:

static String calculateTimeAgoWithPeriodAndDuration(LocalDateTime pastTime, ZoneId zone) {
    Period period = Period.between(pastTime.toLocalDate(), getCurrentTimeByTimeZone(zone).toLocalDate());
    Duration duration = Duration.between(pastTime, getCurrentTimeByTimeZone(zone));
    if (period.getYears() != 0) {
        return "several years ago";
    } else if (period.getMonths() != 0) {
        return "several months ago";
    } else if (period.getDays() != 0) {
        return "several days ago";
    } else if (duration.toHours() != 0) {
        return "several hours ago";
    } else if (duration.toMinutes() != 0) {
        return "several minutes ago";
    } else if (duration.getSeconds() != 0) {
        return "several seconds ago";
    } else {
        return "moments ago";
    }
}

The above code snippet supports time zone and uses native Java 8 API only.

4. PrettyTime Library

PrettyTime is a powerful library that specifically offers “time ago” functionality with i18n support. Also, it’s highly customizable, easy to use, and can be used with both Java versions 7 and 8.

First, let’s add its dependency to our pom.xml:

<dependency>
    <groupId>org.ocpsoft.prettytime</groupId>
    <artifactId>prettytime</artifactId>
    <version>3.2.7.Final</version>
</dependency>

Now getting “time ago” in a human-friendly format is pretty easy:

String calculateTimeAgoWithPrettyTime(Date pastTime) {
    PrettyTime prettyTime = new PrettyTime();
    return prettyTime.format(pastTime);
}

5. Time4J Library

Finally, Time4J is another great library for the manipulation of time and date data in Java. It has a PrettyTime class which can be used to calculate time ago.

Let’s add its dependencies:

<dependency>
    <groupId>net.time4j</groupId>
    <artifactId>time4j-base</artifactId>
    <version>5.9</version>
</dependency>
<dependency>
    <groupId>net.time4j</groupId>
    <artifactId>time4j-sqlxml</artifactId>
    <version>5.8</version>
</dependency>

After adding this dependency, calculating the time ago is pretty straightforward:

String calculateTimeAgoWithTime4J(Date pastTime, ZoneId zone, Locale locale) {
    return PrettyTime.of(locale).printRelative(pastTime.toInstant(), zone);
}

Same as the PrettyTime library, Time4J also supports i18n out of the box.

6. Conclusion

In this article, we discussed different methods for calculating time ago in Java.

There are solutions for both pure Java and third-party libraries. Since a new Date and Time API was introduced in Java 8, pure java solutions are different for versions before and after 8.

As always, the source code for the examples is available over on GitHub.